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.

Naming convention

A numeric variable carries its unit right in the name: _SECONDS, _DAYS, _HOURS, _BYTES, _PER_SEC, _PER_MIN (for example GOTCHA_ESCALATION_INTERVAL_SECONDS, GOTCHA_EXPORT_RETENTION_HOURS, GOTCHA_DIST_RATE_PER_MIN). A bare number without a unit in the name is ambiguous — sixty of what, seconds or minutes? For retention settings the name also names the kind of data being cut off (GOTCHA_EVENT_RETENTION_DAYS, GOTCHA_LOG_RETENTION_DAYS, GOTCHA_DEPLOY_RETENTION_DAYS), rather than one shared RETENTION_DAYS for everything. The variable’s prefix names the subsystem, not the product as a whole: GOTCHA_AGENT_* is the host agent process (gotcha-agent, a separate binary) only; GOTCHA_DIST_* is the instance serving agent binaries (not the agent itself); GOTCHA_PROBE_* is a remote probe (--mode=probe). An invalid value for any variable refuses to start the process rather than silently falling back to a default — a typo in the configuration must be caught by the operator immediately, not weeks later as silently wrong behavior.

The unit-naming convention is enforced by internal/guards/env_example_test.go: ANY variable read in cmd/gotcha/config.go or internal/agent/config.go as a bare number (intNum/num) is suspect by default — the gate fails it unless its name carries the matching suffix or it is listed explicitly in that test’s closed unitlessCounters map (bare counters — limits, concurrency, a port — that have no unit to carry). Adding a new line to that list is a review-visible change, not a quiet way around the convention.

Separately from the value, the variable’s NAME is checked at startup too. A GOTCHA_* name that neither cmd/gotcha nor internal/agent reads (the registry of known names — internal/envcontract/known.go, the union of server and agent variables: the agent is normally installed on the same host as the server, sharing one .env) refuses to start, naming the closest known name (edit distance of at most two) — a typo like GOTCHA_HSTS_ENABLE (missing the D) no longer sails through silently on a default. The exception is the GOTCHA_COMPOSE_* and GOTCHA_BUILD_* prefixes: Docker Compose itself reads those (via ${...} substitution), or Makefile does (image build-args) — no Go process reads them, and the registry of known names doesn’t include them.

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

Compose-only variables (database containers)

These four are Docker Compose substitution variables, not configuration of the gotcha process: the app never reads them. Compose substitutes them into the database containers’ settings and into the DSNs above.

Changing a database password on an existing install. POSTGRES_PASSWORD/CLICKHOUSE_PASSWORD only take effect when the data volume is first initialized — on a live install, changing the variable alone locks the app out of a database that still expects the old password. The order matters:

1. Change the password in the database itself:

   docker compose exec postgres psql -U gotcha -d gotcha -c "ALTER USER gotcha WITH PASSWORD 'new-password'"
   docker compose exec clickhouse clickhouse-client --user gotcha --password 'old-password' -q "ALTER USER gotcha IDENTIFIED BY 'new-password'"
   

2. Set GOTCHA_COMPOSE_PG_PASSWORD/GOTCHA_COMPOSE_CH_PASSWORD in .env.
3. docker compose up -d — the app container is recreated with the new DSN.

Compose-only variables (the app container)

Build-only variables (Makefile build-args)

These three are substitution variables too, but not Docker Compose’s — Makefile’s: it forwards them into docker compose build as image build-args (DOCKER_BUILD_ENV, see Dockerfile). No gotcha process reads them; make sets them itself (git describe/commit/date) — you only need these if you build the image with docker compose build directly, bypassing make.

Start with the symptom, not the numbers. Docker gives container networks an MTU of 1500 without looking at the host’s uplink, and a VPS behind a tunnel (GRE, VXLAN, OpenVZ) commonly has 1450. The mismatch itself is everywhere, and most installations live with it and never notice.

It is only harmless in one direction, though. Outbound packets are fixed by your own kernel: the narrow link is the host’s own interface, the kernel says so, and the container lowers the route’s MTU. Inbound packets depend on the remote end: it sends segments of the size the container advertised when the connection was set up (MSS = MTU − 40, so 1460 instead of 1410), and it only shrinks them if it receives an ICMP “fragmentation needed” from a router on the path. Whether that ICMP arrives is neither your side nor your control. Where it is filtered, the sender keeps pushing 1460-byte segments and they vanish.

Every sign of this failure follows from that:

