Merge pull request #93 from c4dt/cleanup

docs: cleaned up README, removed obsolete files and updated .env.example

.env.example

@@ -1,18 +1,21 @@
 # This is an example .env file with default passwords and private keys.
 # Do not use this in production or with any public-facing ports!
-DELA_PROXY_URL=http://172.19.44.254:8080
+BACKEND_HOST=backend                                    # name of the 'backend' container
+BACKEND_PORT=5000                                       # port of the 'backend' container
+COMPOSE_FILE=./docker-compose/docker-compose.yml        # Docker Compose configuration file to use
+DATABASE_HOST=db                                        # name of the PostgreSQL container
+DATABASE_PASSWORD=Ohw0phoa                              # choose any PostgreSQL password
+DATABASE_PORT=5432                                      # port of the PostgreSQL container
 DATABASE_USERNAME=dvoting
-DATABASE_PASSWORD=Ohw0phoa                  # choose any PostgreSQL password
-DATABASE_HOST=db
-DATABASE_PORT=5432
-DB_PATH=dvoting                             # LMDB database path
-FRONT_END_URL=http://127.0.0.1:3000         # the automated frontend tests expect this value do not change it
-BACKEND_HOST=backend
-BACKEND_PORT=5000
-SESSION_SECRET=kaibaaF9                     # choose any secret
+DB_PATH=dvoting                                         # LMDB database path
+DELA_PROXY_URL=http://172.19.44.254:8080                # IP and port of one of the DELA containers
+FRONT_END_URL=http://127.0.0.1:3000                     # the automated frontend tests expect this value do not change it
+NODEPORT=2000                                           # DELA node port
 # For public-facing services and production, this key needs to be changed!
 PRIVATE_KEY=6aadf480d068ac896330b726802abd0da2a5f3824f791fe8dbd4cd555e80b809
+PROXYPORT=8080                                          # DELA proxy port
 PUBLIC_KEY=3e5fcaed4c5d79a8eccceeb087ee0a13b8f91d917ed62017a9cd28e13b228389
-PROXYPORT=8080
-NODEPORT=2000                               # DELA node port
-
+REACT_APP_DEV_LOGIN=true                                # debugging admin login /!\ disable in production /!\
+REACT_APP_RANDOMIZE_VOTE_ID=true                        # randomize voter ID for debugging /!\ disable in production /!\
+REACT_APP_SCIPER_ADMIN=123456                           # debugging admin ID /!\ disable in production /!\
+SESSION_SECRET=kaibaaF9                                 # choose any secret

README.docker.md

@@ -8,96 +8,66 @@ The files related to the Docker environment can be found in
 * `Dockerfiles/` (Dockerfiles)
 * `scripts/` (helper scripts)
 
-You also need to either create a `.env` file in the project's root
-or point to another environment file using the `--env-file` flag
-when running `docker compose`.
+### Setup
 
-The environment file needs to contain
+It is recommended to use the `run_docker.sh` helper script for setting up and
+tearing down the environment as it handles all the necessary intermediary steps
+to have a working D-Voting application.
 
-```
-DELA_PROXY_URL=http://172.19.44.254:8080
-DATABASE_USERNAME=dvoting
-DATABASE_PASSWORD=XXX                       # choose any PostgreSQL password
-DATABASE_HOST=db
-DATABASE_PORT=5432
-DB_PATH=dvoting                             # LMDB database path
-FRONT_END_URL=http://127.0.0.1:3000         # the automated frontend tests expect this value do not change it
-BACKEND_HOST=backend
-BACKEND_PORT=5000
-SESSION_SECRET=XXX                          # choose any secret
-PUBLIC_KEY=XXX                              # public key of pre-generated key pair
-PRIVATE_KEY=XXX                             # private key of pre-generated key pair
-PROXYPORT=8080
-NODEPORT=2000                               # DELA node port
-```
+This script needs to be executed at the project's root.
 
-For the `PUBLIC_KEY` and `PRIVATE_KEY`, you need to run the following commands:
+To set up the environment:
 
-```bash
-cd web/backend
-npm ci
-npm run keygen
+```
+./scripts/run_docker.sh
 ```
 
-And then copy the two lines to the `.env` file.
-
-There are two Docker Compose file you may use:
+This will run the subcommands:
 
-* `docker-compose/docker-compose.yml` for the preprod version, or
-* `docker-compose/docker-compose.debug.yml` for the development/debugging version
+- `setup` which will build the images and start the containers
+- `init_dela` which will initialize the DELA network
+- `local_admin` which will add local admin accounts for testing and debugging
+- `local_login` which will set a local cookie that allows for interacting w/ the API via command-line
+- `add_proxies` which will set up the DELA node proxies
 
-You run
+Each of these subcommands can also be run by invoking the script w/ the subcommand:
 
 ```
-export COMPOSE_FILE=<path to Docker Compose file>
+./scripts/run_docker.sh <subcommand>
 ```
 
-The preprod version will create an environment without any debugging tools that's as close as possible to a real environment.
-It is meant to be used to test the `main` branch before deploying it to production. Use the development/debugging version
-for setting up your local development environment.
+/!\ The `init_dela` subcommand must only be run exactly **once**.
 
-Run
+To tear down the environment:
 
 ```
-docker compose build
-docker compose up
+./scripts/run_docker.sh teardown
 ```
 
-to set up the environment.
-
-/!\ Any subsequent `docker compose` commands must be run with `COMPOSE_FILE` being
-set to the Docker Compose file that defines the current environment.
-
-Use
+This will:
 
-```
-docker compose down
-```
+- remove the local cookie
+- stop and remove the containers and their attached volumes
+- remove the images
 
-to shut off, and
+/!\ This command is meant to reset your environment. If you want to stop one or more
+containers, use the appropriate `docker compose` commands (see below for using the correct `docker-compose.yml`).
 
-```
-docker compose down -v
-```
+### Docker environment
 
-to delete the volumes and reset your instance.
+There are two Docker Compose file you may use:
 
-## Post-install commands
+* `docker-compose/docker-compose.yml` (recommended, default in `.env.example` and `run_docker.sh`), or
+* `docker-compose/docker-compose.debug.yml`, which contains some additional debugging tools
 
-To set up the DELA network, go to `scripts/` and run
+To run `docker compose` commands w/ the right `docker-compose.yml`, you need to either run
 
 ```
-./init_dela.sh
+export COMPOSE_FILE=<path to Docker Compose file>
 ```
 
-/!\ This script uses `docker compose` as well, so make sure that the `COMPOSE_FILE` variable is
-set to the right value.
-
-To set up the permissions, run
+or
 
 ```
-docker compose exec backend npx cli addAdmin --sciper XXX
-docker compose down && docker compose up -d
+source .env
 ```
-
-to add yourself as admin and clear the cached permissions.