How to Self-Host Homer with Docker Compose

What Is Homer?

Homer is a lightweight, static dashboard for organizing links to your self-hosted services. Everything is configured through a single YAML file — no database, no account system, no admin panel. It serves compiled static assets from an Alpine container, making it one of the fastest and most resource-efficient dashboards available. Homer also supports smart service cards that pull live data from apps like Pi-hole, Portainer, and Plex.

Official site: github.com/bastienwirtz/homer

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
100 MB of free disk space
64 MB of RAM (minimum)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  homer:
    image: b4bz/homer:v25.11.1
    container_name: homer
    volumes:
      - homer_assets:/www/assets
    ports:
      - "8080:8080"
    user: "1000:1000"    # Match your host user UID:GID
    environment:
      - INIT_ASSETS=1    # Copies example config on first run
    restart: unless-stopped

volumes:
  homer_assets:

Start the stack:

docker compose up -d

Initial Setup

Open http://your-server-ip:8080 in your browser
Homer loads immediately with the example configuration
Edit the configuration file to add your services:

# Find the volume mount path
docker volume inspect homer_assets --format '{{ .Mountpoint }}'

# Edit the config (replace path with your volume mountpoint)
sudo nano /var/lib/docker/volumes/homer_assets/_data/config.yml

Alternatively, use a bind mount instead of a named volume for easier file access:

volumes:
  - ./homer/assets:/www/assets

Configuration

Homer’s entire configuration lives in /www/assets/config.yml. Here’s a practical example:

title: "Homelab"
subtitle: "Dashboard"
logo: "logo.png"

header: true
footer: false
columns: "3"
connectivityCheck: true

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

services:
  - name: "Media"
    icon: "fas fa-film"
    items:
      - name: "Jellyfin"
        logo: "assets/tools/jellyfin.png"
        subtitle: "Media Server"
        url: "http://jellyfin.local:8096"
        target: "_blank"
      - name: "Sonarr"
        logo: "assets/tools/sonarr.png"
        subtitle: "TV Shows"
        url: "http://sonarr.local:8989"

  - name: "Infrastructure"
    icon: "fas fa-server"
    items:
      - name: "Portainer"
        logo: "assets/tools/portainer.png"
        subtitle: "Container Management"
        url: "http://portainer.local:9000"
        type: "Portainer"
        apikey: "your-portainer-api-key"
      - name: "Pi-hole"
        logo: "assets/tools/pihole.png"
        subtitle: "DNS & Ad Blocking"
        url: "http://pihole.local"
        type: "PiHole"
        apikey: "your-pihole-api-key"

Smart Service Cards

Homer supports live data cards for specific services. Set the type field on an item to enable:

Service Type	Live Data Shown
`Portainer`	Container count and status
`PiHole`	Queries blocked, percentage, total queries
`Plex`	Active streams count
`Vaultwarden`	Server status
`TrueNAS`	Pool status and alerts
`Miniflux`	Unread article count
`Linkding`	Bookmark count
`Traefik`	Router count and status
`Gatus`	Endpoint health status
`Transmission`	Active torrents

Environment Variables

Variable	Default	Description
`INIT_ASSETS`	`1`	Copy example config on first run; set to `0` after initial setup
`PORT`	`8080`	Web server port inside the container
`SUBFOLDER`	`/`	Base path for subfolder hosting (e.g., `/homer`)
`IPV6_DISABLE`	`0`	Set to `1` to disable IPv6 listening

Themes

Homer includes built-in themes. Set in config.yml:

stylesheet:
  - "assets/custom.css"

Or use the theme field:

defaults:
  layout: "columns"
  colorTheme: "auto"  # auto, light, or dark

PWA Support

Homer works as a Progressive Web App — install it on your phone or desktop for native-app-like access to your dashboard. The PWA manifest is generated automatically from your config.

Reverse Proxy

Homer serves static files and requires no special proxy configuration. See Reverse Proxy Setup.

Caddy example:

homer.yourdomain.com {
    reverse_proxy homer:8080
}

Backup

Back up the assets directory — it contains your config, custom icons, and any uploaded images:

docker compose stop
tar czf homer-backup-$(date +%Y%m%d).tar.gz /path/to/homer/assets
docker compose start

See Backup Strategy for automated approaches.

Troubleshooting

Dashboard Shows Default Config After Editing

Symptom: Your changes to config.yml don’t appear. Fix: Homer caches configuration. Hard refresh your browser (Ctrl+Shift+R). If using a named volume, confirm you’re editing the file at the correct volume mountpoint.

YAML Parsing Error (Blank Page)

Symptom: Dashboard shows nothing or displays a YAML error. Fix: Validate your config.yml with a YAML linter. Common issues: incorrect indentation, missing quotes around URLs with special characters, tabs instead of spaces.

Smart Cards Show Connection Error

Symptom: Service cards display “Connection error” instead of live data. Fix: The url must be reachable from the Homer container, not just from your browser. Use the Docker network hostname or the server’s LAN IP, not localhost.

Icons Not Loading

Symptom: Custom icons show as broken images. Fix: Place icon files in the /www/assets/tools/ directory (or any subdirectory under assets). Reference them with relative paths: logo: "assets/tools/myapp.png".

Resource Requirements

Metric	Value
RAM	~15-30 MB idle
CPU	Negligible — serves pre-compiled static files
Disk	~50 MB for application + custom assets

Frequently Asked Questions

Does Homer have user authentication?

No. Homer is a static page with no backend user system. To restrict access, place it behind a reverse proxy with authentication like Authelia or HTTP basic auth.

How do I add custom icons to Homer?

Place icon files (PNG, SVG) in the /www/assets/tools/ directory inside the container. Reference them in config.yml with logo: "assets/tools/myapp.png". You can also use Font Awesome icons with the icon: field (e.g., icon: "fas fa-server").

Does Homer support live data from services?

Yes, through smart service cards. Set the type field on a service item (e.g., type: "PiHole", type: "Portainer") and provide the API key. Homer pulls live stats for about a dozen supported service types.

How does Homer compare to Homepage?

Homer is lighter (~15 MB RAM) and simpler — single YAML file, static assets, no database. Homepage has 100+ service widget integrations, Docker auto-discovery, and more information widgets. Choose Homer for minimal resource usage and simplicity. Choose Homepage if you want deep service integrations.

Can I use Homer as my browser’s start page?

Yes. Homer works as a PWA (Progressive Web App) — you can set it as your browser homepage and install it on your phone’s home screen for native-app-like access.

Verdict

Homer is the best dashboard for users who prefer configuration-as-code. The single YAML file approach means your entire dashboard is version-controllable and trivially reproducible. At ~15 MB of RAM, it’s the lightest dashboard option available. The smart service cards give it enough interactivity for most homelab setups without the complexity of a full application.

Choose Homer if you’re comfortable editing YAML and want minimal resource usage. If you prefer a GUI for managing your dashboard, Homarr or Heimdall are better fits. If you want even simpler link organization, Flame offers a GUI-first approach.