• small exchanges work, large ones disappear: TCP connects, the SMTP 220 greeting arrives, and the TLS handshake — the first large exchange — hangs until it times out;
• different destinations behave differently: TLS completes to one host and hangs on another, because the ICMP is not filtered everywhere;
• it can work and then stop: the kernel keeps a learned path MTU in the route cache for about ten minutes (net.ipv4.route.mtu_expires), and while that entry lives everything is fine — once it expires the symptom returns on its own;
• from the host the very same thing always works: that interface is 1450, so the MSS is 1410 from the start and no ICMP is needed.

That last point is the trap when diagnosing this. Test from inside the container, not from the host:

docker compose exec gotcha wget -q -O /dev/null https://api.github.com/ && echo ok || echo fail

If TLS hangs there while openssl s_client -starttls smtp -connect <your-smtp>:587 completes on the host, the MTU is your answer.

Everything the instance sends outward shares the path — email, webhook channels, OAuth, and uptime checks — so when this does happen, a monitored site can be reported unreachable because of the MTU of the container watching it.

Check the host:

ip -o link show

If the external interface (ens3, eth0) is below 1500 while docker0 shows 1500 and you have the timeout above, set GOTCHA_COMPOSE_NET_MTU to the interface’s value and bring the stack back up. The container then advertises an MSS the path can certainly carry, and delivery stops depending on somebody else’s ICMP:

docker compose down && docker compose up -d

down matters here — up -d alone is not enough. Changing the value requires recreating the network, and doing that under running containers leaves Docker’s embedded DNS holding the old records: services stop finding each other by name (lookup postgres on 127.0.0.11:53: server misbehaving) until the whole stack is brought up again.

If delivery doesn’t recover, the MTU wasn’t the cause — put the value back and look at reachability instead (Alerts walks through it).

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.

Telegram

Outbound HTTP proxies are honoured for Telegram through the standard HTTPS_PROXY/HTTP_PROXY/NO_PROXY environment variables. They do not apply to webhook channels, OAuth or uptime checks: those dial their targets directly on purpose, because the SSRF filter decides on the address actually connected to, and a proxy would move that decision off the instance. See Alerts for the Telegram troubleshooting path.

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

GOTCHA_MAX_WRITER_BUFFER_BYTES auto-default: when the variable is unset, each writer buffer’s ceiling is derived from the detected heap ceiling (the same 80%-of-GOTCHA_COMPOSE_MEM_LIMIT ceiling described above, under “Compose-only variables”) instead of the package’s flat constant (256 MiB). There are six buffer “units” (events; a tracing writer’s transaction buffer and span buffer count as two independent buffers of one writer; metrics; profiles; logs); the auto-default splits 60% of the heap ceiling across them, leaving 40% for everything else (HTTP ingest, JSON parsing, the PostgreSQL client, the runtime itself). On the default docker-compose.yml (mem_limit: 1g, heap ceiling ≈ 819 MiB) this works out to roughly 82 MiB per buffer — instead of a flat 256 MiB, which summed (1.5 GiB) would exceed the heap ceiling and could trigger a kernel OOM kill during a sustained ClickHouse outage. If there’s nothing to derive a heap ceiling from (bare metal, no cgroup, no GOMEMLIMIT), behavior is unchanged: a flat 256 MiB per buffer. An explicitly set GOTCHA_MAX_WRITER_BUFFER_BYTES always wins over the auto-default — including for constrained profiles (docker-compose.small.yml still sets 24 MiB explicitly).

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.

Limits and evaluators

Ceilings that protect the instance from a flood, plus how often the background evaluators run. These bound WORK, not storage — which is why they no longer sit under Retention and Quotas.

Observability and logs

Detail level and format of the instance’s own logs.

Security

The --migrate-only command-line flag applies the schema and exits without starting any component: an init job for deployments with GOTCHA_AUTO_MIGRATE_ENABLED=false. See Upgrade.

Process modes: what each --mode= runs

The process role is set by the binary’s --mode= flag (not an environment variable): all is the default and what the stock docker-compose.yml runs; web, ingest, and uptime are for a split deployment across several replicas; probe is a remote probe (see below). The table shows which components each mode brings up. All four database-backed modes keep an HTTP listener with the service endpoints (/healthz, /readyz, /version, /metrics, see Monitoring gotcha itself) and run the secrets backfill under the current GOTCHA_SECRET_KEY at startup.

Two consequences for a split deployment follow. First, web is not “UI only”: it delivers notifications and prunes the database like every other mode, so a notify outbox janitor line in its log is normal, not a sign of a mixed-up mode. Second, without an uptime or all replica the evaluators run nowhere — enable them explicitly with GOTCHA_EVALUATORS_ENABLED=true on exactly one replica (see Limits and evaluators).

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.

Agent distribution

Exports

Feature details and limits are in Exports.

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.