Skip to content

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

git clone https://github.com/cmaslard/AnnoTrain.git
cd AnnoTrain
cp .env.example .env

Edit .env: set POSTGRES_PASSWORD and ANNOTRAIN_ADMIN_TOKEN to long random values.

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

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

  1. In the Cloudflare dashboard open Zero Trust → Networks → Tunnels → Create a tunnel and choose Cloudflared.
  2. Name it (for example annotrain) and copy the tunnel token.
  3. Put it in .env as CLOUDFLARE_TUNNEL_TOKEN=....
  4. In the tunnel's Public Hostname tab add:
    • Hostname: annotrain.cmaslard.xyz
    • Service: HTTP → web:80
  5. Start the tunnel container:
docker compose --profile tunnel up -d

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. The s parameter 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

./scripts/backup.sh

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):

30 3 * * * /path/to/AnnoTrain/scripts/backup.sh >> $HOME/annotrain-backups/backup.log 2>&1

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):

sudo chown -R 10001 /path/on/host

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

git pull
docker compose up -d --build

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.
  • private projects are not listed and their images are not served; unlisted projects are reachable only by link.
  • Original files are never exposed publicly.
  • Put the site behind Cloudflare (as above) rather than exposing the machine directly.