What are we building?

A central dashboard with Homepage (v1.13.2) behind Traefik, configured entirely through simple YAML files. By the end you’ll have a tidy start page with tiles for all services, widgets for CPU/RAM/disk, a search box – and the killer feature: Homepage reads the Docker socket and shows live whether a container is running. All statically generated, no database, with a tiny footprint.

Prerequisites

• A server with Traefik running and Docker Compose
• A subdomain pointing at the server – YOUR_DOMAIN below (e.g. start.yourdomain.com)
• A few already-running services to link (more fun, but not required)

Step by step

Step 1: Create the project and config folder

Homepage is driven entirely by YAML files in a config folder. Create the structure:

mkdir -p /opt/homepage/config /opt/homepage/icons && cd /opt/homepage

Step 2: Base settings

config/settings.yaml controls appearance and layout. We define two groups as a row layout with three columns each:

title: My Serverküche
theme: dark
color: slate
headerStyle: boxed
layout:
  Infrastructure:
    style: row
    columns: 3
  Media:
    style: row
    columns: 3

The names under layout: (Infrastructure, Media) must later match the group names in the services file exactly – only then does the layout apply.

Step 3: Link your services

config/services.yaml is the heart – your tiles. Each service gets a name, a URL, a description and an icon (Homepage automatically pulls matching icons from a large catalog when you specify name.png):

- Infrastructure:
    - Nextcloud:
        href: https://cloud.YOUR_DOMAIN
        description: Your own cloud
        icon: nextcloud.png
    - Vaultwarden:
        href: https://vault.YOUR_DOMAIN
        description: Password manager
        icon: vaultwarden.png
- Media:
    - Immich:
        href: https://photos.YOUR_DOMAIN
        description: Photos
        icon: immich.png
    - Jellyfin:
        href: https://media.YOUR_DOMAIN
        description: Media server
        icon: jellyfin.png

This is how you link your already-installed services like Nextcloud, Immich, Jellyfin or Vaultwarden in one central place.

Step 4: Widgets for system load and search

config/widgets.yaml controls the info bar at the top. Resource display, a search box and date/time:

- resources:
    cpu: true
    memory: true
    disk: /
- search:
    provider: duckduckgo
    target: _blank
- datetime:
    text_size: xl
    format:
      dateStyle: full
      timeStyle: short

The resources widget shows the host’s utilization. Homepage reads CPU and RAM straight from within the container (no Docker socket needed); we only wire up the socket in the next step for the container status.

Step 5: Connect Traefik – and the crucial host protection

Now the compose.yaml. Replace YOUR_DOMAIN with your real subdomain:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:v1.13.2
    restart: unless-stopped
    environment:
      HOMEPAGE_ALLOWED_HOSTS: YOUR_DOMAIN
    volumes:
      - ./config:/app/config
      - ./icons:/app/public/icons
    networks: [proxy]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.homepage.rule=Host(`YOUR_DOMAIN`)"
      - "traefik.http.routers.homepage.entrypoints=websecure"
      - "traefik.http.routers.homepage.tls.certresolver=le"
      - "traefik.http.services.homepage.loadbalancer.server.port=3000"

networks:
  proxy:
    external: true

Start the dashboard:

docker compose up -d

Verify from outside that it responds with valid HTTPS:

curl -sI https://YOUR_DOMAIN/ | head -1

HTTP/2 200

In the browser you now see your dashboard with tiles and the info bar:

Step 6: Live container status via the Docker socket

The strongest feature: Homepage can read directly from Docker whether a container is running, and show CPU/RAM per container. For that create config/docker.yaml:

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

Then mount the socket read-only into the container – add under volumes: in compose.yaml:

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

And link a tile to its container (server refers to the name from docker.yaml, container to the real container name):

- Infrastructure:
    - Traefik:
        description: Reverse proxy
        icon: traefik.png
        server: my-docker
        container: traefik-traefik-1

After docker compose up -d the tile shows a green status badge as soon as the container is running:

Step 7: Add bookmarks (optional)

Besides services, Homepage can show plain bookmarks – via config/bookmarks.yaml:

- Development:
    - Serverküche:
        - abbr: SK
          href: https://serverkueche.de

Now you have services, system load, search and bookmarks in one place. Homepage picks up changes to the YAML files automatically – a browser reload is usually enough, no restart needed.

When things go wrong

Maintenance & backups

• Updates are low-risk. Homepage has no persistent state except your config files. Occasionally bump the image tag (ghcr.io/gethomepage/homepage:v1.13.2) to the new version and docker compose up -d; otherwise your normal update process handles it. After larger jumps check the release notes, as config options can change.
• The backup is tiny. Back up only the config folder (and any custom icons) – that’s your entire configuration. It belongs in your Restic backup; the application itself is recreated from the image any time.
• Don’t forget security. A dashboard with Docker insight is a worthwhile target. Run it only behind HTTPS (Traefik handles that) and additionally protect it with authentication before it’s reachable publicly.