Skip to main content

Installation

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

Prerequisites​

  • A Plex Media Server with admin access
  • Your Plex authentication token (How to find your token)
  • Docker (recommended) or Python 3.9+

Docker Installation​

See Docker Setup for the full Docker Compose configuration.

Using Docker Run​

docker run -d \
  --name homescreen-hero \
  -p 8000:8000 \
  -v /path/to/data:/app/data \
  -e HSH_PLEX_URL=http://your-plex-ip:32400 \
  -e HSH_PLEX_TOKEN=your-plex-token \
  ghcr.io/trentferguson/homescreen-hero:latest

Unraid (Community Apps)​

PLACEHOLDER: In the process of getting the homescreen-hero docker image on the Unraid Community Apps page. Installation will be as simple as searching for homescreen-hero, click install, and fill out all necessary environment variables.

Manual Installation​

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

First-Time Setup​

  1. Open http://localhost:8000 in your browser
  2. Complete the QuickStart wizard to connect your Plex server
  3. Select which libraries and collections to manage
  4. Configure your rotation schedule

You're ready to go!