Getting Started

Getting Started

The shortest path from nothing to an API you can query. You need Docker and a PostgreSQL database the container can reach.

1. Start a database

The API's migrations create only the tables it owns. devices, events and the collection-module tables come from the deployment's schema (see Data-Model), so a bare PostgreSQL server needs that schema loaded first. The Docker Compose repo publishes it as schema/init.sql:

curl -fsSLO https://raw.githubusercontent.com/reportmate/selfhosted-docker-reportmate/main/schema/init.sql

Start a throwaway server that runs it on first boot. CI tests against PostgreSQL 16.

docker run -d --name reportmate-db -p 5432:5432 -e POSTGRES_USER=reportmate -e POSTGRES_PASSWORD=password -e POSTGRES_DB=reportmate -v "$PWD/init.sql:/docker-entrypoint-initdb.d/01-init.sql:ro" postgres:16

2. Run the API

DB_SSL=false is required against a local Postgres — TLS is on by default because managed cloud databases demand it.

docker run --rm -p 8000:8000 -e DATABASE_URL=postgresql://reportmate:password@host.docker.internal:5432/reportmate -e DB_SSL=false -e REPORTMATE_PASSPHRASE=changeme ghcr.io/reportmate/reportmate-api:latest

On startup the container runs Alembic migrations to head, then serves on port 8000. Interactive OpenAPI docs are at http://localhost:8000/docs.

3. Check it is alive

/api/v1/health needs no credential and reports whether the database is reachable.

curl http://localhost:8000/api/v1/health

A healthy response:

{
  "status": "healthy",
  "timestamp": "2026-01-15T09:12:44.108231+00:00",
  "database": "connected",
  "version": "1.0.0",
  "deviceIdStandard": "serialNumber"
}

4. Make an authenticated call

Every route except /, the three health probes and /api/v1/auth/config requires a credential. The passphrase you set above is the simplest one.

curl -H "X-Client-Passphrase: changeme" http://localhost:8000/api/v1/devices

On a fresh database this returns an empty list. Nothing appears until an agent checks in.

5. Mint a scoped API key

The shared passphrase carries every scope. Per-client keys are scope-limited and audited; use the passphrase once to create the first one.

curl -X POST http://localhost:8000/api/v1/admin/api-keys \
  -H "X-Client-Passphrase: changeme" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"dashboard","scopes":["read"]}'

The response carries the full key exactly once, in the form rm_<id>_<secret>. Only its SHA-256 hash is stored, so a lost key cannot be recovered — revoke it and mint another. Send it as X-API-Key.

6. Point an agent at it

The agents post to POST /api/v1/events with the same passphrase in X-Client-Passphrase. Configuration of the agents themselves lives in reportmate-client-win and reportmate-client-mac. Ingest-Pipeline describes what the API does with the payload when it arrives.

Next

• Configuration — everything else you can set
• API-Reference — the full surface
• Deployment — running it somewhere real