Thomas
150d38be62
* feat(docker): add endpoint filtering and setup assistant * fix(docker): simplify environment setup * test(docker): cover demo endpoint filtering * refactor(docker): use accordion for setup suggestions * fix(docker): use docker icon for setup assistant * refactor(docker): simplify assisted service setup * refactor(docker): reuse shared translations * fix(docker): address review feedback
122 lines
12 KiB
Plaintext
122 lines
12 KiB
Plaintext
---
|
|
title: Environment variables
|
|
tags:
|
|
- Configuration
|
|
- Docker
|
|
- Advanced
|
|
- Env
|
|
- Environment variables
|
|
- Variables
|
|
- Database
|
|
- Redis
|
|
- Secrets
|
|
---
|
|
|
|
Homarr offers a few environment variables, which can be used to configure the container.
|
|
|
|
:::info
|
|
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](https://docs.docker.com/engine/swarm/secrets/#use-secrets-in-compose).
|
|
:::
|
|
|
|
## General
|
|
|
|
:::warning
|
|
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](/docs/advanced/running-as-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` |
|
|
| `NO_EXTERNAL_CONNECTION` | Disables Homarr's internet-backed requests, including update checks, weather, 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](https://github.com/homarr-labs/homarr/issues/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](https://github.com/homarr-labs/homarr/issues/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/operator#environment-variables).
|
|
|
|
## Authentication
|
|
|
|
See [Single Sign-On](/docs/advanced/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 | - |
|
|
|
|
:::info
|
|
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](/docs/integrations/docker) | A JSON array of endpoint descriptors | - |
|
|
|
|
## Database
|
|
|
|
| Environment Variable | Description | Possible values | Default |
|
|
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------- |
|
|
| `DB_DRIVER` | Database driver to use. Currently `better-sqlite3` is used for sqlite, `mysql2` for mysql and `node-postgres` for postgresql | `better-sqlite3` / `mysql2` / `node-postgres` | `better-sqlite3` |
|
|
| `DB_DIALECT` | Database dialect to use. | `sqlite` / `mysql` / `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.
|
|
|
|
:::note
|
|
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
|
|
|
|
:::warning
|
|
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 Docusaurus starts.
|