Review the setup with docker compose

.env

@@ -1,20 +1,37 @@
+# Environment configuration file.
+# Copy this file to `.env.local` and fill the latter with your own configuration.
+# Best not edit this file directly.  See README.md
+
+# You can put pretty much any string in here but it can't be empty.
+# It is used to generate the web tokens.  Make sure this stays secret.
 SECRET=
 
+# Configure the postgres database.
+# The database password may not be empty.
 DB_NAME=mj
 DB_HOST=mj_db
 DB_PORT=5433
 DB_USER=mj
 DB_PASS=
 
-DOMAIN=
+# Put your online domain name here, such as "mieuxvoter.fr" for example.
+DOMAIN=localhost
+
+# Various admin reports may be sent at this email address.
 EMAIL=
+
+# Eg: "Europe/Paris"
 TIMEZONE=
 
+# User Id of the owner of the uploaded images via imgpush.
+PUID=1000
+
 # This is used by restic's backup
 SMTP_HOST=
 SMTP_USER=
 SMTP_PASS=
 
+# Restic is a backup engine on AWS, disabled for now (see docker compose file).
 RESTIC_REPOSITORY=s3:s3.amazonaws.com/your-bucket
 RESTIC_PASSWORD=
 RESTIC_SEND_MAIL=

.gitignore

@@ -1,11 +1,22 @@
-__pycache__/
+# Temporary files
 *.swp
 *.mo
 .#*
-.ipynb_checkpoints/
-.env.local
+
 backup
-.venv/
+
+# Python
+__pycache__/
+.mypy_cache
+.ipynb_checkpoints/
+/.venv/
+
+# Local (secret) configuration
+/.env.local
+
+# Databases (dumps?)
 test.db
 main.db
-.mypy_cache
+
+# IDE
+/.idea/

README.md

@@ -1,8 +1,10 @@
-# API for Mieux Voter
+# Majority Judgment App Server in Python
 
-This API allows you to create elections, vote and obtain results with [majority judgment](https://en.wikipedia.org/wiki/Majority_judgment).
+> This is the REST API Backend for the Mieux Voter Online WebApp.
+
+You can use our instance of this at [api.mieuxvoter.fr/](https://api.mieuxvoter.fr/).
 
-You can use our server at [api.mieuxvoter.fr/](api.mieuxvoter.fr/).
+This API allows you to create elections, vote and obtain results with [majority judgment](https://en.wikipedia.org/wiki/Majority_judgment).
 
 Since our API relies on OpenAPI, documentation is automatically generated and it is available at [api.mieuxvoter.fr/redoc](api.mieuxvoter.fr/redoc) or [api.mieuxvoter.fr/docs](api.mieuxvoter.fr/docs).
 
@@ -11,32 +13,33 @@ Since our API relies on OpenAPI, documentation is automatically generated and it
 
 Copy the `.env` into `.env.local` with your own settings.
 
-Then launch the dockers with:
+Then launch the docker services with:
 
-`docker compose --profile all --env-file .env.local up -d`
+    docker compose --profile all --env-file .env.local up --detach
 
-Note that you can use the `profile` called `dashboard` if you only need Metabase, `image` if you only need to store images, or `backup` for restic.
+Note that you can use the `profile` called:
+- `core` if you only need the backend and database,
+- `dashboard` if you only need Metabase,
+- `image` if you only need to store images,
+- or `backup` for restic.
 
-You certainly want to apply databases migrations with:
+You certainly want to apply the database migrations with:
 
-`docker/migrate.sh`
+    ./docker/migrate.sh
 
 
 ## Run the tests
 
-`docker/test.sh`
+    ./docker/test.sh
 
 
 
 ## Local development
 
 1. Install [postgresql](https://www.postgresql.org/download/).
-
 2. Install python 3.11.
-
 3. Create a new virtual environment and activate it:
 
-
 ```bash
 venv .venv
 source .venv/bin/activate
@@ -60,23 +63,19 @@ POSTGRES_USER
 POSTGRES_PASSWORD
 ```
 
-(In docker, DB_* variables are injected to POSTGRES_* variables)
+> (In docker, `DB_*` variables are injected to `POSTGRES_*` variables)
 
-:warning: If your using launch.json on vscode, .env create a conflict. You need to remove it.
+:warning: If you're using `launch.json` on vscode, `.env` creates a conflict.  You need to remove it.
 
 6. Start the server:
 
 ```
 uvicorn app.main:app --reload --env-file .env.local
 ```
 
-7. Visit the generated documentation:
-
-```
-http://127.0.0.1:8000/redoc
-```
+7. Visit the generated documentation at http://127.0.0.1:8000/redoc
 
-If you need to alter the database, you can create new migrations using [alembic](https://alembic.sqlalchemy.org/en/latest/index.html).
+> If you need to alter the database, you can create new migrations using [alembic](https://alembic.sqlalchemy.org/en/latest/index.html).
 
 
 ## TODO