.. _installation: ============ 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 :ref:`installation-expert-only-dev` 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 :ref:`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. #. Clone ``trapper-setup`` next to your other Trapper repos: .. code-block:: bash git clone https://gitlab.com/trapper-project/trapper-setup.git cd trapper-setup #. Bootstrap the setup tool's own Python venv: .. code-block:: bash ./setup.sh This downloads ``uv`` if missing, creates ``.venv/``, and installs the handful of Python deps used by the configuration wizard (``typer``, ``rich``). #. Run the configuration wizard. The simplest "everything on localhost" flavour is: .. code-block:: bash ./configure.py localhost For a full production deployment with a public domain, Let's Encrypt SSL, and all modules: .. code-block:: bash ./configure.py quick \ --domain example.com \ --ssl letsencrypt \ --modules all \ --profile production The wizard renders ``profiles//.env`` plus per-profile ``start.sh`` / ``stop.sh`` / ``logs.sh`` / ``ps.sh``. #. Install the AI Worker host coordinator. This is a *one-time per host* step independent of profile: .. code-block:: bash ./bin/install-coordinator.sh 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. #. Bring up the stack: .. code-block:: bash ./profiles//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). #. Run the post-deploy administration wizard once the stack is healthy: .. code-block:: bash ./admin.py wizard -p 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 :ref:`administration` page for everything the wizard sets up and for running individual steps later (``--steps`` flag). #. Verify the stack: - Trapper Expert at ``http(s):///`` (or ``http://localhost:8000`` in localhost mode). - Trapper AI Manager admin at ``http(s):///admin/``. - AI Worker UI at ``http://localhost:34821`` (or via Traefik when ``AI_WORKER_DOMAIN`` is set). - Frontend at ``http(s):///`` 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 :ref:`configuration-frame-hypertable` for the optional flag that lets new installs skip the extension entirely. .. _installation-expert-only-dev: 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. #. Clone this repository: .. code-block:: bash git clone https://gitlab.com/trapper-project/trapper.git cd trapper #. Copy and adjust the env template: .. code-block:: bash cp trapper.env .env # Edit .env if you want to point at an external DB or change ports #. Start the dev stack with the in-tree helper: .. code-block:: bash ./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 :ref:`configuration-database`). #. Create a superuser: .. code-block:: bash 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: .. code-block:: bash ./profiles//stop.sh --no-coordinator docker compose pull ./bin/install-coordinator.sh --reinstall ./profiles//start.sh ./admin.py manage trapper migrate -p ./admin.py manage trapper-ai-web migrate -p If you installed via the in-tree ``./start.sh`` (Expert-only dev), pull the new image and run migrations inside the container: .. code-block:: bash ./stop.sh ./start.sh -pb dev docker exec -it trapper bash python /app/trapper-project/manage.py migrate