Menu
Article Guides

Homepage Dashboard: The Best Self-Hosted Startpage

homelabbed

• 5 min read
Homepage Dashboard: The Best Self-Hosted Startpage
Homepage Dashboard: The Best Self-Hosted Startpage

Homepage Dashboard: The Best Self-Hosted Startpage

If you've been running a homelab for any length of time, you've probably accumulated a growing list of services. Jellyfin for media, Nextcloud for files, Pi-hole for DNS, maybe Portainer for container management. And let's be honest, keeping track of all those URLs gets old fast. That's where Homepage comes in.

Homepage is a modern, fully static, lightning-fast dashboard that gives you a single pane of glass for your entire homelab. It's beautiful out of the box, incredibly customizable, and packed with integrations that actually work. After trying Heimdall, Organizr, and a handful of others, Homepage is the one that stuck for me.

Why Homepage Stands Out

There are plenty of dashboard solutions out there, so what makes Homepage special? A few things:

  • Speed: It's built with Next.js and generates static pages. The result is a dashboard that loads instantly, even on lower-powered hardware.
  • Widget ecosystem: Homepage has native support for over 100 services. We're talking Plex, Sonarr, Radarr, qBittorrent, Proxmox, Portainer, and way more. These aren't just links; they show live data.
  • Clean configuration: Everything is configured through simple YAML files. No clunky web UI for setup, just edit the files and reload.
  • Active development: The project moves fast, with new integrations and features landing regularly.

Getting Started with Docker

The easiest way to run Homepage is with Docker. Here's a simple docker-compose setup to get you started:

version: "3.3"
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: unless-stopped

A few notes on this setup:

  • The ./config volume is where all your YAML configuration files will live.
  • Mounting the Docker socket (/var/run/docker.sock) is optional but enables the Docker integration, letting Homepage show container status and stats.
  • Port 3000 is the default. Change it if you've got something else running there.

Spin it up with docker-compose up -d and hit http://your-server:3000. You'll see a default dashboard ready to customize.

Configuration Basics

Homepage uses four main configuration files, all in YAML format:

  • settings.yaml - Global settings like title, theme, and layout
  • services.yaml - Your service links and widgets
  • bookmarks.yaml - Quick links organized by category
  • widgets.yaml - Top-bar widgets for system info, weather, etc.

Let's look at each one.

settings.yaml

This controls the overall look and feel:

title: My Homelab
theme: dark
color: slate
headerStyle: boxed
layout:
  Media:
    style: row
    columns: 4
  Infrastructure:
    style: row
    columns: 3

The layout section is particularly useful. It lets you control how each service group displays, whether as rows or columns, and how many items per row.

services.yaml

This is where the magic happens. Here's an example with a few common services:

- Media:
    - Jellyfin:
        icon: jellyfin.png
        href: https://jellyfin.example.com
        description: Media streaming
        widget:
          type: jellyfin
          url: http://jellyfin:8096
          key: your-api-key-here
          enableBlocks: true

    - Sonarr:
        icon: sonarr.png
        href: https://sonarr.example.com
        description: TV show management
        widget:
          type: sonarr
          url: http://sonarr:8989
          key: your-api-key-here

    - qBittorrent:
        icon: qbittorrent.png
        href: https://qbit.example.com
        description: Torrent client
        widget:
          type: qbittorrent
          url: http://qbittorrent:8080
          username: admin
          password: your-password

- Infrastructure:
    - Proxmox:
        icon: proxmox.png
        href: https://proxmox.example.com:8006
        description: Hypervisor
        widget:
          type: proxmox
          url: https://proxmox:8006
          username: api@pam!homepage
          password: your-api-token

    - Pi-hole:
        icon: pi-hole.png
        href: https://pihole.example.com/admin
        description: DNS ad blocking
        widget:
          type: pihole
          url: http://pihole
          key: your-api-key

Each service can have an icon (Homepage includes hundreds built-in), a description, and most importantly, a widget that pulls live data from the service. The Jellyfin widget shows active streams and library counts. Sonarr shows upcoming episodes and queue status. Pi-hole displays queries blocked and percentage filtered.

widgets.yaml

These are the info widgets that appear at the top of your dashboard. Here's a solid starter setup:

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

- openmeteo:
    label: Weather
    latitude: 53.3498
    longitude: -6.2603
    timezone: Europe/Dublin
    units: metric

- datetime:
    text_size: xl
    format:
      dateStyle: long
      timeStyle: short

- search:
    provider: duckduckgo
    target: _blank

The resources widget is fantastic for keeping an eye on your server's health. It shows CPU usage, memory consumption, and disk space right on your dashboard. No need to SSH in just to check if you're running low on storage.

The weather widget uses Open-Meteo, which is free and doesn't require an API key. Just plug in your coordinates and you're good to go.

Docker Integration

One of Homepage's killer features is its Docker integration. If you mounted the Docker socket, you can show container status directly on your services. Add this to any service:

- Jellyfin:
    icon: jellyfin.png
    href: https://jellyfin.example.com
    server: my-docker
    container: jellyfin

You'll also need a docker.yaml file:

my-docker:
  socket: /var/run/docker.sock

Now Homepage will show a small status indicator on each service, turning green when the container is running and red when it's stopped. You can even click to see container stats like CPU and memory usage.

For remote Docker hosts, you can use TCP connections instead:

remote-server:
  host: 192.168.1.100
  port: 2375

Bookmarks for Quick Access

Not everything needs a widget. For simple links, use bookmarks.yaml:

- Developer:
    - GitHub:
        - abbr: GH
          href: https://github.com
    - Stack Overflow:
        - abbr: SO
          href: https://stackoverflow.com

- Social:
    - Reddit:
        - abbr: RD
          href: https://reddit.com
    - Hacker News:
        - abbr: HN
          href: https://news.ycombinator.com

Bookmarks appear in a separate section and use abbreviations instead of icons by default. They're perfect for external sites you visit frequently.

Tips for a Clean Setup

After running Homepage for a while, here are some tips that have served me well:

  • Group logically: Organize services by function (Media, Infrastructure, Monitoring) rather than alphabetically. It makes scanning the dashboard much faster.
  • Use descriptions: A one-liner under each service helps when you've got 20+ things running and can't remember what "Overseerr" does at a glance.
  • Don't overdo widgets: Not every service needs live data. Sometimes a simple link is enough. Too many widgets can slow down page load and create visual clutter.
  • Custom CSS: Homepage supports custom CSS if you want to tweak the look further. Create a custom.css file in your config directory.

Wrapping Up

Homepage has become an essential part of my homelab stack. It's the first thing I see when I open a browser, giving me instant visibility into what's running, what's downloading, and whether anything needs attention. The setup is straightforward, the configuration is clean, and the widget support is genuinely impressive.

If you're still juggling browser bookmarks or can never remember which port Radarr runs on, give Homepage a shot. It takes maybe 15 minutes to get a basic setup running, and you can refine it over time as your homelab grows.

Check out the official documentation for the full list of supported widgets and configuration options. The project is open source and available on GitHub.

Share