Skip to main content

Deployment Overview

SAPOT is a multi-component system deployed as independent services on a LAN.

The established bare-metal/systemd path below remains supported. For an offline site that uses Docker Engine and a prebuilt immutable artifact, use the offline Docker bundle guide instead, and follow install-ubuntu-server.md for the first install on a fresh Ubuntu Server 24.04 host.

Components and deployment units​

Each component runs as its own OS process on the same host (or split across hosts on the same LAN), with systemd supervising the long-running services.

ComponentProcessManaged by
FastAPI serverGunicorn + uvicorn workerssystemd server-main-api.service
Nginx reverse proxynginxsystemd
MariaDBmysqldsystemd
Redisredis-serversystemd
Admin frontendnext startsystemd or manual
GSM module APIGunicorn + uvicornsystemd server-GSM-api.service
Tileservertileserver binarysystemd tileserver.service
MikroTik routerRouterOS (vendor)RouterOS web UI

Deployment prerequisites​

Install these on the host before starting any component; the Nix flake per component can substitute for the manual Python/Node setup.

  • Linux host (tested Debian/Ubuntu)
  • Nix package manager (optional — flake.nix per component)
  • Python 3.11+ with venv
  • Node.js + pnpm (admin frontend)
  • MariaDB server
  • Redis server
  • Nginx
  • TLS certificate at /home/sapot/certs/server.crt and server.key

Network requirements​

SAPOT is LAN-first (see ADR 0005) — the server must be reachable at a stable address on the same subnet as mobile devices.

  • Static IP or DHCP reservation for the server on the LAN
  • MikroTik router for captive portal (optional)
  • Mobile devices on the same LAN subnet

Deployment order​

Later steps depend on earlier ones being up — start data stores before the API, and the API before anything that proxies or calls it.

  1. Start MariaDB and Redis
  2. Start SAPOT FastAPI server (creates DB tables on first run)
  3. Start Nginx (proxy to :8000)
  4. Start GSM module API (if hardware connected)
  5. Start tileserver
  6. Build and serve admin frontend

Detailed guides​