Getting Started

Getting Started

The shortest path from a clean host to a working ReportMate dashboard.

Requirements

• A host with Docker Engine and the Compose plugin (docker compose version must work).
• Outbound access to ghcr.io to pull the images.
• Ports 3000 and 8000 free on the host, or edited in docker-compose.yml.

1. Clone and configure

git clone https://github.com/reportmate/selfhosted-docker-reportmate.git
cd selfhosted-docker-reportmate
cp .env.example .env

.env ships with placeholder values. Four of them are refused by Compose if left unset, and all four should be replaced with real random strings: DB_PASSWORD, API_INTERNAL_SECRET, REPORTMATE_PASSPHRASE, and NEXTAUTH_SECRET. The web and api services must be given the same API_INTERNAL_SECRET and the same REPORTMATE_PASSPHRASE — the Compose file already wires both from the single .env value, so just set each once.

Generate a value per secret:

openssl rand -hex 24

See Configuration for the full variable list.

2. Start the stack

docker compose up -d

On first start, postgres initialises an empty database and runs schema/init.sql from /docker-entrypoint-initdb.d. The api container waits for the Postgres healthcheck to pass before it starts.

3. Verify

docker compose ps

All three services should be running, with postgres marked healthy. Then check the API:

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

Open the dashboard at http://localhost:3000.

4. Sign-in

.env.example sets DEMO_MODE=true, which reaches the dashboard as NEXT_PUBLIC_DEMO_MODE. The published ghcr.io/reportmate/web image is built with NEXT_PUBLIC_DEMO_MODE=false, and Next.js compiles that value into the image, so the runtime setting has no effect: the published dashboard always asks for sign-in, and sign-in cannot complete until you configure an identity provider.

Supply the Microsoft Entra ID variables to the web service to sign in. Those variables are not in .env.example or in the Compose file — you add them to the web service's environment: block yourself. To evaluate without an identity provider, build a demo-mode dashboard image instead. Both are covered in Configuration.

5. Point clients at it

A ReportMate agent needs the API base URL and a passphrase. The URL is the api service as reachable from your endpoints — http://reportmate.example.com:8000 for a bare stack, or an HTTPS front door if you have followed TLS and Reverse Proxy. The passphrase is the REPORTMATE_PASSPHRASE value you set in .env.

Client configuration itself lives in the agent repos: reportmate-client-win and reportmate-client-mac.

Starting over

This deletes the database volume and all ingested data:

docker compose down -v

Because schema/init.sql runs only when the data directory is empty, removing the volume is also how you force the bundled schema to be re-applied.