Blog — Self-hosting #1

Homepage Dashboard

Homepage to aplikacja do zarządzania dashboardem homelab. Charakteryzuje się szybkim działaniem, konfiguracją przez pliki YAML i obsługą Git. Umożliwia wyświetlanie linków statycznych i dynamicznych (auto-discovery z Docker labels). Wbudowane pakiety ikon ułatwiają konfigurację.

Kluczowe cechy

YAML + git: konfiguracja przechowywana w plikach tekstowych. Różnice widoczne w diffs, przeniesienie między maszynami wymaga kopii katalogu.
Auto-discovery: labele homepage.* w docker-compose.yml powodują automatyczne pojawienie się serwisu na dashboardzie.
Widgety integracji: ponad 100 serwisów (Portainer, AdGuard, Traefik, Plex, Home Assistant) z metrykami na żywo z API.
Multi-host: jeden dashboard agreguje kontenery z wielu hostów Docker.
Lekki: obraz około 150 MB, zużycie RAM poniżej 100 MB, brak wymaganych baz danych.

Moja konfiguracja

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    restart: on-failure:1
    environment:
      HOMEPAGE_ALLOWED_HOSTS: "nas-1.lan:8091,mini-1.lan:8091"
    ports: [8091:3000]
    volumes:
    - ./homepage:/app/config
    - ./images:/app/public/images

settings.yaml — układ i wygląd (dokumentacja)

showStats: false
hideVersion: true
fiveColumns: true
disableCollapse: true
color: gray

backgroundOpacity: 0.5
cardBlur: md
headerStyle: boxed
background: https://i.ibb.co/hMWFX6D/mountain-clouds.gif

useEqualHeights: true
bookmarksStyle: icons

layout:
  Admin:
    style: row
    columns: 7
  NAS 1:
    style: row
    columns: 7
  Server 1:
    style: row
    columns: 7
  Mini 1:
    style: row
    columns: 7
  OHV VPS 1:
    style: row
    columns: 7
  External:
    style: row
    columns: 7
  Tools:
    style: row
    columns: 7

services.yaml — serwisy ręczne (dokumentacja)

Plik services.yaml definiuje serwisy bez obsługi auto-discovery, takie jak usługi spoza Dockera lub z hostów bez docker-socket-proxy:

- Admin:
  - NAS_1:
      name: nas-1.lan
      icon: synology-dsm.svg
      href: "https://nas-1.lan:5001/"
      weight: -10
      target: _self

  - Webmin:
      name: mini-1.lan
      icon: webmin.svg
      href: "https://mini-1.lan:10000"
      target: _self

  - Webmin:
      name: server-1.lan
      icon: webmin.svg
      href: "https://server-1.lan:10000"
      target: _self

- External:
  - search-console:
      name: Search console
      icon: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/google-search-console.svg"
      href: "https://search.google.com/..."
      target: _self

  - ovhcloud:
      name: OVH
      icon: "ovh.svg"
      href: "https://manager.eu.ovhcloud.com/..."
      target: _self

bookmarks.yaml — zakładki (dokumentacja)

Bookmarki stanowią osobną sekcję poniżej serwisów.

- Links:
  - github:
    - name: GitHub
      icon: https://cdn.jsdelivr.net/gh/selfhst/icons/svg/github-light.svg
      href: https://github.com/
      target: _self

  - feedly:
    - name: Feedly
      icon: feedly.png
      href: https://feedly.com/i/collection/...
      target: _self

- Other:
  - home_assistant:
    - name: Home Assistant
      icon: home-assistant.svg
      href: http://ha.lan:8123
      target: _self

  - UniFi:
    - icon: unifi.svg
      href: https://192.168.30.1/network/default/dashboard
      target: _self

custom.css — dopasowanie wyglądu (dokumentacja)

.text-xl {
  font-size: 1rem !important;
  line-height: 1.5rem !important;
}

.services-group {
  padding: 0 .25rem !important;
}

#information-widgets {
  display: none;
}

