Configuration

Gotcha is configured entirely through environment variables prefixed GOTCHA_. There’s no config file and no web UI screen for system-level settings — only environment variables. Their authoritative source is cmd/gotcha/config.go in the source tree; this document is a readable description of the same thing, grouped by purpose. A template with every variable and comments lives in .env.example at the repository root.

How to set environment variables with Docker Compose

Two equivalent ways:

Option 1 — an .env file next to docker-compose.yml (recommended, the simplest). Docker Compose reads it automatically:

# inside the gotcha/ directory
nano .env

GOTCHA_SECRET_KEY=random-string-from-openssl-rand
GOTCHA_BASE_URL=https://gotcha.example.com
GOTCHA_SMTP_HOST=smtp.example.com
GOTCHA_SMTP_PORT=465
GOTCHA_SMTP_USER=noreply@example.com
GOTCHA_SMTP_PASSWORD=an-app-password
GOTCHA_SMTP_FROM=noreply@example.com

Apply the changes:

docker compose up -d

(this recreates the gotcha container with the new variables; it leaves postgres/clickhouse alone unless their own variables changed).

Option 2 — an environment: block right in docker-compose.yml. If you’d rather not use an .env file, you can set variables directly in the compose file, under the gotcha service:

services:
  gotcha:
    # ...
    environment:
      GOTCHA_PG_DSN: postgres://gotcha:gotcha@postgres:5432/gotcha?sslmode=disable
      GOTCHA_CH_DSN: clickhouse://gotcha:gotcha@clickhouse:9000/gotcha
      GOTCHA_BASE_URL: ${GOTCHA_BASE_URL:-http://localhost:59080}
      GOTCHA_SECRET_KEY: ${GOTCHA_SECRET_KEY:-insecure-dev-secret}
      GOTCHA_SMTP_HOST: smtp.example.com

${VAR:-default} is Docker Compose interpolation: “take VAR from the environment/.env, and if it isn’t set, use the value after :-.” The repository’s stock docker-compose.yml already uses this pattern for GOTCHA_BASE_URL and GOTCHA_SECRET_KEY, so for those two, option 1 (just creating an .env file) is usually enough — no need to edit the compose file itself.

After changing any variable, run docker compose up -d to apply it — Docker Compose detects that the container’s configuration changed and recreates it.

Core

Database

Email / SMTP

Used for invite emails and the email alert channel. As long as GOTCHA_SMTP_HOST is empty, email sending is disabled entirely (the log shows GOTCHA_SMTP_HOST is not set, email alert channels are disabled), while everything else keeps working normally.

Retention (ClickHouse data)

How many days ClickHouse keeps each kind of data before deleting old rows. Lower means less disk usage; higher means a deeper history for investigations.

Retention changes apply on the next application start (the value is used to set a TTL on the ClickHouse tables) — data already deleted doesn’t come back retroactively.

Quotas & edition

When you must change the quotas: 0 (unlimited) in the oss edition is a deliberate choice for a private self-hosted instance where the DSN never leaks. If a project’s DSN ends up in publicly reachable code (e.g. your website’s frontend JS), anyone can send it an unbounded volume of events — both an abuse vector and a risk of filling up ClickHouse’s disk. In that case, set real numbers, e.g.:

GOTCHA_DEFAULT_EVENT_QUOTA=100000
GOTCHA_DEFAULT_TRANSACTION_QUOTA=50000

(This is the default applied to new organizations; an existing organization’s quota can be changed in its settings in the web UI.)

Privacy / scrubbing

Server-side removal of personal data before storage — on by default.

Security

Uptime & probe

--mode=probe is a separate process deployed in another region/data center: it doesn’t open PostgreSQL or ClickHouse at all — it only makes outbound HTTP requests to the central instance.

OAuth / SSO

Each login provider is enabled independently. Enabling a provider without setting its required secrets makes the app refuse to start.

Step-by-step setup for each provider is in SSO.

What’s next

• Installation — getting started on a fresh server.
• Backup & Restore.
• Upgrade.
• SSO.