Docker Setup

The recommended way to run homescreen-hero is with Docker Compose.

Docker Compose

Create a docker-compose.yml file:

services:
  homescreen-hero:
    image: ghcr.io/trentferguson/homescreen-hero:latest
    container_name: homescreen-hero
    ports:
      - "${HSH_PORT:-8000}:8000"
    environment:
      # Config and data paths
      HOMESCREEN_HERO_CONFIG: /data/config.yaml
      HOMESCREEN_HERO_DB: sqlite:////data/homescreen_hero.sqlite
      HOMESCREEN_HERO_LOG_DIR: /data/logs
      # Sensitive values (loaded from .env file)
      HSH_PLEX_URL: ${HSH_PLEX_URL:-}
      HSH_PLEX_TOKEN: ${HSH_PLEX_TOKEN}
      HSH_AUTH_PASSWORD: ${HSH_AUTH_PASSWORD:-}
      HSH_AUTH_SECRET_KEY: ${HSH_AUTH_SECRET_KEY:-}
      HSH_TRAKT_CLIENT_ID: ${HSH_TRAKT_CLIENT_ID:-}
      HSH_MDBLIST_API_KEY: ${HSH_MDBLIST_API_KEY:-}
      HSH_TAUTULLI_API_KEY: ${HSH_TAUTULLI_API_KEY:-}
      HSH_TAUTULLI_BASE_URL: ${HSH_TAUTULLI_BASE_URL:-}
      HSH_SEERR_API_KEY: ${HSH_SEERR_API_KEY:-}
      HSH_SEERR_BASE_URL: ${HSH_SEERR_BASE_URL:-}
    volumes:
      - ./data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8000/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3

Environment File

Create a .env file in the same directory:

# General
HSH_PORT=8000  # Port to run the web UI on (default: 8000)

# Required - Plex
HSH_PLEX_URL=http://your-plex-ip:32400
HSH_PLEX_TOKEN=your-plex-token

# Optional - Authentication
HSH_AUTH_PASSWORD=your-admin-password
HSH_AUTH_SECRET_KEY=random-secret-for-jwt

# Optional - Third-party integrations
HSH_TRAKT_CLIENT_ID=your-trakt-client-id
HSH_MDBLIST_API_KEY=your-mdblist-api-key

# Optional - Tautulli analytics
HSH_TAUTULLI_API_KEY=your-tautulli-api-key
HSH_TAUTULLI_BASE_URL=http://your-tautulli-ip:8181

# Optional - Seerr (Overseerr/Jellyseerr)
HSH_SEERR_API_KEY=your-seerr-api-key
HSH_SEERR_BASE_URL=http://your-seerr-ip:5055

Start the Container

docker compose up -d

View Logs

docker compose logs -f

Update to Latest Version

docker compose pull
docker compose up -d

Data Persistence

All data is stored in the ./data directory:

• config.yaml - Your configuration settings
• homescreen_hero.sqlite - Database with collection history and analytics
• logs/ - Application logs

Back up this directory to preserve your configuration and history.