Installation

TRAPPER ships as a multi-container Docker stack covering the Expert backend (this module), the AI Manager, the AI Worker host coordinator, and the Citizen Science frontend. We use a unified deployment toolchain — the trapper-setup repository — to orchestrate the entire ecosystem with one interactive wizard, instead of running docker compose against a hand- edited .env file as in v1.

If you only want to develop on this module (Expert backend) without the AI stack and Frontend, see Expert-only development setup at the end of this page.

Note

This page covers getting a deployment running. Tweaking individual runtime options (database, storage, AI pipeline, distance estimation, trackers, …) is documented in Configuration.

Prerequisites

A Linux host (Ubuntu Server LTS recommended) with:

• Docker Engine ≥ 24 and Docker Compose v2 (docker compose subcommand, not legacy docker-compose). Follow the official installation guide at https://docs.docker.com/engine/install/.

• Python 3.11+ on the host (used by trapper-setup itself; the stack containers ship their own Python).

• Git and curl for fetching trapper-setup and the AI Worker installer.

• For AI inference (optional): an NVIDIA GPU with working driver, a Hailo-8 PCIe device with hailo-all installed, or sufficient CPU. The AI Worker coordinator autodetects available hardware at startup.

The reference target is amd64 / arm64 Linux. Apple Silicon Macs work for local development via Docker Desktop. Windows is supported via Docker Desktop + WSL2 but is not what the team runs day-to-day.

Recommended path: trapper-setup

The trapper-setup repository is the canonical install path. It generates a per-deployment profile with a rendered .env, Compose overlays, helper scripts (start.sh / stop.sh / logs.sh), and a host-side AI Worker coordinator install.

1. Clone trapper-setup next to your other Trapper repos:

   git clone https://gitlab.com/trapper-project/trapper-setup.git
   cd trapper-setup
   

2. Bootstrap the setup tool’s own Python venv:

   ./setup.sh
   

   This downloads uv if missing, creates .venv/, and installs the handful of Python deps used by the configuration wizard (typer, rich).

3. Run the configuration wizard. The simplest “everything on localhost” flavour is:

   ./configure.py localhost
   

   For a full production deployment with a public domain, Let’s Encrypt SSL, and all modules:

   ./configure.py quick \
       --domain example.com \
       --ssl letsencrypt \
       --modules all \
       --profile production
   

   The wizard renders profiles/<profile>/.env plus per-profile start.sh / stop.sh / logs.sh / ps.sh.

4. Install the AI Worker host coordinator. This is a one-time per host step independent of profile:

   ./bin/install-coordinator.sh <profile>
   

   It runs the upstream install-trapperai.sh, creating a uv tool venv at ~/.local/share/uv/tools/trapperai/ with trapperai-coordinator, trapperai-ctl, and trapperai-worker linked into ~/.local/bin/.

   Skip this step if you don’t need AI inference (e.g. citizen-science- only deployment); pass --no-coordinator to start.sh to run without it.

5. Bring up the stack:

   ./profiles/<profile>/start.sh
   

   The script orchestrates both the Compose backbone and the host coordinator (as a systemd user unit by default; pass --foreground to keep it inline).

6. Run the post-deploy administration wizard once the stack is healthy:

   ./admin.py wizard -p <profile>
   

   The wizard creates Expert and AI Manager superusers, the AI Worker API user, imports the GBIF Backbone Taxonomy, runs sync_models_from_schemas (AI Manager) and sync_ai_models (Expert), installs the runtime that matches detected hardware, generates Classificators from AI provider species mappings, and creates a sample test project.

   See the Administration page for everything the wizard sets up and for running individual steps later (--steps flag).

7. Verify the stack:

   • Trapper Expert at http(s)://<your-domain>/ (or http://localhost:8000 in localhost mode).

   • Trapper AI Manager admin at http(s)://<ai-domain>/admin/.

   • AI Worker UI at http://localhost:34821 (or via Traefik when AI_WORKER_DOMAIN is set).

   • Frontend at http(s)://<cs-domain>/ or http://localhost:4200.

The trapper-setup README has the full reference for compose overlay combinations (dev / SSL / localhost), profile management, volume configuration, and worked examples (5-min localhost dev, production NVIDIA GPU, Raspberry Pi + Hailo, side-by-side staging/production). For all deployment-toolchain questions, that document is authoritative.

What you get out of the box

A successful installation gives you the following running services. All ports listed are localhost defaults; in production deployments they sit behind Traefik.

Service	What it does	Port
Trapper Expert (Django)	Core backend, REST API, admin	8000
Trapper Expert Celery	Background tasks (uploads, AI dispatch)
Trapper Expert Uploader	Chunked-upload FastAPI service	8088
Trapper Expert Nginx	Static + media + video streaming	8080
Trapper AI Manager	Prediction-job orchestration	8001
AI Worker coordinator	Host process, autodetects hardware	34821
Citizen Science frontend	Angular SPA	4200
PostgreSQL (Expert)	TimescaleDB-enabled main database	5432
PostgreSQL (AI)	Plain PostgreSQL for the AI Manager	5433
RabbitMQ	Celery broker (Expert and AI Manager)	5672
Memcached	Shared cache	11211
Pure-FTPd	FTPS upload endpoint	21

The PostgreSQL Expert image is TimescaleDB-enabled because the ObjectFrameObservation per-frame index is stored as a hypertable; see Frame-level data and USE_FRAMES_HYPERTABLE for the optional flag that lets new installs skip the extension entirely.

Expert-only development setup

If you are working only on this module (no AI stack, no frontend), the project’s own ./start.sh is still the path of least resistance for a quick dev loop.

1. Clone this repository:

   git clone https://gitlab.com/trapper-project/trapper.git
   cd trapper
   

2. Copy and adjust the env template:

   cp trapper.env .env
   # Edit .env if you want to point at an external DB or change ports
   

3. Start the dev stack with the in-tree helper:

   ./start.sh -pb dev
   

   Flags: -p pulls images, -b builds the local trapper image. See ./start.sh -h for the full list (notably -d for an external database — see Database).

4. Create a superuser:

   docker exec -it trapper bash
   python /app/trapper-project/manage.py createsuperuser
   

This path skips the AI stack and frontend entirely. Use it for quick iteration on the Expert backend; switch to trapper-setup for any deployment-shaped task.

Upgrading

If you installed via trapper-setup, follow the upgrade procedure in the trapper-setup README — at minimum:

./profiles/<profile>/stop.sh --no-coordinator
docker compose pull
./bin/install-coordinator.sh <profile> --reinstall
./profiles/<profile>/start.sh
./admin.py manage trapper migrate -p <profile>
./admin.py manage trapper-ai-web migrate -p <profile>

If you installed via the in-tree ./start.sh (Expert-only dev), pull the new image and run migrations inside the container:

./stop.sh
./start.sh -pb dev
docker exec -it trapper bash
python /app/trapper-project/manage.py migrate