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`.
`-log-level`	`HITKEEP_LOG_LEVEL`	`info`	Logging verbosity. Options: `debug`, `info`, `warn`, `error`.

Server & Networking

Settings for binding ports and clustering nodes.

Flag	Env Variable	Default	Description
`-http`	`HITKEEP_HTTP_ADDR`	`:8080`	The interface and port for the HTTP server to listen on.
`-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.

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.