Getting Started: Overview
SAPOT is built from independently-runnable components, each with its own toolchain and no shared build. Set up only the ones you need for the task at hand.
Four have a dedicated setup guide here:
| Component | Path | Language / Stack | Purpose |
|---|---|---|---|
| Server | server/ | Python / FastAPI | REST API, WebSocket signalling relay, GPS streaming, MariaDB storage |
| Mobile app | mobile-app/sapot-mobile-app/ | React Native / Expo | The SAPOT client — P2P LAN messenger + server-relayed fallback |
| GSM module | GSM-module/GSM-fastapi/ | Python / FastAPI | SMS gateway bridging the server to a serial-attached GSM modem |
| Admin frontend | admin-frontend/sapot-admin/ | Next.js | Admin dashboard (announcements, user/router management) |
Two more ship with the system but need no per-developer setup:
| Component | Path | What to know |
|---|---|---|
| Tileserver | tileserver/ | Deploy scripts only, no source. The Docker stack runs it as a service behind Nginx at /tiles/; you only supply the gitignored .mbtiles data file. |
| Captive portal | captive-portal/ | Static HTML/CSS/JS login pages served by the RouterOS hotspot, not by any component above. Deployed to the router, not run locally. |
Fastest path
For a single "clone → run the whole stack" walkthrough (server + mobile app, with optional GSM and admin frontend steps), see quickstart.md. The per-component guides below go into more depth on each piece individually.
Typical setup order
- Docker setup (full stack): server needed by every other component; also brings up the admin dashboard, tileserver, and SMS gateway. Prefer running the API directly without Docker? See server-setup.md (bare-metal). Either path needs a separate
alembic upgrade headbefore the API can serve anything: the schema is Alembic-owned (ADR 0007) and no startup path creates it. - Mobile app setup — the primary client; requires the server running and reachable on the same LAN for local dev.
- GSM module setup: only needed if testing SMS fallback; the Docker stack already runs this service, so follow it only for a modem on a non-Docker host.
- Admin frontend setup: the Docker stack already serves the dashboard, but a fresh database has no administrator; this guide covers creating the first one.
If something doesn't work, see ../TROUBLESHOOTING.md.
Related documentation
docs/architecture/— system-wide architecturedocs/deployment/environment-config.md— full environment variable reference for all components- Mobile app architecture — mobile app internals
- Mobile app onboarding — mobile app onboarding doc