Skip to main content

Installation

homescreen-hero can be installed using Docker (recommended) or run directly with Python.

Prerequisites

Create a docker-compose.yml file:

services:
  homescreen-hero:
    image: 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, or use the .env.example file provided on GitHub

# 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

Update to Latest Version​

docker compose pull
docker compose up -d

Unraid (Community Apps)​

homescreen-hero is available on the Unraid Community Apps store!

  1. Open the Apps tab in your Unraid dashboard
  2. Search for homescreen-hero
  3. Click Install
  4. Fill out the environment variables you need and click Apply
info

If you want to test out features before they are released, simply replace the :latest tag in the Repository field with :nightly to switch to using the nightly Docker image.

Windows Portable (Beta)​

Download​

Download the latest homescreen-hero-portable.zip from the latest release page

Quick Start​

  1. Extract the homescreen-hero-portable.zip to any folder on your machine
  2. Open the README.txt file and follow the setup instructions for configuring the app
Port Already in use?

In the root directory, create a file named .env and add this line HSH_PORT=9000

Need more help?

Use the included .env.example or checkout the Environment Variables page for more info on using environment variables

Running at Startup​

To have homescreen-hero start automatically with Windows:

  1. Press Win+R, type shell:startup, press Enter
  2. Right-click in the folder > New > Shortcut
  3. Browse to start.bat in this folder
  4. Click Next, name it "homescreen-hero", click Finish
Hide the console window

The console window will be visible. For a hidden background service, look into Task Scheduler or NSSM (nssm.cc).

Updating​

  1. Download the latest portable release
  2. Extract it to a new folder
  3. Copy your data\ folder (and your .env file if using environment variables) from the old version to the new one
  4. Run start.bat in the new folder

If you prefer to run without Docker:

# Clone the repository
git clone https://github.com/trentferguson/homescreen-hero.git
cd homescreen-hero

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate  # Windows

# Install dependencies
pip install -r homescreen_hero/requirements.txt

# Create data directory
mkdir -p data

# Run the server
uvicorn homescreen_hero.web.app:app --host 0.0.0.0 --port 8000

Data Persistence​

All data is stored in the ./data directory (or /data in Docker):

  • 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.

First-Time Setup​

  1. Open http://localhost:[HSH_PORT]in your browser (Default: 8000)
  2. Complete the Setup Wizard to connect your Plex server and select libraries
  3. Configure any additional integrations (optional)
  4. Enable/Disable auto rotation and configure your rotation settings

You're ready to go!