Web Dashboard for Raspberry Pi

Introduction

Homepage (formerly Homer) is a minimal web dashboard that aggregates your Docker services, Pi-hole stats, weather, and custom widgets into one page. It's lightweight (40MB RAM) and works great on Pi 4+ with simple YAML configuration.

Prerequisites

• Raspberry Pi 4 or 5 (2GB+ RAM)
• Docker and Docker Compose installed
• Your homelab services already running
• Optional: Traefik or another reverse proxy

Step 1 — Create Homepage Directory and docker-compose.yml

mkdir -p ~/homepage
cd ~/homepage

Create docker-compose.yml:

version: '3.8'

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - "3000:3000"
    volumes:
      - ./config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      PUID: 1000
      PGID: 1000
    restart: always

Start it:

docker compose up -d
mkdir -p config

Access at http://localhost:3000.

Step 2 — Configure services.yaml

Homepage discovers Docker containers automatically. Create config/services.yaml:

---
- Home:
    - Pihole:
        href: http://192.168.1.50/admin
        icon: pi-hole
        description: DNS blocking
    - Portainer:
        href: http://192.168.1.50:9000
        icon: portainer
        description: Docker management
    - Homepage:
        href: http://192.168.1.50:3000
        icon: homepage
        description: This dashboard

- Media:
    - Jellyfin:
        href: http://192.168.1.50:8096
        icon: jellyfin
        description: Video streaming
        widget:
          type: jellyfin
          url: http://jellyfin:8096
          key: YOUR_API_KEY
    - Radarr:
        href: http://192.168.1.50:7878
        icon: radarr
        description: Movie automation

- Dev:
    - Gitea:
        href: http://192.168.1.50:3001
        icon: gitea
        description: Self-hosted Git
    - Woodpecker:
        href: http://192.168.1.50:8000
        icon: woodpecker
        description: CI/CD server

Step 3 — Add Widgets for Live Data

Homepage includes widgets for real-time stats. Create config/widgets.yaml:

---
- resources:
    cpu: true
    memory: true
    disk: /

- search:
    provider: google
    focus: true
    target: _blank

- openweathermap:
    apikey: YOUR_OPENWEATHER_API_KEY
    latitude: 40.7128
    longitude: -74.0060
    units: metric
    show:
      - currentConditions
      - forecast

Step 4 — Docker Auto-Discovery

Homepage automatically finds Docker containers with labels. Add these labels to your services in docker-compose.yml:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    labels:
      - homepage.group=Media
      - homepage.name=Jellyfin
      - homepage.icon=jellyfin
      - homepage.href=http://jellyfin:8096
      - homepage.description=Video streaming
    restart: always

Homepage reads these labels and populates your dashboard automatically.

Step 5 — Custom CSS and Dark Theme

Create config/custom.css for branding:

:root {
    --primary: #1e1e1e;
    --secondary: #2d2d2d;
    --accent: #00a4ff;
}

body {
    background: linear-gradient(135deg, #1e1e1e 0%, #2d2d2d 100%);
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}

.header {
    background: rgba(0, 0, 0, 0.5);
}

Restart Homepage:

docker compose restart homepage

Step 6 — Traefik Integration (Optional)

If using Traefik reverse proxy, auto-discover services:

services:
  homepage:
    labels:
      - traefik.enable=true
      - traefik.http.routers.homepage.rule=Host(`dash.example.com`)
      - traefik.http.services.homepage.loadbalancer.server.port=3000

Homepage can read Traefik's config and display all exposed services automatically.

Performance and Resource Usage

Homepage on Pi uses:

• CPU: 2-5% idle
• Memory: 40-80MB (depending on widget count)
• Disk: ~120MB image

Check resource usage:

docker stats homepage

Disable expensive widgets if memory is tight (e.g., skip weather, limit API calls to once per hour).

Troubleshooting

Widgets not loading: Verify API keys are set in widgets.yaml. Check container logs: docker compose logs homepage

Services not showing: Ensure Docker socket is mounted: /var/run/docker.sock:ro in volumes. Verify service labels are formatted correctly.

Performance slow: Disable auto-refresh on widgets. Set refresh: 3600 (refresh every hour) instead of every minute.

Custom CSS not applied: Add custom.css to config/ folder. Restart container to reload.

Homepage turns your homelab chaos into a organized dashboard. Start with core services (Pi-hole, Jellyfin, Portainer), then add widgets and custom themes as needed.

Summary

Homepage gives you a single-page overview of every service running on your homelab. With Docker auto-discovery and built-in widgets, it stays up to date as you add and remove containers — no manual link management needed.