← Back to Notes
homepagedockerhomelabdashboardself-hosting

Homepage — Advanced Dashboard Configuration

A deep dive into configuring Homepage — the self-hosted dashboard. Covers settings, widgets, service integration, icons, and security considerations.

Homepage (gethomepage.dev) is more than a list of links — it's a high-performance dashboard that integrates directly with Docker and third-party APIs to show live stats from every service on your server.

This guide assumes Homepage is already running. If you haven't installed it yet, start with the RPi5 Home Server — Part 1 guide.

Useful references:

Configuration File Overview

Homepage is configured via YAML files in your appdata directory:

/mnt/data/docker-compose/appdata/homepage/
+-- settings.yaml    < Global appearance and layout
+-- widgets.yaml     < Top-of-page system metrics
+-- services.yaml    < Your service links and integrations
+-- bookmarks.yaml   < Quick bookmark links
+-- docker.yaml      < Docker socket configuration
T
TIP

Homepage hot-reloads configuration changes. Save any YAML file and your dashboard updates instantly — no container restart needed.

settings.yaml — Global Appearance

Controls the overall look and feel of the dashboard.

title: "Home Server"
background:
  image: https://example.com/your-background.jpg
  blur: 0
  saturate: 100
theme: dark
color: slate
layout:
  Infrastructure:
    style: cols
    columns: 2
  Media:
    style: cols
    columns: 3
  Tools:
    style: cols
    columns: 4

Key settings:

  • title — browser tab title
  • background.image — URL or local path to a background image
  • background.blur — blur amount in pixels (0 = sharp)
  • theme — dark or light
  • color — accent color scheme (slate, gray, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose)
  • layout — defines how service groups are displayed and how many columns each group uses

widgets.yaml — System Metrics

Widgets appear at the top of the dashboard and provide immediate feedback on your server's hardware status.

- logo:
    icon: https://raw.githubusercontent.com/gethomepage/homepage/main/public/android-chrome-192x192.png

- resources:
    cpu: true
    memory: true
    temp: true

- datetime:
    format:
      timeStyle: short
      dateStyle: long

- disk:
    label: "Data Disk"
    path: /mnt/data

resources shows live CPU usage, RAM usage, and temperature. The temp: true option is particularly useful on the Raspberry Pi 5 where thermal management matters.

disk shows used/free space for a given path. Set path: /mnt/data to monitor your NVMe data drive.

datetime shows the current time and date in your configured locale.

services.yaml — Service Integration

This is the heart of the dashboard. Services are organized into named groups, each with individual entries.

Basic service entry

- Infrastructure:
    - Homepage:
        icon: homepage.png
        href: http://192.168.1.150:3000
        description: This Dashboard
        container: homepage

icon — name from dashboardicons.com, a URL, or a local file placed in /appdata/homepage/icons/. Most popular self-hosted apps have icons available by name.

href — where clicking the service takes you.

description — subtitle shown under the service name.

container — the Docker container name. When provided, Homepage shows a live green/yellow/red status dot indicating whether the container is running.

Service with a widget

Widgets pull live data from the service's API and display it on the card:

- Infrastructure:
    - Pi-hole:
        icon: pi-hole.png
        href: http://192.168.1.150:8082/admin
        description: DNS Ad Blocking
        widget:
          type: pihole
          url: http://192.168.1.150:8082
          key: your_pihole_api_key

    - Glances:
        icon: glances.png
        href: http://192.168.1.150:61208
        description: System Monitor
        widget:
          type: glances
          url: http://192.168.1.150:61208
          metric: cpu

    - qBittorrent:
        icon: qbittorrent.png
        href: http://192.168.1.150:8090
        description: Torrent Client
        widget:
          type: qbittorrent
          url: http://192.168.1.150:8090
          username: admin
          password: your_password

Full services.yaml example

- Infrastructure:
    - Homepage:
        icon: homepage.png
        href: http://192.168.1.150:3000
        description: This Dashboard
        container: homepage
    - Filebrowser:
        icon: filebrowser.png
        href: http://192.168.1.150:8080
        description: File Manager
        container: filebrowser
    - Pi-hole:
        icon: pi-hole.png
        href: http://192.168.1.150:8082/admin
        description: DNS Ad Blocking
        container: pihole
        widget:
          type: pihole
          url: http://192.168.1.150:8082
          key: your_pihole_api_key
    - Glances:
        icon: glances.png
        href: http://192.168.1.150:61208
        description: System Monitor
        widget:
          type: glances
          url: http://192.168.1.150:61208
          metric: cpu

- Downloads:
    - qBittorrent:
        icon: qbittorrent.png
        href: http://192.168.1.150:8090
        description: Torrents (via Mullvad)
        container: qbittorrent
        widget:
          type: qbittorrent
          url: http://192.168.1.150:8090
          username: admin
          password: your_password
    - MeTube:
        icon: metube.png
        href: http://192.168.1.150:8081
        description: Video Downloader
        container: metube
    - jDownloader2:
        icon: jdownloader.png
        href: http://192.168.1.150:5800
        description: Bulk Downloader
        container: jdownloader2

