Homarr uses environment variables for configuration. This guide covers all available environment variables and their usage.
Getting Started
When cloning Homarr, you’ll find a .env.example file. Copy this file to .env and populate it with your values:
The .env file is gitignored and should never be committed to version control as it contains sensitive information.
Required Variables
These environment variables are required for Homarr to function properly.
Secret key used by Auth.js for encrypting JWTs and mail hashes. While not actively used for encryption in Homarr, it’s required by Auth.js.Example:AUTH_SECRET="supersecret"
A 32-byte (64 character) hex string used to encrypt integration secrets in the database. This is critical for security.Generate a key:Example:SECRET_ENCRYPTION_KEY="0000000000000000000000000000000000000000000000000000000000000000"
Must be exactly 64 hexadecimal characters. If not set or invalid, Homarr will display a randomly generated key on startup.
Database Configuration
Homarr supports three database drivers: SQLite, MySQL, and PostgreSQL.
DB_DRIVER
string
default:"better-sqlite3"
Database driver to use.DB_DRIVER='better-sqlite3'
Full path to your SQLite database file.DB_URL='/path/to/your/database/db.sqlite'
Must be an absolute path, not a relative path.
/appdata/db/db.sqlite MySQL can be configured using either a connection URL or individual connection parameters.Option 1: Connection URL
Complete MySQL connection string.DB_URL='mysql://user:password@host:port/database'
Option 2: Connection Parameters
PostgreSQL can be configured using either a connection URL or individual connection parameters.Option 1: Connection URL
DB_DRIVER='node-postgres'
Complete PostgreSQL connection string.DB_URL='postgres://user:password@host:port/database'
Option 2: Connection Parameters
DB_DRIVER='node-postgres'
PostgreSQL server hostname. Authentication Configuration
See the Authentication Providers page for detailed authentication configuration.
AUTH_PROVIDERS
string
default:"credentials"
Comma-separated list of authentication providers to enable. Supported values: credentials, ldap, oidc.AUTH_PROVIDERS="credentials,oidc"
How long user sessions remain valid. Accepts duration format (e.g., 30d, 7d, 12h).AUTH_SESSION_EXPIRY_TIME="30d"
URL to redirect users to after logout. Must be a valid URL.AUTH_LOGOUT_REDIRECT_URL="https://example.com/goodbye"
Redis Configuration
Redis is optional and used for caching and session management in distributed deployments.
Whether to use an external Redis server. Redis username for authentication.REDIS_USERNAME="redis_user"
Redis password for authentication.REDIS_PASSWORD="your_redis_password"
Path to TLS CA certificate for Redis connection.REDIS_TLS_CA="/path/to/ca.crt"
Redis database index to use. Application Settings
Logging verbosity level. Available options: trace, debug, info, warn, error, fatal. Full path to directory containing trusted SSL certificates. Used for connecting to services with self-signed certificates.LOCAL_CERTIFICATE_PATH='/path/to/certificates'
Must be an absolute path. In production, defaults to /appdata/trusted-certificates if not set.
API key for internal communication between nextjs-api and tasks-api. Generated automatically on container start.Generate manually:This is generated automatically and typically doesn’t need manual configuration.
Disable all external network connections for air-gapped deployments.NO_EXTERNAL_CONNECTION=true
Disable Turborepo telemetry.TURBO_TELEMETRY_DISABLED=1
Feature Flags
Enable Kubernetes integration features. UNSAFE_ENABLE_MOCK_INTEGRATION
Enable mock integration for testing purposes. Only use in development.UNSAFE_ENABLE_MOCK_INTEGRATION=true
This should only be enabled in development environments for testing.
Example Configuration
Here’s a complete example .env file for a production deployment:
# Security
AUTH_SECRET="your-random-secret-here"
SECRET_ENCRYPTION_KEY="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
# Database (PostgreSQL)
DB_DRIVER='node-postgres'
DB_URL='postgres://homarr:password@localhost:5432/homarr'
# Authentication
AUTH_PROVIDERS="credentials,oidc"
AUTH_SESSION_EXPIRY_TIME="30d"
# OIDC Configuration
AUTH_OIDC_ISSUER="https://auth.example.com"
AUTH_OIDC_CLIENT_ID="homarr"
AUTH_OIDC_CLIENT_SECRET="your-oidc-secret"
AUTH_OIDC_CLIENT_NAME="SSO Login"
# Redis (optional)
REDIS_IS_EXTERNAL=true
REDIS_HOST="localhost"
REDIS_PORT="6379"
# Application
LOG_LEVEL='info'
TURBO_TELEMETRY_DISABLED=1
Next Steps
