Configuration Reference

HitKeep follows the 12-factor app methodology. You can configure the application using either Command Line Flags or Environment Variables.

Flags take precedence over environment variables.

General Settings

These are the most critical settings to get HitKeep running correctly.

Flag	Env Variable	Default	Description
`-public-url`	`HITKEEP_PUBLIC_URL`	`http://localhost:8080`	Required. The public-facing URL where HitKeep is accessible. Used for CORS, email links, and JWT issuer validation.
`-jwt-secret`	`HITKEEP_JWT_SECRET`	(randomly generated)	Required for production. A long random string used to sign authentication tokens. If not provided, sessions will invalidate on restart.
`-db`	`HITKEEP_DB_PATH`	`hitkeep.db`	Path to the embedded DuckDB database file. In Docker, this is mapped to `/var/lib/hitkeep/data/hitkeep.db`.
`-http`	`HITKEEP_HTTP_ADDR`	`:8080`	The interface and port for the HTTP server to listen on.
`-log-level`	`HITKEEP_LOG_LEVEL`	`info`	Logging verbosity. Options: `debug`, `info`, `warn`, `error`.

Data Management

Flag	Env Variable	Default	Description
`-archive-path`	`HITKEEP_ARCHIVE_PATH`	`archive`	Directory for exports, rollups, and archival artifacts.
`-retention-days`	`HITKEEP_DATA_RETENTION_DAYS`	`365`	Default data retention window (days) for newly created sites.

Server & Networking

Settings for binding ports and clustering nodes.

Flag	Env Variable	Default	Description
`-name`	`HITKEEP_NODE_NAME`	`hostname-timestamp`	Unique identifier for this node in a cluster.
`-bind`	`HITKEEP_BIND_ADDR`	`0.0.0.0:7946`	The address used for cluster communication (Memberlist/Gossip).
`-join`	`HITKEEP_JOIN_ADDR`	`""`	The address of an existing peer node to join when starting in clustered mode.

Email (SMTP)

Required for “Forgot Password” functionality.

Flag	Env Variable	Default	Description
`-mail-driver`	`HITKEEP_MAIL_DRIVER`	`smtp`	Currently only `smtp` is supported.
`-mail-host`	`HITKEEP_MAIL_HOST`	`""`	SMTP Server Hostname (e.g., `smtp.postmarkapp.com`).
`-mail-port`	`HITKEEP_MAIL_PORT`	`587`	SMTP Server Port.
`-mail-username`	`HITKEEP_MAIL_USERNAME`	`""`	SMTP Username.
`-mail-password`	`HITKEEP_MAIL_PASSWORD`	`""`	SMTP Password.
`-mail-encryption`	`HITKEEP_MAIL_ENCRYPTION`	`tls`	Encryption mode: `tls` (STARTTLS), `ssl` (Implicit TLS), or `none`.
`-mail-from-address`	`HITKEEP_MAIL_FROM_ADDRESS`	`hitkeep@localhost`	The email address messages are sent from.
`-mail-from-name`	`HITKEEP_MAIL_FROM_NAME`	`HitKeep`	The sender name displayed in inboxes.
`-mail-insecure-skip-verify`	`HITKEEP_MAIL_INSECURE_SKIP_VERIFY`	`false`	Set to `true` to accept self-signed certificates (not recommended for production).

Rate Limiting

HitKeep includes a built-in rate limiter to protect against abuse. Limits are defined per IP address.

Ingestion (`/ingest`)

High throughput endpoint for tracking scripts.

Flag	Env Variable	Default	Description
`-ingest-rate`	`HITKEEP_INGEST_RATE_LIMIT`	`20.0`	Requests per second allowed per IP.
`-ingest-burst`	`HITKEEP_INGEST_BURST`	`40`	Maximum burst size allowed per IP.

API (`/api/*`)

General data retrieval endpoints.

Flag	Env Variable	Default	Description
`-api-rate`	`HITKEEP_API_RATE_LIMIT`	`10.0`	Requests per second allowed per IP.
`-api-burst`	`HITKEEP_API_BURST`	`20`	Maximum burst size allowed per IP.

Authentication (`/api/login`, etc)

Strict limits to prevent brute-force attacks.

Flag	Env Variable	Default	Description
`-auth-rate`	`HITKEEP_AUTH_RATE_LIMIT`	`2.0`	Requests per second allowed per IP.
`-auth-burst`	`HITKEEP_AUTH_BURST`	`5`	Maximum burst size allowed per IP.

Trusted Proxies

Use this when HitKeep is behind a reverse proxy or load balancer and you want to trust forwarded headers. This affects both rate limiting and GeoIP resolution.

Flag	Environment Variable	Default	Description
`-trusted-proxies`	`HITKEEP_TRUSTED_PROXIES`	`""`	Comma-separated list of trusted proxy CIDRs (e.g. `10.0.0.0/8,127.0.0.1/32`).

Behavior:

If empty, HitKeep trusts proxy headers from any direct peer.
If set, HitKeep only trusts proxy headers when the direct connection IP is in the trusted list.

Internals (Advanced)

Configuration for embedded components. You generally do not need to change these unless you are developing HitKeep or have port conflicts on the host network.

Flag	Env Variable	Default	Description
`-nsq-tcp-address`	`HITKEEP_NSQ_TCP_ADDRESS`	`127.0.0.1:4150`	Bind address for the embedded NSQ TCP interface.
`-nsq-http-address`	`HITKEEP_NSQ_HTTP_ADDRESS`	`127.0.0.1:4151`	Bind address for the embedded NSQ HTTP API.