- Media:
    - Kavita:
        icon: kavita.png
        href: http://192.168.1.150:5000
        description: Digital Library
        container: kavita
    - Calibre Web:
        icon: calibre-web.png
        href: http://192.168.1.150:3004
        description: Book Reader
        container: calibre-web

- Tools:
    - IT Tools:
        icon: it-tools.png
        href: http://192.168.1.150:8083
        description: Developer Utilities
        container: it-tools
    - Stirling PDF:
        icon: stirling-pdf.png
        href: http://192.168.1.150:8084
        description: PDF Toolkit
        container: stirling-pdf

Finding Icons

Homepage supports multiple icon sources:

Dashboard Icons — the easiest option. Use any name from dashboardicons.com directly:

icon: pihole.png
icon: qbittorrent.png
icon: kavita.png

Remote URL — use any image URL:

icon: https://example.com/my-icon.png

Local file — place .png or .svg files in /mnt/data/docker-compose/appdata/homepage/icons/ and reference by name:

icon: my-custom-logo.png

docker.yaml — Live Container Status

Connecting Homepage to the Docker socket turns your static dashboard into a live monitoring station. Instead of just links, you get real-time status dots, CPU usage, and memory consumption for every container on your Pi.

Prerequisite: Ensure your docker-compose.yml includes the Docker socket mount under the Homepage service:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Step 1 — Define the Docker instance

Create or edit appdata/homepage/docker.yaml:

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

This tells Homepage where your Docker engine lives. Since everything runs on a single Pi, we point it to the local Unix socket.

Step 2 — Add the global Docker widget

Add this to your appdata/homepage/widgets.yaml alongside your existing widgets:

- docker:
    label: "Container Stack"
    server: my-pi-docker
    container_status: true
    cpu: true
    memory: true

This adds a live monitoring table at the top of your dashboard showing every container's status (Running/Stopped), real-time CPU usage, and RAM consumption. Place it after your resources and datetime widgets for a complete at-a-glance health check.

server: my-pi-docker must match the name defined in docker.yaml exactly — this is how Homepage knows which Docker instance to query.

Step 3 — Link individual services to their containers

To get live status dots on individual service cards, add container and server fields to each entry in services.yaml:

- Infrastructure:
    - Filebrowser:
        icon: filebrowser.png
        href: http://192.168.1.150:8080
        description: File Manager
        container: filebrowser
        server: my-pi-docker

The container value must match the container_name in your docker-compose.yml exactly. Homepage uses this to find the right container and display its live status.

Why this matters

  • Instant troubleshooting — if a service stops working, you see a red dot on the dashboard immediately without running docker ps in a terminal
  • Resource visibility — the Pi 5 has 16GB of RAM but it's still useful to spot a container that's leaking memory or unexpectedly spiking CPU
  • Zero extra configuration — once docker.yaml is set up, Homepage automatically finds all containers for the global widget without you having to list them individually
N
NOTE

Mounting docker.sock gives Homepage read-only access to your Docker engine — it can observe container state but cannot start, stop, or modify containers. This is safe for a local dashboard. Never expose Homepage directly to the internet without a VPN or reverse proxy in front of it.

Security Considerations

Homepage does not have a built-in login screen. Since it displays server information and service links, consider these mitigations:

  • Network isolation — Homepage is only accessible on your local network and via Tailscale. It is not exposed to the public internet.
  • HOMEPAGE_ALLOWED_HOSTS — always set this to your Pi's specific IP and localhost to prevent host header attacks. Avoid using * in production.
  • Sensitive widgets — avoid storing passwords in services.yaml in plain text if others have access to your server. Use environment variables where supported.

Troubleshooting

Dashboard shows "Access Denied" or "Invalid Host"

Ensure HOMEPAGE_ALLOWED_HOSTS in docker-compose.yml includes your Pi's IP:

- HOMEPAGE_ALLOWED_HOSTS=192.168.1.150:3000,localhost:3000

Container status dots not showing

Verify the Docker socket is mounted correctly in docker-compose.yml:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

And confirm docker.yaml exists in your appdata folder with the socket configuration above. Also make sure the server: value in services.yaml matches the name in docker.yaml exactly.

YAML parsing errors

Homepage is strict about YAML indentation. Rules:

  • Always use spaces — never tabs
  • Service entries are indented two spaces under their group name
  • Widget entries are indented four spaces under their service entry
  • Run your YAML through a validator like yamllint.com if you can't spot the error

Widget shows "N/A" or no data

  • Verify the service URL in the widget config is reachable from inside the Homepage container
  • Check that API keys or credentials are correct
  • Some widgets require specific API features to be enabled in the target service — check the Homepage widget docs for requirements

Docker widget shows no containers

Confirm the server: name in widgets.yaml matches docker.yaml exactly. Then check the Docker socket is mounted and readable:

docker exec -it homepage ls /var/run/docker.sock

If the socket isn't visible inside the container, the volume mount is missing from docker-compose.yml.

Related