Skip to main content

Getting Started

Run the whole Snitcher stack locally with Docker Compose: bring it up, log in, and take a first tour. The stacks live under deployments/ — deployments/dev/ (local, build from source) and deployments/prod/ (published images, hardened).

Prerequisites​

  • Docker with the Compose plugin.
  • The Snitcher repository cloned locally. Run all commands from the repo root.

1. Secrets​

The dev stack is zero-config — every secret has a dev default baked in, so you can skip straight to step 2.

For a production deployment you generate your own secrets into a git-ignored .env inside deployments/prod/. Compose references them with ${VAR:?} placeholders, so startup fails loudly if a required value is unset:

cd deployments/prod
cp .env.example .env
openssl rand -base64 48   # SNITCHER_JWT_KEY  (min 32 chars)
openssl rand -base64 32   # SNITCHER_SECRETS_KEY  and  SCOUT__KEY_ENCRYPTION_KEY
openssl rand -base64 24   # SNITCHER_DB_PASSWORD

See deployments/prod/README.md for the PBKDF2 admin-password-hash recipe.

warning

Changing SNITCHER_SECRETS_KEY after target secrets have been stored makes those secrets permanently undecryptable. Set it once and keep it safe.

note

A plaintext Auth__Password works only in the Development environment (where the default is admin / admin). Production requires Auth__PasswordHash.

2. Bring the stack up​

docker compose -f deployments/dev/compose.yaml -p snitcher-new up -d --build

This starts the Snitcher server, TimescaleDB, Mailpit, Keycloak (bundled SSO), and the bundled first Scout from source in the Development environment — no .env needed. For a hardened production deployment use deployments/prod/ (cd deployments/prod && docker compose up -d) after step 1, which pulls the published images and runs as Production.

3. Log in​

ServiceURLNotes
Snitcher dashboardhttp://localhost:8080admin / admin (built-in Administrators group)
Mailpit (alert email sink)http://localhost:8025Catches alert emails
Keycloak (bundled SSO)http://localhost:8081Admin console: admin / admin

4. First tour​

  • Add a target — go to Targets → New, choose a check type (HTTP/TCP/ICMP), set the target, interval, and timeout, then assign one or more Scouts to decide where it's checked from.
  • Label targets — add freeform labels to a target to group it in the UI and scope permission groups or audit-log filters to it (see Targets).
  • Set up alerting — create an Alerter (email channel) and an Alert Rule tying an alert type to it (see Alerting).
  • Add users — enable SSO and manage permissions via groups (see Users & Groups).

Where data lives​

The Postgres/TimescaleDB database is internal-only (no host port) and persists in the snitcher-db-data Docker volume. Configuration is authoritative on the server — restore it and Scouts reconverge.