Get a localhost stack running¶

Only working on the Expert backend (this module) and don't need the AI stack or frontend? See Expert-only development setup instead — it's a faster loop for that narrower case.

Before you begin¶

• A Linux host (Ubuntu Server LTS recommended). Apple Silicon Macs work via Docker Desktop for local dev.
• Docker Engine ≥ 24 and Docker Compose v2 (the docker compose subcommand, not legacy docker-compose) — install guide.
• Python 3.11+ on the host (used by trapper-setup itself; the stack containers ship their own Python).
• Git and curl.
• (Optional, for AI inference) An NVIDIA GPU with a working driver, or a Hailo-8 PCIe device with hailo-all installed. CPU-only works too, just slower.

Steps¶

1. Clone trapper-setup¶

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

2. Bootstrap the setup tool¶

./setup.sh

This downloads uv if missing, creates a .venv/, and installs the wizard's own dependencies (typer, rich).

3. Run the configuration wizard¶

For the simplest "everything on localhost" flavour:

./configure.py localhost

This creates a profile (default name localhost-dev) under profiles/, with a rendered .env and helper scripts (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 any profile:

./bin/install-coordinator.sh localhost-dev

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

Skip this step if you don't need AI inference (e.g. a Citizen-Science-only evaluation) — then also skip starting the coordinator in step 5.

5. Bring up the stack¶

./profiles/localhost-dev/start.sh

This starts the Docker Compose backbone (Expert, AI Manager, Citizen Science frontend, databases, …). It does not start the host coordinator from step 4 — that's a separate, host-level process. Start it as a systemd user unit (keeps running in the background, including after you log out):

./bin/coordinator.sh localhost-dev --install-systemd

Or skip systemd and run it in the foreground in its own terminal instead:

./bin/coordinator.sh localhost-dev

Skip this whole step if you skipped step 4 (no AI inference needed).

6. Run the post-deploy administration wizard¶

./admin.py wizard -p localhost-dev

This creates the Expert and AI Manager superusers, the AI Worker API user, imports the GBIF Backbone Taxonomy, syncs AI models, installs the runtime matching your detected hardware, generates Classificators, and creates a sample test project. See Users & roles for what each step does and how to re-run individual steps.

Verify it worked¶

If all four respond, the stack is up. Log in to the Expert admin with the superuser created by the wizard.

Troubleshooting¶

Next steps¶

• Your first research project
• Your first AI pipeline run
• Architecture reference for the full service/port table