Configure a deployment

Configuration in Netstamp comes from three places:

1. Deployment configuration controls the controller, database, public origin, secrets, and workers through environment variables. Changes require a controller restart.
2. System settings control access policy, email, and external identity providers at runtime.
3. Build configuration compiles public analytics and documentation values into the web bundles.

Choose the source that owns the setting you want to change. A runtime setting cannot override deployment configuration, and changing a build variable on an existing container does not rebuild its frontend.

Deployment configuration

The controller reads environment variables and an optional .env file from the working directory or server/. Environment variables take precedence over values loaded from .env. Docker Compose reads the project .env and forwards the supported values to the container.

Durations use Go syntax such as 250ms, 5s, 30m, or 168h. Boolean values use true or false. Keep secrets stable, unique, and outside version control.

The release .env.example contains the required secrets and production URL settings. Add only the overrides you need from this page.

Runtime system settings

Settings that operators may change while Netstamp is running are stored by the controller under Admin → System settings:

SMTP and provider credentials are encrypted with SYSTEM_SETTINGS_ENCRYPTION_KEY. Web analytics are build-time settings and are not configured in the administration UI.

Compose variables

Pin image values for production. The logical Compose volume is netstamp-postgres.

Controller core

Every non-local deployment must replace the database password and all four application keys with independent random values of at least 32 characters.

HTTP and public origin

PUBLIC_BASE_URL must contain only the scheme and host. Non-local environments require it, and production requires HTTPS.

Database

Use TLS verification when database traffic crosses an untrusted network. The standard Compose stack keeps it on the private Compose network.

Sessions, passwords, and tokens

Changing a hash key invalidates credentials protected by it.

Background workers

Disabling a worker pauses its work; it does not delete configuration or queued jobs.

Tracing

Leave the endpoint empty to disable trace export.

Probe agent

The installer writes the controller URL, ID, and secret. The remaining values are local tuning overrides.

All numeric capacities and durations must be greater than zero. Maximum backoff must be at least the initial backoff.

Web application build variables

The browser always calls the same-origin API path generated from the OpenAPI contract (/api/v1). VITE_NETSTAMP_API_PROXY_TARGET only controls the local Vite development proxy and is not compiled into the browser bundle.

Demo credentials are public values compiled only into the dedicated demo image. The remaining values configure optional trackers and are also compiled into the frontend. Changing a container’s runtime environment does not modify an already-built bundle.

Every browser-visible VITE_* value is public; never put a private secret in one.

Documentation build variables

The docs support the same optional trackers and consent controls with the PUBLIC_NETSTAMP_* prefix. Google and Meta use only the canonical PUBLIC_NETSTAMP_GOOGLE_TAG_ID and PUBLIC_NETSTAMP_META_PIXEL_ID names.