ul.services-list, ul.bookmark-list {
  margin-top: 0 !important;
}

Konfiguracja przez Docker labele

Zamiast ręcznie duplikować wpisy w services.yaml, należy dodać labele homepage.* bezpośrednio do docker-compose.yml serwisu. Homepage wykrywa kontener automatycznie (dokumentacja):

services:
  adguard:
    image: adguard/adguardhome
    container_name: adguard
    ports: ["53:53/udp", "85:85/tcp"]
    labels:
      homepage.group: Tools
      homepage.name: AdGuard
      homepage.icon: adguard-home.svg
      homepage.href: http://nas-1.lan:85/
      homepage.weight: 100
      homepage.target: _self

Połączenie z Docker hostami

Homepage wymaga dostępu do Docker API w celu odczytywania etykiet kontenerów (dokumentacja). Konfiguracja przechowywana w docker.yaml:

nas_1:
  host: nas-1.lan
  port: 2375

mini_1:
  host: mini-1.lan
  port: 2375

Każdy wpis odpowiada osobnemu hostowi Docker. Port 2375 nie powinien być wystawiany bezpośrednio. Zamiast tego użyj Docker Socket Proxy (Tecnativa). Jest to lekki kontener HAProxy, który montuje socket wewnętrznie i wystawia przefiltrowane API tylko do odczytu:

services:
  agent_docker_proxy:
    image: ghcr.io/tecnativa/docker-socket-proxy:latest
    container_name: agent_docker_proxy
    restart: on-failure:1
    ports: [2375:2375]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      CONTAINERS: "1"
      SERVICES: "0"
      TASKS: "0"
      POST: "0"

POST: 0 blokuje wszystkie żądania modyfikujące. Proxy umożliwia wyłącznie odczytywanie stanu kontenerów. Schemat połączeń:

graph LR
    H[Homepage<br/>nas-1.lan:8091] -->|TCP 2375| P1[docker-socket-proxy<br/>nas-1.lan]
    H -->|TCP 2375| P2[docker-socket-proxy<br/>mini-1.lan]
    H -->|TCP 2375| P3[docker-socket-proxy<br/>server-1.lan]
    P1 -->|socket| D1[Docker Engine<br/>nas-1]
    P2 -->|socket| D2[Docker Engine<br/>mini-1]
    P3 -->|socket| D3[Docker Engine<br/>server-1]

Ikony (dokumentacja)

Homepage obsługuje wiele źródeł ikon, które można łączyć w jednej konfiguracji:

Dashboard Icons (Homarr Labs): wbudowana baza ponad 1800 ikon dostępnych po nazwie pliku bez dodatkowej konfiguracji. Przykłady: traefik.png, portainer.svg, synology-dsm.svg, plex.png, home-assistant.svg, adguard-home.svg, freshrss.png, jellyfin.svg, nextcloud.svg, vaultwarden.svg. Galeria: dashboardicons.com.
Material Design Icons: tysiące ikon ogólnego przeznaczenia dostępnych przez prefix mdi-. Przydatne gdy aplikacja nie ma dedykowanej ikony. Przykłady: mdi-server, mdi-nas, mdi-router-network, mdi-database, mdi-shield-lock.
Simple Icons: ikony brandów i popularnych projektów open-source dostępne przez prefix si-. Przykłady: si-github, si-grafana, si-prometheus, si-ubuntu, si-cloudflare.
URL do zewnętrznego obrazka: dostępny gdy ikona nie istnieje w innych źródłach. Obsługuje dowolny publiczny URL, np. https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/google-search-console.svg.
Własny plik: obrazki zamontowane jako ./images:/app/public/images dostępne po nazwie pliku: my-app.png. Po dodaniu nowego pliku wymagany jest restart kontenera. Homepage nie wykrywa zmian w tym katalogu automatycznie.

W większości przypadków wystarczy wpisać nazwę pliku SVG lub PNG — Homepage znajdzie ikonę automatycznie.

Menu