Skip to content

Deploy with trapper-setup

At a glance

trapper-setup is the canonical install path for the whole TRAPPER ecosystem — Expert, AI Manager, AI Worker, and the Citizen Science frontend — across localhost, staging, and production, on CPU, NVIDIA GPU, or Hailo-8.

  • Time: ~15–30 minutes depending on profile
  • Who: anyone deploying or operating a TRAPPER instance
  • Prerequisites: Docker Engine ≥ 24 + Compose v2, Python 3.11+, Git/curl

If you just want the simplest local dev setup, follow Get a localhost stack running instead — this page covers the full range of profiles and options.

Before you begin

  • trapper-setup cloned and bootstrapped (./setup.sh)
  • Decided which profile you need: localhost, staging, or production
  • For GPU: NVIDIA driver + Container Toolkit installed
  • For Hailo-8: PCIe driver, libhailort.so, and the HailoRT Python wheel staged (see docker/hailo/README.md in trapper-setup)

Steps

1. Configure a profile

./configure.py localhost
Disables Traefik, exposes service ports directly, no SSL.

./configure.py quick \
    --domain example.com \
    --ssl letsencrypt \
    --modules all \
    --profile production
Enables Traefik with automatic Let's Encrypt certificates.

./configure.py interactive
Walks through deployment mode, domain/SSL, module selection, and volume configuration one prompt at a time. Use --from-profile <name> or --from-env <path> to base it on an existing configuration.

Field What it does Recommended value
--modules Which services to run: trapper, trapper-ai, ai-worker, frontend, all all unless resource-constrained
--ssl letsencrypt, selfsigned, or static certs (quick/interactive only — localhost always uses none) letsencrypt for public domains, selfsigned for staging
--profile Name for this configuration, stored under profiles/<name>/ Descriptive, e.g. production, staging
--reuse-env / -r Keep existing passwords/secrets, only update specified values Use when iterating on an existing profile

There's no accelerator flag to set

GPU/Hailo selection isn't part of configure.py — it was removed (the AI Worker host coordinator now auto-detects the hardware at runtime). As long as the NVIDIA driver or hailo-all is installed on the host, ./admin.py wizard's step 6 installs the matching runtime automatically; see step 4 below.

2. Install the AI Worker host coordinator

One-time per host, independent of profile:

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

Installs the trapperai-core tool into a uv-managed venv at ~/.local/share/uv/tools/trapperai-core/, exposing trapperai-coordinator / trapperai-ctl / trapperai-worker via ~/.local/bin/. This only installs the binaries — it does not start anything yet (see step 3). Skip this whole step if you don't need AI inference.

Reinstalling or removing the coordinator 
./bin/install-coordinator.sh <profile> --reinstall
./bin/install-coordinator.sh <profile> --uninstall   # this profile's unit only
./bin/install-coordinator.sh --uninstall              # all profiles + shared venv (asks first)

3. Bring up the stack

./profiles/<profile>/start.sh

This only starts the Docker Compose backbone (Expert, AI Manager, frontend, databases, …). Useful flags:

./start.sh --profile trapper --profile frontend   # only these modules, overriding configure-time choice
./start.sh --no-flower                            # skip Celery monitoring to save resources
./start.sh --frontend-dev                         # Angular dev server with hot reload instead of the prod build

If you installed the coordinator in step 2, start it separately — it's a host-level process, not a Compose service:

./bin/coordinator.sh <profile> --install-systemd   # persistent systemd user unit (recommended)
./bin/coordinator.sh <profile>                     # or: run it in the foreground instead

4. Run the post-deploy administration wizard

./admin.py wizard -p <profile>

See Users & roles for the full step list and how to re-run individual steps with --steps.

Verify it worked

./ps.sh -p <profile>

All containers should show Up/healthy. For a host-coordinator profile, also check systemctl --user status trapperai-coord-<profile>.

Troubleshooting

SSL certificate issues (Let's Encrypt)

Ensure ports 80/443 are reachable from the internet and DNS resolves to this host. Check docker compose logs traefik.

AI Worker not processing jobs

./logs.sh ai-worker. For GPU, verify the runtime with docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi. For Hailo, check lspci | grep Hailo, lsmod | grep hailo, and ls -l /dev/hailo0.

Database connection issues

docker compose exec postgres pg_isready (and postgres-ai for the AI Manager's database).

Next steps