Environment variables

Configure database, network, email, replay, limits and other Supermetry settings.

Set Supermetry options in the process environment or in ./.env; process values take precedence.

Use KEY=VALUE lines in the file. Comments, an export prefix, and quoted values are accepted. Set SUPERMETRY_ENV_FILE to read a different file.

Required

Use SUPERMETRY_DATABASE_URL, or set SUPERMETRY_DATABASE_HOST and the component settings. The installer generates SUPERMETRY_SECRET_KEY for you.

Name	Default	What it does	Required
`SUPERMETRY_DATABASE_URL`	none	PostgreSQL connection URL; takes precedence over component settings.	Y*
`SUPERMETRY_DATABASE_HOST`	none	Enables a URL assembled from the component settings below.	Y*
`SUPERMETRY_DATABASE_PORT`	`5432`	PostgreSQL port used with `SUPERMETRY_DATABASE_HOST`.	N
`SUPERMETRY_DATABASE_USER`	`POSTGRES_USER`, then `supermetry`	PostgreSQL user used with the host setting.	N
`SUPERMETRY_DATABASE_PASSWORD`	`POSTGRES_PASSWORD`, then `supermetry`	PostgreSQL password used with the host setting.	N
`SUPERMETRY_DATABASE_NAME`	`POSTGRES_DB`, then `supermetry`	PostgreSQL database used with the host setting.	N
`SUPERMETRY_DATABASE_SSLMODE`	`disable`	PostgreSQL SSL mode used with the host setting.	N
`POSTGRES_USER`	`supermetry`	Fallback database user for the bundled PostgreSQL setup.	N
`POSTGRES_PASSWORD`	`supermetry`	Fallback database password for the bundled PostgreSQL setup.	N
`POSTGRES_DB`	`supermetry`	Fallback database name for the bundled PostgreSQL setup.	N
`SUPERMETRY_BASE_URL`	none	Public HTTP or HTTPS instance URL used for links and tracking snippets.	Y
`SUPERMETRY_SECRET_KEY`	none	Standard base64 for at least 32 random bytes; encrypts stored secrets.	Y

Y* means one of the two database configuration forms is required.

Generate a key with:

openssl rand -base64 32

Network

Name	Default	What it does	Required
`SUPERMETRY_LISTEN`	`:8080`	HTTP listen address.	N
`SUPERMETRY_HOMEPAGE_URL`	`https://supermetry.com`	External brand link shown by the interface; it does not change the instance origin.	N
`SUPERMETRY_TRUSTED_PROXIES`	empty	Comma-separated proxy IPs or CIDR prefixes trusted for forwarded client addresses.	N
`SUPERMETRY_EVENT_PATH`	`/api/public/v1/events`	Public event-ingest path; must begin with `/`.	N
`SUPERMETRY_TRACKER_PATH`	`/js/script.js`	Public tracker-script path; must begin with `/`.	N
`SUPERMETRY_TRACKING_PUBLIC_PATHS`	absent (`[]` behavior)	JSON array of exact public paths that anonymous tracking may collect.	N
`SUPERMETRY_METRICS_TOKEN`	empty	Bearer token for `/metrics`; without it, metrics are limited to loopback clients.	N
`SUPERMETRY_HTTP_READ_TIMEOUT`	`30s`	Maximum request-body read time.	N
`SUPERMETRY_HTTP_WRITE_TIMEOUT`	`60s`	Maximum non-streaming response write time.	N

Email (SMTP, optional)

Leave SUPERMETRY_SMTP_HOST empty to disable email. If a host is set, SUPERMETRY_SMTP_FROM is required.

Name	Default	What it does	Required
`SUPERMETRY_SMTP_HOST`	empty	SMTP server hostname.	N
`SUPERMETRY_SMTP_PORT`	`587`	SMTP port from 1 to 65535.	N
`SUPERMETRY_SMTP_USER`	empty	SMTP username.	N
`SUPERMETRY_SMTP_PASS`	empty	SMTP password.	N
`SUPERMETRY_SMTP_FROM`	empty	Sender address; required when the SMTP host is set.	N
`SUPERMETRY_SMTP_STARTTLS`	`true`	Enables STARTTLS for SMTP.	N

Session replay

Replay is off at the instance level by default. Each project must also opt in.

