Deploying Homer

Introduction

Homer is a dead simple static homepage for your server, providing a clean and customizable way to organize all your web services in one place. Unlike dynamic dashboards, Homer generates a static HTML page from a YAML configuration file, making it extremely fast, lightweight, and easy to maintain.

Designed with simplicity in mind, Homer requires no database, no API calls, and no complex setup. Just configure your services in a YAML file, and Homer generates a beautiful dashboard. The application supports custom themes, icons, search functionality, and even basic service health checks.

Key highlights of Homer:

Static Generation: Fast, lightweight, no backend required
YAML Configuration: Simple, version-controllable setup
Custom Themes: Built-in themes and custom CSS support
Search Functionality: Quick filter across all services
Service Groups: Organize services by category
Health Checks: Optional status indicators for services
PWA Support: Install as a progressive web app
Keyboard Navigation: Quick access with keyboard shortcuts

This guide walks through deploying Homer on Klutch.sh using Docker, configuring your services, and customizing the appearance.

Prerequisites

Before deploying Homer on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Homer configuration
A list of services you want to organize
Basic familiarity with YAML configuration

Preparing Your Repository

Create a GitHub repository with the following structure:

homer-deploy/
├── Dockerfile
├── assets/
│   ├── config.yml
│   ├── icons/
│   └── custom.css (optional)
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the official Homer image:

FROM b4bz/homer:latest

# Environment variables
ENV INIT_ASSETS=0
ENV UID=${UID:-1000}
ENV GID=${GID:-1000}

# Copy configuration
COPY assets/ /www/assets/

# Expose the application port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/ || exit 1

Homer Configuration File

Create assets/config.yml:

---
# Homepage configuration
title: "Dashboard"
subtitle: "Homer"
documentTitle: "My Dashboard"

logo: "logo.png"
# Alternatively, an absolute URL:
# logo: "https://example.com/logo.png"

header: true
footer: '<p>Created with <span class="has-text-danger">❤️</span> using Homer</p>'

columns: "3"

# Optional: Customize behavior
defaults:
  layout: columns
  colorTheme: auto

# Optional: Set theme
# theme: default

# Optional: Custom stylesheet
# stylesheet:
#   - "assets/custom.css"

# Optional: Message
# message:
#   url: https://api.example.com/status
#   style: "is-warning"
#   title: "Notice"
#   icon: "fa fa-exclamation-triangle"
#   content: "System maintenance scheduled for tonight."

links:
  - name: "GitHub"
    icon: "fab fa-github"
    url: "https://github.com"
    target: "_blank"

  - name: "Documentation"
    icon: "fas fa-book"
    url: "https://docs.example.com"

# Services
services:
  - name: "Media"
    icon: "fas fa-film"
    items:
      - name: "Plex"
        logo: "assets/icons/plex.png"
        subtitle: "Media Server"
        url: "https://plex.example.com"
        target: "_blank"

      - name: "Jellyfin"
        logo: "assets/icons/jellyfin.png"
        subtitle: "Alternative Media Server"
        url: "https://jellyfin.example.com"

  - name: "Downloads"
    icon: "fas fa-download"
    items:
      - name: "Sonarr"
        logo: "assets/icons/sonarr.png"
        subtitle: "TV Show Manager"
        url: "https://sonarr.example.com"

      - name: "Radarr"
        logo: "assets/icons/radarr.png"
        subtitle: "Movie Manager"
        url: "https://radarr.example.com"

  - name: "Infrastructure"
    icon: "fas fa-server"
    items:
      - name: "Portainer"
        logo: "assets/icons/portainer.png"
        subtitle: "Container Management"
        url: "https://portainer.example.com"

      - name: "Uptime Kuma"
        logo: "assets/icons/uptime-kuma.png"
        subtitle: "Monitoring"
        url: "https://uptime.example.com"

Environment Variables Reference

Variable	Required	Default	Description
`INIT_ASSETS`	No	1	Install example assets (0 to disable)
`UID`	No	1000	User ID for file ownership
`GID`	No	1000	Group ID for file ownership
`PORT`	No	8080	Internal port
`SUBFOLDER`	No	-	Subfolder path if not at root
`IPV6_DISABLE`	No	0	Set to 1 to disable IPv6

Deploying Homer on Klutch.sh

Prepare Your Configuration

Create your config.yml with your services and customize as needed.

Add Icons (Optional)

Download or create icons for your services and place them in assets/icons/.

Push Your Repository to GitHub

git init
git add Dockerfile assets/ .dockerignore README.md
git commit -m "Initial Homer deployment configuration"
git remote add origin https://github.com/yourusername/homer-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “homer” or “dashboard”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Homer repository.

Configure HTTP Traffic

Select HTTP as the traffic type
Set the internal port to 8080

Set Environment Variables

Configure the following environment variables:

Variable	Value
`INIT_ASSETS`	`0`
`UID`	`1000`
`GID`	`1000`

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container and start Homer with HTTPS enabled.

Access Homer

Once deployment completes, access your dashboard at https://your-app-name.klutch.sh.

Customizing Homer

Available Themes

Homer includes several built-in themes:

# In config.yml
theme: default  # Options: default, dark

Or use auto theme switching:

defaults:
  colorTheme: auto  # Follows system preference

Custom CSS

Create assets/custom.css:

/* Custom styling */
body {
  font-family: 'Your Font', sans-serif;
}

.card {
  border-radius: 12px;
}

.card:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
}

Reference in config:

stylesheet:
  - "assets/custom.css"

Service Tags

Add tags to filter services:

items:
  - name: "Plex"
    tag: "media"
    url: "https://plex.example.com"

Health Checks

Enable service status indicators:

items:
  - name: "Plex"
    url: "https://plex.example.com"
    type: "Ping"  # Basic connectivity check

Available types: Ping, PiHole, AdGuardHome, Mealie, and more.

Dynamic Messages

Display status messages from an API:

message:
  url: "https://status.example.com/api/summary"
  mapping:
    title: 'summary.title'
    content: 'summary.content'
  refreshInterval: 10000

Keyboard Shortcuts

Key	Action
`/`	Focus search
`Escape`	Clear search
`Enter`	Open first result
`Alt + Number`	Open service by index

Icon Resources

Find icons for your services:

Troubleshooting

Configuration Not Loading

Validate YAML syntax
Check file paths are correct
Ensure config.yml is in assets folder

Icons Not Showing

Verify icon paths are relative to www/assets
Check file permissions
Use absolute URLs for external icons

Layout Issues

Adjust columns setting (1-4)
Check for HTML in text fields
Review custom CSS conflicts

Additional Resources

Conclusion

Deploying Homer on Klutch.sh creates a lightning-fast, static dashboard for organizing your services. The YAML-based configuration makes it easy to maintain and version control, while the clean design keeps focus on quick access to your applications. Whether you have a handful of services or dozens, Homer provides a simple, elegant solution for your homepage needs.