Scout Server
July 16, 2026 · View on GitHub
A Vapor backend for the Scout package. The server aggregates analytics data natively: clients upload only raw records, and the name-grouped metric series Scout's UI reads are synthesized on the fly with SQL aggregation. Active users (DAU/WAU/MAU) are aggregated the same way and served as a flat series.
Table of Contents
Features
| 📊 | Native Aggregation | The name-grouped metric series Scout's UI reads, the DAU/WAU/MAU active-user series, and the retention cohorts are synthesized on the fly with SQL — clients upload only raw records. |
| 🔁 | Idempotent Upserts | Records are upserted by recordID, so re-sent batches overwrite in place and sync retries stay safe. The Scout dashboard queries the API directly. |
| 🔑 | API Keys | Endpoints are guarded by API keys, passed via an X-API-Key header or a bearer token. |
| 🐘 | Postgres | Records persist in Postgres with migrations run automatically on boot; tests run against in-memory SQLite. |
| 🐳 | Docker | Ships as a container image on the GitHub Container Registry. |
Running
docker compose up
brings up the server with Postgres on localhost:8080. Images are published to GitHub Container Registry as ghcr.io/kasianov-mikhail/scout-server.
Configuration
| Variable | Meaning |
|---|---|
SCOUT_API_KEYS | Comma-separated list of accepted API keys |
DATABASE_URL | Postgres connection string (takes precedence) |
DATABASE_HOST / DATABASE_PORT / DATABASE_USERNAME / DATABASE_PASSWORD / DATABASE_NAME | Component-wise Postgres configuration |
Migrations run automatically on boot.
API
The server exposes a small HTTP API under /api/v1 for uploading and querying records. See API.md for the full reference.
Development
swift test
Tests run against an in-memory SQLite database; the aggregation SQL is portable across both drivers (grouping happens on epoch-second bucket columns).
License
Scout Server is released under the MIT License. See LICENSE for details.