Name	Default	What it does	Required
`SUPERMETRY_REPLAY_ENABLED`	`false`	Allows session replay for the instance.	N
`SUPERMETRY_REPLAY_MASK`	project value	Requires masking of all page text and inputs when set.	N
`SUPERMETRY_REPLAY_SAMPLE_RATE`	project value (`15` if unset there)	Caps the sampled percentage from 0 to 100.	N
`SUPERMETRY_REPLAY_RETENTION_DAYS`	project value (`30` if unset there)	Caps replay retention from 1 to 365 days.	N
`SUPERMETRY_REPLAY_QUOTA`	project value (`5GB` if unset there)	Sets the storage target per site, such as `500MB` or `5GB`.	N
`SUPERMETRY_REPLAY_DIR`	`$SUPERMETRY_DATA_DIR/replay`	Local replay storage directory.	N
`SUPERMETRY_REPLAY_S3_URL`	empty	S3-compatible endpoint, credentials, bucket, prefix and region in one URL.	N
`SUPERMETRY_REPLAY_S3_ENDPOINT`	empty	S3-compatible endpoint for separate-value configuration.	N
`SUPERMETRY_REPLAY_S3_BUCKET`	empty	S3 bucket.	N
`SUPERMETRY_REPLAY_S3_REGION`	empty	S3 region.	N
`SUPERMETRY_REPLAY_S3_ACCESS_KEY`	empty	S3 access key.	N
`SUPERMETRY_REPLAY_S3_SECRET_KEY`	empty	S3 secret key.	N
`SUPERMETRY_REPLAY_S3_PREFIX`	empty	Optional object-key prefix.	N

Set the five separate S3 endpoint, bucket, region, access-key and secret-key values together. The prefix is optional. SUPERMETRY_REPLAY_S3_URL takes precedence over separate values.

Limits

Durations use Go syntax such as 500ms, 2s, or 1m.

Name	Default	What it does	Required
`SUPERMETRY_MAX_ORGS_PER_USER`	`3`	Organizations a non-instance-admin user may own.	N
`SUPERMETRY_MAX_SITES_PER_ORG`	`10`	Sites a non-instance-admin user may create in one organization.	N
`SUPERMETRY_QUEUE_SIZE`	`65536`	In-memory event queue capacity.	N
`SUPERMETRY_DEDUP_ENTRIES`	`250000`	In-memory event-deduplication entry capacity.	N
`SUPERMETRY_FLUSH_EVERY`	`1s`	Interval for flushing queued events to PostgreSQL.	N
`SUPERMETRY_SESSION_FLUSH`	`10s`	Interval for flushing session state.	N
`SUPERMETRY_QUERY_TIMEOUT`	`10s`	Analytics query timeout, from `1s` through `5m`.	N
`SUPERMETRY_INGEST_RATE_IP`	`1000`	Events per second accepted from one client address.	N
`SUPERMETRY_INGEST_RATE_SITE`	`5000`	Events per second accepted for one site.	N
`SUPERMETRY_INGEST_RATE_GLOBAL`	`10000`	Events per second accepted by the process.	N

Other

Name	Default	What it does	Required
`SUPERMETRY_ENV_FILE`	`.env`	Selects the dotenv file read at startup.	N
`SUPERMETRY_SIGNUP`	`invite`	Sets signup to `invite` or `open`.	N
`SUPERMETRY_TRACKING_MODE`	absent (`identified` behavior)	Chooses `anonymous` or `identified` collection. Set `anonymous` for the strictest mode.	N
`SUPERMETRY_GSC_CLIENT_ID`	empty	Google OAuth client ID for the Search Console integration; the integration is hidden until both GSC values are set.	N
`SUPERMETRY_GSC_CLIENT_SECRET`	empty	Google OAuth client secret for the Search Console integration.	N
`SUPERMETRY_GEOIP_PATH`	bundled DB-IP Lite	Uses a MaxMind-format country database at this path.	N
`SUPERMETRY_DATA_DIR`	`./data`	Stores downloaded GeoIP databases and default replay data.	N
`SUPERMETRY_MAXMIND_ACCOUNT_ID`	empty	MaxMind account ID; set with the license key.	N
`SUPERMETRY_MAXMIND_LICENSE_KEY`	empty	MaxMind license key; set with the account ID.	N
`SUPERMETRY_MAXMIND_EDITIONS`	`GeoLite2-City,GeoLite2-ASN`	Comma-separated GeoLite2 editions to download.	N
`SUPERMETRY_ALLOW_PRIVATE_WEBHOOKS`	`false`	Allows webhook destinations on private, loopback or link-local addresses.	N
`SUPERMETRY_REFERRER_SPAM_FILE`	empty	Adds blocked referrer hostnames from a startup-only file.	N
`SUPERMETRY_INGEST_DIAG`	`0`	Set to `1` for per-event client-address diagnostics.	N
`SUPERMETRY_ADMIN_API_KEY`	empty	Development and benchmark compatibility API key.	N
`SUPERMETRY_SITES_FILE`	empty	Development and benchmark site-list file.	N

Restart Supermetry after changing startup configuration.

What you should see: supermetry starts without a configuration error naming an invalid or missing variable.