Blog — Self-hosting #1

Homepage Dashboard

Homepage to mój główny dashboard homelab — szybki, konfigurowany przez pliki YAML, git-friendly. Używam go do linków statycznych i dynamicznych (auto-discovery z Docker labels). Wbudowane pakiety ikon bardzo ułatwiają konfigurację.

Kluczowe cechy

YAML + git — konfiguracja to kilka plików tekstowych. Diff pokazuje zmiany, przeniesienie między maszynami to kopia katalogu.
Auto-discovery — labele homepage.* w docker-compose.yml wystarczą, żeby serwis pojawił się na dashboardzie automatycznie.
Widgety integracji — 100+ serwisów (Portainer, AdGuard, Traefik, Plex, Home Assistant…) z live metrykami z API.
Multi-host — jeden dashboard agreguje kontenery z wielu Docker hostów.
Lekki — obraz ~150 MB, zużycie RAM poniżej 100 MB, zero bazy 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, które nie używają auto-discovery (np. 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 to osobna sekcja 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, można dodać labele homepage.* bezpośrednio do docker-compose.yml serwisu — Homepage wykryje 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

Żeby Homepage mógł odczytywać labele kontenerów, potrzebuje dostępu do Docker API (dokumentacja). Konfiguracja w docker.yaml:

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

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

Każdy wpis to osobny Docker host. Nie wystawiaj portu 2375 bezpośrednio — zamiast tego użyj Docker Socket Proxy (Tecnativa). To lekki kontener HAProxy, który montuje socket wewnętrznie i wystawia przefiltrowane, read-only API:

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 — przez proxy można wyłącznie odczytywać stan 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 kilka źródeł ikon, które można mieszać w jednej konfiguracji:

Dashboard Icons (Homarr Labs) — wbudowana baza ponad 1800 ikon, dostępna bezpośrednio po nazwie pliku. Nie wymaga żadnej 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 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 przez prefix si-. Przykłady: si-github, si-grafana, si-prometheus, si-ubuntu, si-cloudflare.
URL do zewnętrznego obrazka — gdy ikony nie ma nigdzie indziej. Działa z dowolnym publicznym 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 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