Skip to main content

Quick Start

Get homescreen-hero up and running in minutes with minimal configuration. For more detailed setup options, alternative installation methods, or customization, see the Installation Guide.

Prerequisites

Setup​

Security Tip

Want to keep secrets out of config files? Copy .env.example to .env and fill in your sensitive values before running the wizard. The wizard will automatically use your environment variables instead of writing them to config.yaml.

git clone https://github.com/trentferguson/homescreen-hero.git
cd homescreen-hero
mkdir -p data
docker-compose up -d
Open http://localhost:8000 and the Setup Wizard will guide you through configuration.

Open http://localhost:8000 and the Setup Wizard will guide you through configuration.

note

All info entered into the Setup Wizard (except for passwords) is stored as plaintext in config.yaml. See the Environment Variables page for best practices on managing sensitive values.

Your First Rotation​

After installing homescreen-hero, follow these steps to get your collections rotating:

1. Create Your First Group​

Groups are how homescreen-hero knows which collections to rotate. Nothing will rotate until you create at least one Group.

  • Go to the Groups page
  • Click Create Group
  • Give it a name (e.g., "Holiday Collections" or "Personal")
  • Configure the the Groups's Rotation Settings & Visbility Settings

2. Add Collections​

  • In your new Group, scroll down to the Content Sources section
  • Select which collections from your library you'd like in this group
  • When this group is Active, this is the list of collections that homscreen-hero will select from to feature on your homescreen

3. Set Your Schedule​

  • If you did not specify during the Setup Wizard, click the Settings Icon in the top right of the app
  • Click the Rotation Schedule Config section and fill out your desired settings
  • Check out Collection Rotation for more information on some of these settings

4. Verify It's Working​

  • The Dashboard shows the collections currently featured on your homescren and the next scheduled rotation
  • If you don't want to wait until the next scheduled rotation, you can manually trigger a rotation with the Run Rotation Now button
  • You can also simulate a rotation by clicking the down arrow on the Run Rotation Now button and click Simulate Rotation
  • If you have it enabled on the dashboard, check Recent Rotations widget to see past rotations

For more detailed setup options, check out the Installation Guide.