This guide explains how to configure your self-hosted Unleash instance when running it via Docker Compose or the Docker CLI.
When running Unleash using Docker, configuration is managed through environment variables.
Unleash requires a PostgreSQL database to store its data. You must provide connection details using environment variables.
For detailed PostgreSQL SSL configuration options via environment variables, refer to the node-postgres documentation on SSL. Ensure file paths for certificates (DATABASE_SSL_*_FILE) are accessible inside the running container (for example, via Docker volumes).
If you experience intermittent database connection errors or timeouts, particularly after periods of inactivity, a network component (like a firewall or load balancer) between the Unleash server and the PostgreSQL database may be closing idle TCP connections. If the network component’s idle timeout is shorter than the connection pool’s idle timeout (DATABASE_POOL_IDLE_TIMEOUT_MS), the pool may try to use a connection that the network device has already terminated.
Solution:
DATABASE_POOL_IDLE_TIMEOUT_MS environment variable (default: 30000 ms), is configured to be less than the network device’s idle timeout setting. For instance, if your firewall closes idle connections after 60 seconds, consider keeping or setting DATABASE_POOL_IDLE_TIMEOUT_MS to 30000 (30 seconds).It is highly recommended to back up your Unleash database, especially before upgrades or significant changes. When running PostgreSQL within a Docker container, use docker exec to run the standard pg_dump (backup) and psql (restore) commands inside the container.
Identify container name: Find your PostgreSQL container’s name or ID (for example, using docker ps).
Create a backup: Run the following command on your host machine. It executes pg_dump inside the container and saves the output to a .dump file on your host.
Restore from backup: Run the following command on your host machine. It executes psql inside the container, reading the specified backup file from your host.
If you are moving an instance (for example, to a new cloud provider or cluster) and need full fidelity, use a database dump and restore instead of API export/import.
This is the safest way to keep data parity. Use export/import primarily for ongoing synchronization of feature flags, not full migrations.
To connect to a PostgreSQL database using a self-signed certificate, you need to:
DATABASE_SSL_REJECT_UNAUTHORIZED environment variable to false. Disabling this check bypasses validation that the server certificate is signed by a trusted CA; only use this when you fully trust the network path and the server identity.DATABASE_SSL_CA_FILE variable (pointing to the certificate file mounted inside the container) or include the certificate string within the JSON object passed to DATABASE_SSL_CA_CONFIG.Set the public URL where your Unleash instance can be accessed using the environment variable UNLEASH_URL. For example, https://unleash.mycompany.com or https://app.mycompany.com/unleash. This URL is used for creating password reset links, signup links for new users, and links within integrations, such as Slack or Datadog.
Use the EDGE_URL environment variable to set the public URL for your Enterprise Edge instance. For example, https://yourcompany.edge.getunleash.io. This URL appears on the Admin > API access page alongside the Client and Frontend API URLs, so your team can copy it when connecting SDKs to Edge.
Configure an SMTP server to enable password resets and user welcome emails. If not configured, self-service password resets will not be available.
If emails fail to send or contain errors:
EMAIL_* environment variables are correctly set for your SMTP provider.UNLEASH_URL is the complete public URL for your instance, including the http:// or https:// protocol prefix.EMAIL_PORT and EMAIL_SECURE match your SMTP server’s requirements (for example, port 587 or 465 often requires EMAIL_SECURE=true).EMAIL_SECURE=true, ensure it’s trusted by mounting the PEM file into the container and setting the NODE_EXTRA_CA_CERTS environment variable to its path inside the container.Controls requests per minute per IP for specific API endpoints.
If your Unleash server needs to make outgoing requests (for example, for integrations, webhooks, version checks) through an HTTP/HTTPS proxy, you can configure this using standard proxy environment variables.
HTTP_PROXY: URL of the HTTP proxy (for example, http://proxy.mycompany.com:8080).HTTPS_PROXY: URL of the HTTPS proxy (for example, http://secureproxy.mycompany.com:8081).NO_PROXY: Comma-separated list of hosts or domains that should bypass the proxy.Set these environment variables when starting your Unleash container.
While specific minimums depend heavily on usage patterns (number of flags, frequency of requests, number of connected SDKs), a general starting point for the Unleash server container could be:
For the PostgreSQL database, consider:
For example, you might consider some of the following managed PostgreSQL services and machine types:
db.t4g.small (2 vCPU / 2 GiB RAM).B2s (Burstable, 2 vCPU / 4 GiB RAM).db-n1-standard-1 (1 vCPU / 3.75 GiB RAM) as the starting point.Monitor resource usage and adjust based on your specific load.
By default, Unleash uses password-based login. When using passwords, Unleash enforces strong passwords:
To learn more about managing users, implementing single sign-on instead of passwords, setting up access controls, and using audit logs, read the User Management, Access Controls and Auditing guide.
As your feature flag usage grows, ensuring your Unleash setup can handle the load is crucial. To learn how to implement high availability, improve resilience, and apply other scaling strategies, read the Scaling Unleash guide.