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.
-data-path	HITKEEP_DATA_PATH	data	Base directory for tenant-local analytics databases and other local state. In multiteam installs, this whole tree is part of the backup boundary.
-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.

Database Backups

HitKeep can periodically export all live databases (shared + per-tenant) to Parquet snapshots. Set HITKEEP_BACKUP_PATH to enable.

Flag	Env Variable	Default	Description
-backup-path	HITKEEP_BACKUP_PATH	"" (disabled)	Backup destination — local directory or s3:// URL. Empty disables backups.
-backup-interval	HITKEEP_BACKUP_INTERVAL	60	Minutes between backup runs.
-backup-retention	HITKEEP_BACKUP_RETENTION	24	Number of snapshots to keep before pruning older ones.

When HITKEEP_BACKUP_PATH is an s3:// URL, the same S3 credentials configured below are used. For local paths, old snapshots beyond the retention count are automatically deleted. For S3, configure lifecycle policies on your bucket.

See Backups and Restore and S3 Backups for concrete layouts and restore examples.

S3 Archive Storage

When HITKEEP_ARCHIVE_PATH is set to an s3:// URL, HitKeep writes Parquet archives directly to S3-compatible storage via DuckDB’s httpfs extension.

Authentication mode is auto-detected:

• If HITKEEP_S3_ACCESS_KEY_ID and HITKEEP_S3_SECRET_ACCESS_KEY are both set, HitKeep uses static credentials.
• If neither is set, HitKeep uses the AWS credential chain (environment variables, shared config, instance profiles, STS, SSO).

Flag	Env Variable	Default	Description
-s3-access-key-id	HITKEEP_S3_ACCESS_KEY_ID	""	AWS access key ID for static credential authentication.
-s3-secret-access-key	HITKEEP_S3_SECRET_ACCESS_KEY	""	AWS secret access key for static credential authentication.
-s3-session-token	HITKEEP_S3_SESSION_TOKEN	""	STS temporary session token (used with static credentials).
-s3-region	HITKEEP_S3_REGION	us-east-1	S3 region for the archive bucket.
-s3-endpoint	HITKEEP_S3_ENDPOINT	""	Custom S3-compatible endpoint (e.g., MinIO, Cloudflare R2, DigitalOcean Spaces).
-s3-url-style	HITKEEP_S3_URL_STYLE	""	URL addressing style: path or vhost. Empty uses the DuckDB default.
-s3-use-ssl	HITKEEP_S3_USE_SSL	true	Set to false for local S3-compatible endpoints over HTTP (e.g., MinIO dev).

See S3 Backups for end-to-end examples with AWS S3, MinIO, and Cloudflare R2.

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.