Deployment¶
AnnoTrain runs on one Linux machine with Docker. Four containers make up the stack:
| Service | Role |
|---|---|
db |
PostgreSQL 16: projects, media references, contributors, annotations |
backend |
FastAPI API; applies database migrations on start |
web |
nginx: serves the React app and proxies /api to the backend |
cloudflared |
Optional Cloudflare Tunnel: publishes the site without opening any port |
Only the web container is published, and only on 127.0.0.1. The outside world reaches it through the tunnel.
1. Configure¶
Edit .env: set POSTGRES_PASSWORD and ANNOTRAIN_ADMIN_TOKEN to long random values.
Warning
ANNOTRAIN_ADMIN_TOKEN protects project creation, uploads and exports. Keep .env out of git (it is already ignored).
2. Start¶
docker compose up -d --build
docker compose ps # all services should be "healthy" / "running"
curl http://127.0.0.1:8080/api/health
The first start builds the images and creates the database schema automatically.
3. Publish with Cloudflare Tunnel¶
- In the Cloudflare dashboard open Zero Trust → Networks → Tunnels → Create a tunnel and choose Cloudflared.
- Name it (for example
annotrain) and copy the tunnel token. - Put it in
.envasCLOUDFLARE_TUNNEL_TOKEN=.... - In the tunnel's Public Hostname tab add:
- Hostname:
annotrain.cmaslard.xyz - Service:
HTTP→web:80
- Hostname:
- Start the tunnel container:
Cloudflare creates the DNS record and the HTTPS certificate. The documentation site stays on docs.annotrain.cmaslard.xyz, so the application and its docs never collide.
4. Create a project and import images¶
The admin API and the command line do the same things; the command line is easier for bulk imports.
Put the images in a host folder and mount it read-only at /import by setting ANNOTRAIN_IMPORT_DIR in .env (default: ./data), then:
docker compose exec backend python -m app.cli create-project bt-2026 \
--name "Camera traps - Bioinformatics Tools" --visibility unlisted --target 3
docker compose exec backend python -m app.cli import-images bt-2026 /import
create-project uses the Animal / No animal / Unsure task by default; pass --from-json to define another one. Import is idempotent: identical files (by SHA-256) are stored once and never duplicated, even across projects.
For each image AnnoTrain keeps the untouched original and generates a lightweight web version (max 1600 px). Only the web version is ever sent to browsers.
Try it first
docker compose exec backend python -m app.cli seed-demo creates a demo project with generated images, useful to check the whole chain before real data is imported.
Admin API¶
Interactive documentation is served at /api/docs. Admin calls need the X-Admin-Token header:
curl -H "X-Admin-Token: $TOKEN" https://annotrain.cmaslard.xyz/api/admin/projects
curl -H "X-Admin-Token: $TOKEN" -X PATCH -H "Content-Type: application/json" \
-d '{"status": "closed"}' https://annotrain.cmaslard.xyz/api/admin/projects/bt-2026
Browser admin panel¶
/admin on the deployed site gives non-technical people (course assistants, colleagues) a way to create projects, change their settings, and download exports without touching the command line. It needs its own login, separate from ANNOTRAIN_ADMIN_TOKEN (which stays valid for scripts and curl, and always has full access regardless of any account's role): create one account per person who needs access, with a role:
- admin: everything, including deleting a project.
- researcher: create projects and change their settings, but cannot delete one.
docker compose exec backend python -m app.cli create-admin alice --email alice@example.com --role admin # prompts for a password
docker compose exec backend python -m app.cli create-admin bob --email bob@example.com --role researcher
docker compose exec backend python -m app.cli list-admins
docker compose exec backend python -m app.cli set-admin-role bob admin # promote/demote later
docker compose exec backend python -m app.cli set-admin-email alice alice@example.com # if added later
docker compose exec backend python -m app.cli delete-admin alice # revoke access
Signing in at /admin sets an HttpOnly session cookie (30 days); there is no self-service signup, so accounts are created through the CLI above. Once signed in, a person can change their own password from the panel; "forgot password" sends a one-hour reset link by email (needs the email set above and ANNOTRAIN_SMTP_* configured in .env - see .env.example; without SMTP configured, the link is printed to docker compose logs backend instead of emailed).
On a project's page (/admin/p/<slug>), "Add images" lets an admin or researcher import images straight from their own computer - no server access needed. Good for a researcher's own handful-to-hundreds of images; a bulk import of a large existing dataset is still better done via ANNOTRAIN_IMPORT_DIR above, since that never copies the originals at all. Uploaded originals are stored under ANNOTRAIN_ORIGINALS_DIR_HOST (see below) - the "web" thumbnail used for annotating stays local either way, so this never slows down the annotation screen.
5. Run a session¶
- Share
https://annotrain.cmaslard.xyz/p/bt-2026?s=BT2026. Thesparameter is the session code stored with each annotation, so different groups can be told apart afterwards. No account is required. - Project the live dashboard at
/p/bt-2026/live: annotation count, contributors, progress toward the target and the distribution of answers, refreshed every 3 seconds. - Each image is shown to contributors who have not annotated it yet, least-annotated first, until it reaches the target (default 3). Ties are broken randomly, so 40 simultaneous students spread over the pool.
Before the class¶
- [ ] Open the link on a phone over mobile data (not the campus network).
- [ ] Import enough images: with 40 students × 50 images and a target of 3, a pool of about 700 images is fully covered; a larger pool gives more variety.
- [ ] Do a rehearsal with a few colleagues and check
/live. - [ ] Take a backup (below) and prepare a fallback dataset and model in case the network fails.
6. Export the results¶
docker compose exec backend python -m app.cli export bt-2026 --out /tmp/export
docker compose cp backend:/tmp/export ./export
or download through the admin API:
curl -H "X-Admin-Token: $TOKEN" -o consensus.csv https://annotrain.cmaslard.xyz/api/admin/projects/bt-2026/export/consensus.csv
curl -H "X-Admin-Token: $TOKEN" -o annotations.csv https://annotrain.cmaslard.xyz/api/admin/projects/bt-2026/export/annotations.csv
consensus.csv has one row per image with the plurality label, the agreement (e.g. 0.6667 for 2 of 3), the per-label counts and a status:
| Status | Meaning |
|---|---|
consensus |
Enough annotations and a single winning label |
disputed |
Enough annotations but a tie for first place: candidates for review |
insufficient |
Fewer annotations than the project target |
unsure_only |
Everyone answered Unsure |
Unsure answers are kept in the raw history but do not vote. annotations.csv is the raw history (add ?include_revoked=true to also see answers that contributors undid); it is never replaced by the consensus.
Backups¶
dumps the database (compressed, dated) into ~/annotrain-backups/ and, when ANNOTRAIN_BACKUP_DIR is set in .env (ideally a folder on a NAS), copies it there too along with the stored files (painted masks...) and the trained models. Database dumps are kept 14 days (ANNOTRAIN_BACKUP_KEEP_DAYS); stored files and models are copied new and changed files only and never deleted from the backup folder. Image caches are skipped (storage/web, storage/variants, the trainers' image_cache): they're rebuilt from the original images, which should live on the NAS already (ANNOTRAIN_ORIGINALS_DIR_HOST). If anything fails, the script exits with an error and emails the admin accounts that have an email address.
Run it every night with cron (crontab -e as the user that runs Docker):
and also by hand before a risky change (a migration, an upgrade).
The dumps hold the accounts' emails and password hashes: keep the backup folder readable by you only.
To restore the database, into an empty one (this erases the current one):
docker compose stop backend ml ml-cluster
docker compose exec -T db psql -U annotrain -d postgres -c "DROP DATABASE annotrain" -c "CREATE DATABASE annotrain OWNER annotrain"
gunzip -c ~/annotrain-backups/db-YYYYMMDD-HHMMSS.sql.gz | docker compose exec -T db psql -q -U annotrain annotrain
docker compose up -d
and the stored files and models, from the backup folder, as the user the backend runs as
(ANNOTRAIN_BACKEND_UID/GID in .env, 10001 by default):
docker run --rm -u 10001:10001 -v annotrain_storage:/data/storage -v annotrain_ml:/data/ml \
-v "$ANNOTRAIN_BACKUP_DIR/files:/backup:ro" --entrypoint rsync annotrain-ml -rt /backup/storage /backup/ml /data/
Storage on a NAS or another disk¶
Three separate things can live outside the app server's own disk, each controlled by its own .env variable:
| What | Variable | Read-only? |
|---|---|---|
Bulk datasets for import-images --reference |
ANNOTRAIN_IMPORT_DIR |
yes |
| Images from the admin panel's "Add images" button | ANNOTRAIN_ORIGINALS_DIR_HOST |
no |
| Everything (the "web" thumbnail cache and any local originals) | ANNOTRAIN_STORAGE_DIR_HOST |
no |
Avoid ANNOTRAIN_STORAGE_DIR_HOST unless you have a specific reason: it also relocates the "web" thumbnail cache that every annotation request reads, so a slow NAS link would slow down the annotation screen itself. ANNOTRAIN_ORIGINALS_DIR_HOST only affects originals, which are never read on the annotation hot path.
ANNOTRAIN_ORIGINALS_DIR_HOST and ANNOTRAIN_IMPORT_DIR can point at the same folder - browser
uploads for a project are written to <project-slug>/images/<sha><ext> under it, as a plain
sibling of any --reference-imported datasets, so everything stays browsable in one place instead
of a separate flat pool. The app creates a short README the first time it writes to a project's
folder, marking it as app-managed rather than a hand-curated dataset.
The target directory must be writable by the container. By default it runs as a dedicated system user (uid 10001):
A network share (CIFS/SMB, e.g. many NAS setups) commonly forces every file to appear owned by your own user instead, no matter what you chown - check with stat -c '%u %g' /path/on/host. If so, chown won't help; instead make the container run as that same uid/gid:
# in .env
ANNOTRAIN_BACKEND_UID=1000 # your uid - id -u
ANNOTRAIN_BACKEND_GID=1000 # your gid - id -g
If you already had data in the default named volume(s) before switching, re-own it once so the container can still write to it after the uid change:
docker run --rm -v annotrain_storage:/data/storage alpine chown -R 1000:1000 /data/storage
docker run --rm -v annotrain_originals:/data/originals alpine chown -R 1000:1000 /data/originals
Updating¶
Database migrations run automatically when the backend starts.
Security notes¶
- Contributors are anonymous: a random identifier is kept in the browser. This is enough to avoid showing an image twice and to count contributors, but it is not authentication: do not treat it as identity.
privateprojects are not listed and their images are not served;unlistedprojects are reachable only by link.- Original files are never exposed publicly.
- Put the site behind Cloudflare (as above) rather than exposing the machine directly.