Self-hosting configuration reference

The full set of environment variables for configuring a self-hosted NervesHub: endpoints, database, storage, TLS, email, auth, and tuning.

Written By Josh Kalderimis

Last updated 4 months ago

NervesHub is configured through environment variables at runtime. This is the reference for those variables. For a walkthrough of getting an instance running, see Self-hosting NervesHub.

This list is drawn from config/runtime.exs. The exact set changes between releases, so cross-check against the version you deploy.

Secrets

Variable	Purpose
`SECRET_KEY_BASE`	Base secret for signing and encryption. Use a long random value.
`LIVE_VIEW_SIGNING_SALT`	Salt for LiveView session signing.

Web endpoint

Variable	Purpose
`HOST` / `WEB_HOST`	Public hostname for the web UI and HTTP API.
`HTTP_PORT` / `WEB_PORT` / `PORT`	Ports the web endpoint listens on.
`SESSION_COOKIE_DOMAIN`	Cookie domain for sessions.
`LOGIN_RETURN_URLS_ALLOWED_LIST`	Allowed post-login redirect URLs.
`DASHBOARD_ENABLED`	Enable the Phoenix LiveDashboard.

Device endpoint

Variable	Purpose
`DEVICE_HOST`	Hostname devices connect to.
`DEVICE_PORT`	Port for device connections.
`DEVICES_WEBSOCKET_HOST`	Websocket host advertised to devices.
`DEVICE_HOST_STATUS_PORT`	Port for device endpoint status/health.
`DEVICE_ENDPOINT_REDIRECT`	Redirect configuration for the device endpoint.
`DEVICE_SHARED_SECRETS_ENABLED`	Enable shared-secret device authentication.
`DEVICE_CONNECT_RATE_LIMIT`	Rate limit for incoming device connections.

Device endpoint TLS (mTLS)

Variable	Purpose
`DEVICE_SSL_CERTFILE` / `DEVICE_SSL_CERT`	TLS certificate (file path or inline).
`DEVICE_SSL_KEYFILE` / `DEVICE_SSL_KEY`	TLS private key (file path or inline).
`DEVICE_SSL_CACERTFILE`	CA bundle used to verify device certificates.

Database (PostgreSQL)

Variable	Purpose
`DATABASE_URL`	PostgreSQL connection URL.
`DATABASE_SSL`	Enable TLS to the database.
`DATABASE_CERT_SELF_SIGNED`	Allow a self-signed database certificate.
`DATABASE_PEM`	PEM bundle for the database TLS connection.
`DATABASE_INET6`	Use IPv6 for the database connection.
`DATABASE_POOL_SIZE` / `DATABASE_POOL_COUNT`	Connection pool sizing.
`DATABASE_AUTO_MIGRATOR`	Run migrations automatically on boot.

Firmware & archive storage

Variable	Purpose
`FIRMWARE_UPLOAD_BACKEND`	Storage backend (S3-compatible or local).
`FIRMWARE_UPLOAD_PATH`	Local path when using the local backend.
`FIRMWARE_UPLOAD_MAX_SIZE`	Max firmware upload size.
`ARCHIVE_UPLOAD_MAX_SIZE`	Max archive upload size.
`S3_BUCKET_NAME`	Bucket for firmware and archives.
`S3_REGION` / `S3_HOST`	Object storage region and endpoint.
`S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY`	Object storage credentials.
`S3_BUCKET_AS_HOST`	Use the bucket name as the host (path vs virtual-host style).

Device logs & analytics (ClickHouse, optional)

Variable	Purpose
`CLICKHOUSE_URL`	ClickHouse connection URL. Omit to run without logs/Insights.
`ANALYTICS_AUTO_MIGRATOR`	Run ClickHouse migrations automatically.
`ANALYTICS_POOL_SIZE` / `ANALYTICS_POOL_COUNT`	ClickHouse pool sizing.
`EXTENSIONS_LOGGING_DAYS_TO_KEEP`	Retention for device logs.

Email

Variable	Purpose
`SMTP_SERVER` / `SMTP_PORT`	SMTP host and port.
`SMTP_USERNAME` / `SMTP_PASSWORD`	SMTP credentials.
`SMTP_SSL` / `SMTP_TLS_VERSIONS`	SMTP transport security.
`FROM_EMAIL` / `EMAIL_SENDER`	Sender address and sender module.
`SUPPORT_EMAIL_ADDRESS` / `SUPPORT_EMAIL_PLATFORM_NAME` / `SUPPORT_EMAIL_SIGNOFF`	Support email details.

Authentication

Variable	Purpose
`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`	Google OAuth sign-in.

Observability

Variable	Purpose
`SENTRY_DSN_URL`	Error reporting to Sentry.
`OTLP_ENDPOINT`	OpenTelemetry export endpoint.
`STATSD_HOST` / `STATSD_PORT`	StatsD metrics.
`LOGGER_EXCLUSIONS`	Log filtering.
`LOG_INCLUDE_MFA`	Include module/function/arity in logs.

Branding

Variable	Purpose
`LOGO_URL` / `LOGO_URL_LIGHT` / `LOGO_URL_DARK`	Logo URLs.

Health, geo & connection tuning

Variable	Purpose
`FEATURES_HEALTH_INTERVAL_MINUTES`	How often health is reported.
`FEATURES_HEALTH_UI_POLLING_SECONDS`	How often the UI polls health.
`FEATURES_GEO_INTERVAL_MINUTES`	How often geo is reported.
`HEALTH_CHECK_DAYS_TO_RETAIN` / `DEVICE_HEALTH_DELETE_LIMIT`	Health-data retention and cleanup.
`DEVICE_LAST_SEEN_UPDATE_INTERVAL_MINUTES` / `..._JITTER_SECONDS`	Last-seen update cadence.
`DEVICE_CONNECTION_MAX_AGE_DAYS` / `DEVICE_CONNECTION_DELETE_LIMIT` / `DEVICE_CONNECTION_UPDATE_LIMIT`	Connection-history retention and cleanup.
`CLEAN_UP_SOFT_DELETED_DEVICES`	Purge soft-deleted devices.

Deployment & orchestrator tuning

Variable	Purpose
`DEFAULT_LIFO_DEPLOYMENT_QUEUE`	Default new deployment queues to LIFO instead of FIFO.
`DEPLOYMENT_CALCULATOR_INTERVAL_SECONDS`	How often deployment membership is recalculated.
`DEVICE_DEPLOYMENT_CHANGE_JITTER_SECONDS`	Jitter when devices change deployment.
`DEVICE_SOCKET_DRAINER_BATCH_SIZE` / `..._BATCH_INTERVAL` / `..._SHUTDOWN`	How device sockets are drained during deploys.

Was this helpful?

Still need help? Ask the team