Environment Variables

homescreen-hero uses environment variables to keep sensitive values (API keys, tokens, passwords) out of config files. Environment variables always override values in config.yaml.

Setup

Create a .env file in the project root (next to docker-compose.yml):

cp .env.example .env

Docker Compose and the backend both automatically load this file.

General

Variable	Description	Default
`HSH_PORT`	Port to run the web UI on	`8000`

Required

These are needed for homescreen-hero to function:

Variable	Description	Example
`HSH_PLEX_URL`	Your Plex server URL	`http://192.168.1.100:32400`
`HSH_PLEX_TOKEN`	Your Plex authentication token	`abc123xyztokengoeshere`

info

Don't know what the heck a Plex token is? Check out the the official Plex guide on how to find it!

Authentication

Variable	Required When	Description
`HSH_AUTH_PASSWORD`	`method: password` or `method: both`	Admin password (plaintext or bcrypt hash)
`HSH_AUTH_SECRET_KEY`	Any auth method	Secret key for JWT token signing (use a random string)

Third-Party Integrations

Only required if the corresponding integration is enabled:

Variable	Integration	Description
`HSH_TRAKT_CLIENT_ID`	Trakt	OAuth application client ID (create one here)
`HSH_MDBLIST_API_KEY`	MDBList	API key (get yours here)
`HSH_TMDB_API_KEY`	TMDb	API key (request one here)
`HSH_MAL_CLIENT_ID`	MyAnimeList	API client ID (create one here)
`HSH_TAUTULLI_API_KEY`	Tautulli	API key (Settings > Web Interface in Tautulli)
`HSH_TAUTULLI_BASE_URL`	Tautulli	Server URL (default: `http://localhost:8181`)
`HSH_SEERR_API_KEY`	Seerr	API key for Seerr / Overseerr / Jellyseerr
`HSH_SEERR_BASE_URL`	Seerr	Server URL (default: `http://localhost:5055`)

Application Paths

These control where homescreen-hero stores its data. You typically only need to change these in Docker:

Variable	Description	Default
`HOMESCREEN_HERO_CONFIG`	Path to config.yaml	`config.yaml`
`HOMESCREEN_HERO_DB`	SQLAlchemy database URL	`sqlite:///homescreen_hero.sqlite`
`HOMESCREEN_HERO_LOG_DIR`	Log file directory	`logs`

In the default Docker setup, these are pre-configured to use /data:

HOMESCREEN_HERO_CONFIG: /data/config.yaml
HOMESCREEN_HERO_DB: sqlite:////data/homescreen_hero.sqlite
HOMESCREEN_HERO_LOG_DIR: /data/logs

Override Priority

Environment variables always take priority over config.yaml values. This means you can:

Use the Setup Wizard to configure most settings
Override sensitive values with environment variables
Keep your .env file out of version control (it's in .gitignore)

tip

Set up your .env file before running the Setup Wizard. The wizard will detect existing environment variables and skip those fields, so your secrets never get written to config.yaml.

Setup​

General​

Required​

Authentication​

Third-Party Integrations​

Application Paths​

Override Priority​