Heb je meer dan een handvol webapplicaties op een Linux-server draaien? Dan is een dashboard met links naar deze applicaties een uitkomst. Het project Homepage biedt precies dat, inclusief widgets die allerlei statistieken van je services weergeven. In dit artikel installeren we Homepage en laten we je zien hoe je het integreert met je bestaande services.
Dit gaan we doen
In deze masterclass richten we een persoonlijk dashboard in met Homepage. Je leert hoe je de tool installeert in Docker, services groepeert en uitbreidt met widgets voor statistieken zoals cpu- en geheugengebruik, uptime of weersinformatie. We laten zien hoe je containers automatisch herkent, monitoring toevoegt en ook bladwijzers of alternatieve dashboards gebruikt. Zo krijg je één centrale plek waar je al je webapplicaties en services snel terugvindt en beheert.
Lees ook: Windows gebruiken naast of binnen Linux? Zo krijg je het soepel aan de praat met Docker
⬇️ Code downloaden
In dit artikel staat voorbeelden met YAML-code. Omdat YAML erg gevoelig is voor foute spaties en inspringingen, kun je die code beter downloaden en daarna bekijken of kopiëren. Zie het bestand homecode.txt, beschikbaar via deze link.
Homepage helpt je om diverse webapplicaties in één dashboard te organiseren. Dit is handig als je services in Docker-containers draait of eenvoudig toegang wilt tot de beheerpagina’s van apparaten zoals je modem, router en NAS.
Hoewel dit klinkt als een veredelde bookmark-manager, doet Homepage meer dan alleen links op een pagina verzamelen. Het project ondersteunt widgets voor meer dan honderd services en kan zo bijvoorbeeld het cpu- en geheugenverbruik van je hypervisor of het aantal ongelezen artikels in je RSS-lezer tonen. Je hoeft daardoor vaak zelfs niet op de links te klikken om even snel de status van je services te bekijken.
Docker Compose
We gaan ervan uit dat je een Linux-server hebt waarop je services met behulp van Docker Compose in Docker-containers draait. Homepage draai je dan gewoon in een Docker-container naast je bestaande services, al zijn er ook andere installatie-opties. In ons voorbeeld draaien we Docker op Debian 12. Maak om te beginnen een map waarin de container van Homepage zijn data en configuratie kan opslaan, met deze opdracht:
$ mkdir -p containers/homepage
Zet vervolgens in je bestand docker-compose.yml (het bestand waarin je al je containers definieert) een service voor Homepage:
services:
homepage:
image: ghcr.io/gethomepage/homepage:latest
container_name: homepage
ports:
- 3000:3000
volumes:
- /home/koan/containers/homepage:/app/config
environment:
HOMEPAGE_ALLOWED_HOSTS: debian.home:3000
restart: unless-stopped
Homepage kun je op diverse manieren installeren.
Homepage opstarten
Wijzig in het gedefinieerde volume de directory vóór de dubbele punt naar het volledige pad van de directory die je voor de container hebt aangemaakt. Stel de waarde van de omgevingsvariabele HOMEPAGE_ALLOWED_HOSTS gelijk aan het domein of het ip-adres van de host, gescheiden door een dubbele punt van het poortnummer. Als je met een reverse proxy werkt, zet je hier het domein waarop de applicatie via die proxy bereikbaar is.
Start de container met:
$ docker-compose up -d
Zodra het image gedownload is en de container draait, open je Homepage in je browser op de url die je in HOMEPAGE_ALLOWED_HOSTS hebt gedefinieerd. Je ziet dan een voorbeeldpagina met van boven naar onder een header, groepen met services en groepen met bladwijzers.
Het standaarddashboard van Homepage vlak na de installatie.
Informatiewidgets
In de header vind je enkele informatiewidgets. Hoewel deze niet de kern van de functionaliteit van Homepage uitmaken, bieden ze nuttige aanvullende informatie. Standaard zie je het cpu-verbruik, het beschikbare geheugen en de vrije schijfruimte van de host. Er is ook een tekstveld om te zoeken via DuckDuckGo. De definitie van deze twee widgets vind je in het bestand widgets.yaml in de directory van de Homepage-container.
In de online documentatie van de informatiewidgets lees je hoe je hun gedrag aanpast. Zo kunnen we de widget Resources ook de uptime van het systeem laten tonen (uptime: true) en met de optie expanded: true meer informatie over de cpu, het geheugen en de schijfruimte laten weergeven. De widget ziet er dan als volgt uit in widgets.yaml:
- resources:
label: System
expanded: true
cpu: true
memory: true
uptime: true
disk: /
Weersomstandigheden
Homepage biedt twee widgets om het weer in de header te tonen: één via Open-Meteo en één via OpenWeatherMap. De eerste vereist geen registratie, dus daarvoor hoef je alleen maar de gps-coördinaten van je locatie in te voeren. In widgets.yaml ziet dat er als volgt uit:
- openmeteo:
label: Attenrode
latitude: 50.8773405
longitude: 4.9213237
timezone: Europe/Brussels
units: metric
cache: 5
format:
maximumFractionDigits: 1
Met cache: 5 laten we de widget de weergegevens vijf minuten lang cachen om de servers van Open-Meteo te ontlasten. Verder biedt Homepage nog andere informatiewidgets aan, bijvoorbeeld voor beurskoersen of de datum en tijd.
In de header van Homepage plaats je allerlei informatiewidgets.
Services toevoegen
De kernfunctionaliteit van Homepage ligt uiteraard in het groeperen van services in één dashboard. De standaardconfiguratie voegt drie groepen toe met elk één service. De YAML-code hiervoor vind je in het bestand services.yaml. Vervang die door je eigen groepen. Je kunt bijvoorbeeld een groep Network aanmaken met links naar de beheerinterfaces van je modem/router en accesspoints:
- Network:
- Proximus:
href: http://192.168.1.1
description: Modem
icon: mdi-web
- OpenWrt:
href: http://gl-mt3000.home
description: Accesspoint
icon: openwrt
De eigenschap icon kan een absolute url zijn of een naam uit de lijst op de website Dashboard Icons. Begin de naam van een pictogram met mdi- voor een keuze uit Material Design Icons , met si- voor een keuze uit Simple, of met sh- voor een keuze uit Self-Hosted Dashboard Icons.
Ook groepen kunnen een pictogram krijgen. Dat definieer je dan in het bestand settings.yaml:
layout:
Network:
icon: mdi-lan-connect
Infrastructure:
icon: mdi-server-network
Services:
icon: mdi-apps
Services en groepen kun je pictogrammen geven, bijvoorbeeld van de website Self-Hosted Dashboard Icons.
Servicewidgets
Tot nu toe lijkt ons dashboard wat op een veredeld lijstje met bladwijzers. Maar Homepage ondersteunt ook servicewidgets voor meer dan honderd services. Controleer in de lijst of je services ondersteund zijn. Draai je bijvoorbeeld OPNsense op je router, dan krijg je met de volgende widget de processorbelasting, het gebruikte geheugen, en de upload- en downloadhoeveelheden van je WAN-interface te zien:
- OPNsense:
href: https://opnsense.home
description: Router
icon: opnsense
widget:
type: opnsense
url: https://opnsense.home
username: KEY
password: SECRET
Voor username en password vul je de API-sleutel en het ‘secret’ in die je in de webinterface van OPNsense aanmaakt via System / Access / Users. De documentatie van Homepage voor de OPNsense-widget legt dit gedetailleerd uit. Wil je slechts een deel van de statistieken zien, dan kan dat door de widget uit te breiden met een regel als:
fields: ["wanDownload", "wanUpload"]
Homepage ondersteunt widgets voor meer dan honderd services.
Meerdere widgets
Je kunt een service ook van meerdere widgets voorzien. Dat is bijvoorbeeld handig bij monitoringtools zoals Uptime Kuma. Voeg aan de OPNsense-service dan de OPNsense-widget toe voor servicespecifieke statistieken en de widget van Uptime Kuma voor beschikbaarheidsstatistieken. In plaats van één object widget bevat de service dan een object widgets met een lijst die beide widgets bevat:
- OPNsense:
href: https://opnsense.home
description: Router
icon: opnsense
widgets:
- type: opnsense
url: https://opnsense.home
username: KEY
password: SECRET
- type: uptimekuma
url: https://uptime-kuma.rubus.home
slug: router
fields: ["uptime", "incident"]
De widget van Uptime Kuma gebruikt data van een statuspagina. Die moet je dus eerst in Uptime Kuma aanmaken, en de naam van de statuspagina vul je bij slug in de widget in. Als de statuspagina bijvoorbeeld toegankelijk is via https://uptime-kuma.rubus.home/status/router, dan is de slug router.
Homepage kan een statuspagina van Uptime Kuma in een service integreren.
Beschikbaarheid monitoren
Ook zonder speciale monitoringtools kun je met Homepage eenvoudig te zien krijgen of al je services momenteel online zijn. Dat kan met de eigenschap ping of siteMonitor in de service. Voeg bijvoorbeeld aan de service voor OPNsense ping: opnsense.home toe. Homepage stuurt dan regelmatig een ICMP-echopakket (ping) naar de host en toont de beschikbaarheid in de rechterbovenhoek van het kader van de service.
Met siteMonitor: https://opnsense.home daarentegen voert Homepage een HTTP HEAD-verzoek uit naar de url om te controleren of de webpagina beschikbaar is. Zo weet je niet alleen dat de host online is, maar ook dat de webserver tenminste draait en de pagina aanbiedt. Let op dat je hier de volledige url met https:// of http:// dient te gebruiken. De stijl van de getoonde status kun je overigens in settings.yaml aanpassen met bijvoorbeeld statusStyle: dot of statusStyle: basic.
Enkele services met pictogrammen, widgets en statusinformatie.
Docker-containers integreren
Als je services in Docker-containers draait, kan Homepage via de API van de Docker-engine statistieken over die containers opvragen en zelfs automatisch services herkennen. Configureer hiervoor een Docker-instance voor Homepage in docker.yaml. Als je Homepage met de Docker-socket laat verbinden, kan dat met de volgende configuratie:
local-docker:
socket: /var/run/docker.sock
In je Docker Compose-bestand moet je deze socket als volume in de Homepage-container aankoppelen:
volumes:
- /home/koan/containers/homepage:/app/config
- /var/run/docker.sock:/var/run/docker.sock
Docker Socket Proxy
Een veiliger alternatief om Homepage toegang tot Docker te geven, is via Docker Socket Proxy. Je laat die laatste dan rechtstreeks met de Docker-socket verbinden en de andere containers via een HTTP API beperkte bevoegdheden geven. Voeg daarvoor in je Docker Compose-bestand de volgende service voor Docker Socket Proxy toe:
docker-socket-proxy:
image: ghcr.io/tecnativa/docker-socket-proxy:0.3.0
container_name: docker-socket-proxy
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
CONTAINERS: 1
restart: unless-stopped
Standaard geeft Docker Socket Proxy sterk ingeperkte API-toegang tot de Docker-engine, en sowieso alleen-lezen. Met de omgevingsvariabele CONTAINERS: 1 geven we toegang tot informatie over containers, precies wat Homepage nodig heeft.
Wijzig nu in het bestand docker.yaml de definitie van local-docker naar:
local-docker:
host: docker-socket-proxy
port: 2375
Omdat de container van Docker Socket Proxy zich in hetzelfde netwerk als Homepage bevindt, is die onder de naam docker-socket-proxy bereikbaar, wat we hier als host invullen.
Maak dan de containers opnieuw aan met de opdrachten:
docker-compose down
docker-compose up -d
Containers monitoren
Containers die in hetzelfde Docker Compose-bestand als Homepage zijn gedefinieerd, kun je nu door die laatste laten monitoren. Je moet dan bij de service in services.yaml de Docker-server en de naam van de container opgeven, bijvoorbeeld:
- Services:
- FreshRSS:
href: http://debian.home:8081
description: Feed aggregator
icon: freshrss
server: local-docker
container: freshrss
De waarde van server is hier de naam van de Docker-instance in docker.yaml, namelijk local-docker. De waarde van container is hier de naam van de container, gedefinieerd in container_name in het Docker Compose-bestand.
Na het herladen van de webpagina van Homepage krijgt de FreshRSS-service de status RUNNING in de rechterbovenhoek of EXITED wanneer de container gestopt is. Klik op de status voor gedetailleerdere statistieken zoals de processorbelasting, het geheugengebruik en netwerkverkeer.
Services automatisch detecteren
Elke keer dat je nu een service toevoegt, moet je de container aan je Docker Compose-bestand toevoegen en een definitie van de service aan het bestand services.yaml van Homepage. Maar Homepage ondersteunt ook het automatisch detecteren van services voor containers met behulp van labels. Met deze aanpak hoef je services.yaml niet meer bij te werken en hoef je slechts één bestand te veranderen. Voor FreshRSS kan dat bijvoorbeeld als volgt:
freshrss:
image: docker.io/freshrss/freshrss:1.26.1-alpine
container_name: freshrss
ports:
- 8081:80
volumes:
- /home/koan/containers/freshrss/data:/var/www/FreshRSS/data
- /home/koan/containers/freshrss/extensions:/var/www/FreshRSS/extensions
environment:
CRON_MIN: "1,31"
TZ: Europe/Brussels
restart: unless-stopped
labels:
- homepage.group=Services
- homepage.name=FreshRSS
- homepage.href=http://debian.home:8081
- homepage.description=Feed aggregator
- homepage.icon=freshrss
In de labels van deze container geef je dus aan dat je in de groep Services een service met de naam FreshRSS toevoegen, met de gegeven link, beschrijving en pictogram. De opties server en container uit de vorige paragraaf zijn met deze aanpak overbodig, omdat Homepage deze automatisch via de API van de geconfigureerde Docker-instance verkrijgt. Na opnieuw het uitvoeren de volgende twee commando’s ontdekt Homepage automatisch de service en voegt deze aan de juiste groep toe:
docker-compose down
docker-compose up -d
Widgets
Op dezelfde manier kun je widgets toevoegen via labels. In het voorbeeld uit de vorige stap voeg je dan de volgende labels toe:
- homepage.widget.type=freshrss
- homepage.widget.url=http://freshrss
- homepage.widget.username=USER
- homepage.widget.password=PASSWORD
Wil je meerdere widgets aan een container toevoegen, geef dan elk widget een index:
- homepage.widgets[0].type=freshrss
- homepage.widgets[0].url=http://freshrss
- homepage.widgets[0].username=USER
- homepage.widgets[0].password=PASSWORD
- homepage.widgets[1].type=uptimekuma
- homepage.widgets[1].url=https://uptime-kuma.rubus.home
- homepage.widgets[1].slug=freshrss
Wanneer je nu de container van FreshRSS opnieuw aanmaakt en opstart, detecteert Homepage de widgets en toont ze bij de service.
Alternatieven voor Homepage
Hoewel Homepage een krachtige tool is, zijn er talrijke alternatieven om een dashboard voor al je services te maken, elk met hun eigen benadering. Houd je niet van YAML-configuraties, dan biedt Homarr een gebruiksvriendelijk alternatief om met slepen en neerzetten allerlei services toe te voegen.
Ook populair is Heimdall. Het is minder naar eigen smaak aan te passen dan Homepage of Homarr, maar daardoor eenvoudig om mee aan de slag te gaan.
Bevalt de aanpak met YAML-bestanden je wel, maar ligt Homepage je niet helemaal, kijk dan eens naar Dashy.
Bookmarks
Tot slot kan Homepage ook gewone bladwijzers aan je dashboard toevoegen. Je kunt ze net op dezelfde manier als services groeperen, maar het zijn slechts links zonder extra functionaliteiten zoals widgets en monitoring. Bladwijzers definieer je in het bestand bookmarks.yaml van Homepage, dat er standaard als volgt uitziet:
- Developer:
- GitHub:
- abbr: GH
href: https://github.com
- Social:
- Reddit:
- abbr: RE
href: https://reddit.com
- Entertainment:
- YouTube:
- abbr: YT
href: https://youtube.com
Vervang deze groepen met bladwijzers door jouw eigen keuzes. Dit is bijvoorbeeld handig om alle links naar portaalsites of accounts bij belangrijke diensten op één pagina te verzamelen. Homepage toont dan per groep een lijst met bladwijzers met hun afkorting (de waarde van abbr), naam en het domein van de link.
Wil je in plaats van een afkorting een pictogram bij een bladwijzer tonen, gebruik dan icon in plaats van abbr en geef daar net zoals bij services de naam van een pictogram op. En vul description bij een bladwijzer in om een beschrijving in de plaats van het domein te zien. Ook de groepen van bladwijzers kun je een pictogram geven. Net zoals voor de groepen van services definieer je die pictogrammen in settings.yaml.
Een volledig dashboard van Homepage met header, services en bladwijzers.
En verder
Homepage biedt nog veel meer mogelijkheden dan we hier kunnen behandelen. Vooral in het bestand settings.yaml zijn er nog allerlei aanpassingen mogelijk. Zo kun je een achtergrondafbeelding instellen en daarop allerlei filters toepassen. Ook het thema en het kleurenpalet, die je beide via pictogrammen onderaan de pagina kunt aanpassen, zijn vast in te stellen.
Ook de lay-out van het dashboard is configureerbaar. Zo neemt standaard elke groep een kolom in, waarbij de services onder elkaar komen te staan. Maar met style: row bij een groep laat je de services in die groep naast elkaar in een rij weergeven. Ook het aantal kolommen, de stijl van de header en nog meer zijn in te stellen.
Homepage is tot in de kleinste details aan te passen.
Speciaal voor de jongste Linux-fans
(dit vinden ze zeker leuk!)
