Environment variables
Homarr offers a few environment variables, which can be used to configure the container.
With docker you can add the _FILE suffix to any environment variable, which will read the value from a file.
This is especially useful for docker secrets.
General
Using the PUID and PGID will require you to set the correct permissions on the mounted volumes and if used the docker socket. See more in the Running as a different user documentation.
| Environment Variable | Description | Possible values | Default |
|---|---|---|---|
PUID | User ID to run the container as | Any valid user ID | 0 |
PGID | Group ID to run the container as | Any valid group ID | 0 |
LOG_LEVEL | Log level to use | debug / info / warn / error | info |
BASE_URL | Public Homarr origin used by MCP OAuth metadata and redirects. Set this when a reverse proxy does not preserve the public host and protocol. | HTTP(S) origin without a path | - |
NO_EXTERNAL_CONNECTION | Disables Homarr's internet-backed requests, including update checks, weather, location search, and RSS feeds | true or false | false |
ENABLE_DNS_CACHING | Enables dns caching. Enabled by default, but if you experience issues with IPv6 or static IPs, see #4006 or disable this flag | true or false | true |
HOMARR_DISABLE_IPV6 | Disables the IPv6 listener of the internal nginx proxy, even when the host supports IPv6. IPv6 is normally disabled automatically when the host has no IPv6 configured. See #4596 | true or false | false |
HOMARR_WEBSITE_URL | Main Homarr documentation/site base used by runtime links. Must be an absolute HTTP(S) URL. | HTTP(S) URL | https://homarr.dev |
WORKSHOP_API_URL | PocketBase API used by Homarr and standalone documentation. | HTTP(S) URL | HOMARR_WEBSITE_URL |
WORKSHOP_WEB_URL | Public Workshop website used by links in Homarr, Custom Widgets, onboarding, and assistant context. | HTTP(S) URL | HOMARR_WEBSITE_URL/workshop |
Workshop service operators can find its server-only configuration in the Workshop operator guide.
Workshop service
These variables configure the separate Workshop service, not the Homarr application container.
| Environment Variable | Description | Default |
|---|---|---|
WORKSHOP_PUBLIC_ORIGIN | Public origin used in PocketBase links and email | Required in production |
PB_ALLOWED_ORIGINS | Browser origins allowed to call PocketBase | * for the public community |
WORKSHOP_IMAGE | Workshop image used by the staging Compose file | ghcr.io/homarr-labs/workshop:v2 |
WORKSHOP_EXPOSE_PORT | Host port for the combined staging service | 8090 |
PB_EXPOSE_PORT | Host port for local PocketBase development | 8090 |
DOCS_EXPOSE_PORT | Host port for local documentation development | 3003 |
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET | Optional GitHub OAuth application credentials | - |
OPENROUTER_API_KEY | Server-only upstream key that enables the Homarr Assistant provider | Provider disabled |
HOMARR_AI_DAILY_REQUEST_LIMIT | Daily Assistant request units per user | 50 |
HOMARR_AI_GLOBAL_DAILY_REQUEST_LIMIT | Daily Assistant request units shared by all users | 10000 |
HOMARR_AI_OPENROUTER_BASE_URL | OpenRouter-compatible provider endpoint | https://openrouter.ai/api/v1 |
HOMARR_AI_OPENROUTER_MODEL | Upstream model exposed through the stable homarr/model alias | Selected by the Homarr team |
HOMARR_AI_ALLOW_INSECURE_UPSTREAM | Allows an HTTP upstream for local provider tests; never use in production | false |
Authentication
See Single Sign-On for more informations.
Security
The SECRET_ENCRYPTION_KEY is required. If none is specified before starting the container, a random key will be shown in the error message and the container will exit.
| Environment Variable | Description | Possible values | Default |
|---|---|---|---|
SECRET_ENCRYPTION_KEY | Secret used to encrypt secrets in database. | 64 character hex string | - |
A random secret can be generated by using the following command: openssl rand -hex 32
Docker
| Environment Variable | Description | Possible values | Default |
|---|---|---|---|
DOCKER_SOCKET_PATHS | Comma-separated mounted Docker-compatible socket paths. Homarr discovers each path as a selectable Docker environment | For example /var/run/docker.sock,/var/run/podman.sock | - |
DOCKER_HOSTNAMES | Comma-separated plaintext TCP hostnames. Pair each hostname with the port in the same position in DOCKER_PORTS | For example localhost,docker.example.com | - |
DOCKER_PORTS | Comma-separated plaintext TCP ports paired with DOCKER_HOSTNAMES | For example 2375,2376 | - |
DOCKER_ENDPOINTS | Optional advanced JSON configuration for custom names, TLS, or restricted capabilities. It takes precedence over the simple variables above. See the Docker and Podman connection guide | A JSON array of endpoint descriptors | - |
Database
SQLite is the default; PostgreSQL is also supported. Existing MySQL installations must convert to SQLite before upgrading to v2.
| Environment Variable | Description | Possible values | Default |
|---|---|---|---|
DB_DRIVER | Database driver to use. Use better-sqlite3 for SQLite or node-postgres for PostgreSQL | better-sqlite3 / node-postgres | better-sqlite3 |
DB_DIALECT | Database dialect to use. | sqlite / postgresql | sqlite |
DB_URL | Database URL to connect to. | Any valid database URL | /appdata/db/db.sqlite |
DB_HOST | Database host to connect to. | Any valid database host | - |
DB_PORT | Database port to connect to. | Any valid database port | - |
DB_NAME | Database name to connect to. | Any valid database name | - |
DB_USER | Database user to connect with. | Any valid database user | - |
DB_PASSWORD | Database password to connect with. | Any valid database password | - |
You can either use the url or host, port, name and credentials combined. The URL will be prioritized over the other values.
Redis
By default Redis is running within the installation. (for example in Docker). However for example for K8s it can be useful to use an external Redis instance.
External redis is currently not supported with Proxmox Community Scripts
| Environment Variable | Description | Possible values | Default |
|---|---|---|---|
REDIS_IS_EXTERNAL | Whether Redis is running externally. | true / false | false |
REDIS_HOST | Hostname of the Redis instance. | Any valid hostname | - |
REDIS_PORT | Port of the Redis instance. | Any valid port | 6379 |
REDIS_USERNAME | Username to connect to the Redis instance. | Any valid username | - |
REDIS_PASSWORD | Password to connect to the Redis instance. | Any valid password | - |
REDIS_DATABASE_INDEX | Select which database of your redis instance should be used. | Any numeric index | - |
REDIS_TLS_CA | CA certificate for Redis TLS connections. If a certificate is specified the connection will use TLS. | Any valid CA certificate | - |
Proxy
| Environment Variable | Description | Possible values | Default |
|---|---|---|---|
HTTP_PROXY | HTTP proxy to use | Any valid HTTP proxy URL | - |
HTTPS_PROXY | HTTPS proxy to use | Any valid HTTPS proxy URL | - |
NO_PROXY | Comma separated list of hosts that should be excluded from proxying | Any valid hostnames | - |
Advanced deployments
The advanced deployments environment variables should only be used if you know what you are doing.
| Environment Variable | Description |
|---|---|
DB_MIGRATIONS_DISABLED | Disable db migrations. For example for helm charts. |
All public URL variables reject non-HTTP protocols, embedded credentials, query strings, and fragments, and normalize trailing slashes when Homarr or the documentation site starts.