Raspberry Pi: creare una Web Dashboard personalizzata

I servizi eseguibili all'interno di una distribuzione Linux sono davvero innumerevoli. Può quindi diventare complesso gestirli tutti, anche perché ogni software ha la sua interfaccia web, il suo servizio di notifica ed il suo URL dedicato. Ecco perché nell'articolo di oggi vogliamo parlarvi di Homepage, una application dashboard personalizzabile con cui interfacciarsi con decine di servizi ed applicativi differenti.

Tale software è eseguibile all'interno di Raspberry Pi, permette quindi di realizzare la propria dashboard accessibile tramite una pratica web interface. Homepage è stato pensato per offrire sempre le massime prestazioni e integrarsi con le più popolari self-hosted application. Inoltre include funzionalità come la ricerca rapida integrata o il supporto alle API di terze parti per espandere le feature di base.

I coder del progetto hanno sviluppato Homepage in modo che sia totalmente sicuro, infatti le richieste dei servizi vengono canalizzate all'interno di un proxy in modo da tenere le API key nascoste. Homepage supporta inoltre ben quaranta lingue e può monitorare i container Docker.

Configurazione hardware

Trattandosi di un programma molto leggero è possibile optare per una Raspberry Pi 4. Tuttavia, se dovete acquistare la board vi consigliamo di scegliere l'incarnazione più recente: Raspberry Pi 5. Senza dimenticarci che per il setup iniziale dovremo dotarci anche di alimentatore, mouse, tastiera e monitor oltre che di un cavo di rete cat 6 e di una microSD/SSD in cui installare Raspberry Pi OS.

Installazione di Raspberry Pi OS

Ora che abbiamo sottomano tutto l'hardware necessario siamo pronti per installare Raspberry Pi OS. Procediamo con il flash della distribuzione su di una microSD sfruttando un imaging tool. Per questa guida abbiamo scelto di affidarci a Raspberry Pi Imager, un pratico software ideato dal team di Raspberry Pi.

Avviamo Raspberry Pi Imager e premiamo su "Choose OS" per scegliere il file ISO di Raspberry Pi OS. Ora, da "Choose Storage", selezioniamo la microSD da utilizzare e poi "Write" per avviare il flash. L'intera procedura dovrebbe durare qualche minuto, tempo che possiamo impiegare per predisporre tutte le periferiche necessarie al primo wizard del sistema operativo.

Terminato il flash inseriamo la microSD nel device e connettiamo il tutto all'alimentazione cosi da eseguire il primo boot. Seguiamo quindi la procedura guidata di Raspberry Pi OS. Dopo aver ottenuto l'accesso al Desktop avremo terminato la prima parte dell'operazione.

Installazione di Docker su Raspberry Pi OS

Arrivati a questo punto siamo pronti per installare Docker. Homepage è infatti disponibile tramite tale sistema di container. Quindi apriamo la shell e prima di tutto assicuriamoci di aver accesso agli ultimi aggiornamenti della distribuzione. Indichiamo ad APT di cercare ed installare, se disponibili, gli ultimi upgrade dei programmi:

sudo apt update && sudo apt upgrade

Adesso scarichiamo l'eseguibile di Docker con curl:

curl -sSL https://get.docker.com | sh

ed avviamo l'installazione:

sudo sh get-docker.sh

Per poter usare più agilmente Docker consigliamo di aggiungere il vostro utente al suo gruppo:

sudo usermod -aG docker nomedelnostroutente

oltre ovviamente ad indicare a systemd, il gestore dei demoni di sistema, di eseguire Docker ad ogni avvio:

sudo systemctl enable docker.service && sudo systemctl enable containerd.service

Quindi creiamo la directory dedicata a Homepage:

sudo mkdir -p /opt/stacks/homepage

e spostiamoci dentro di essa:

cd /opt/stacks/homepage

Creare il docker compose file per Homepage

Siamo pronti per scrivere il Docker compose file per Homepage. Per questa operazione usiamo il classico editor di testo nano:

sudo nano compose.yaml

e nel file appena aperto scriviamo:

version: "3.3"
services:
homepage:
image: ghcr.io/gethomepage/homepage:latest
container_name: homepage
ports:
- 3000:3000
volumes:
- ./config:/app/config
- /var/run/docker.sock:/var/run/docker.sock:ro
restart: unless-stopped

Salviamo le modifiche premendo CTRL+O ed infine chiudiamo il tutto con CTRL+X. Ora possiamo finalmente avviare il container con questo comando:

docker compose up -d

Configurare la dashboard di Homepage

La dashboard di Homepage è completamente configurabile tramite dei pratici file di testo. Spostiamoci nella loro directory:

cd /opt/stacks/homepage/config

e andiamoli a listare:

ls -l /opt/stacks/homepage/config

Ad esempio: per aggiungere nuovi segnalibri si può modificare il file bookmarks.yaml mentre per quanto riguarda lo stile esiste il file chiamato custom.css. Inoltre per le configurazioni più particolari si può eseguire uno script JavaScript tramite custom.js.

Per aggiungere un segnalibro possiamo procedere con nano:

sudo nano ./config/bookmarks.yaml

ed aggiungere l'URL che preferiamo:

- Siti Web:
- HTML.it:
- abbr: HI
href: https://html.it/

Per proporre un altro esempio concreto, se volessimo connettere un'istanza di Docker su Homepage potremmo inserire all'interno del file docker.yaml questi setting:

lamiaistanzadocker:
host: 192.168.0.112
port: 8080

Homepage può gestire anche Docker con connessioni crittografate da TLS:

lamiaistanzadockerTLS:
host: 192.168.0.112
port: 8080
tls:
keyFile: tls/key.pem
caFile: tls/ca.pem
certFile: tls/cert.pem

Oppure possiamo implementare un docker socket proxy cosi da assicurare il massimo livello di sicurezza. Basta inserire tali setting nel Docker compose file:

dockerconproxy:
image: ghcr.io/urldelvostrodockerconproxy:latest
container_name: dockerconproxy
environment:
- CONTAINERS=1 # Allow access to viewing containers
- SERVICES=1 # Allow access to viewing services (necessary when using Docker Swarm)
- TASKS=1 # Allow access to viewing tasks (necessary when using Docker Swarm)
- POST=0 # Disallow any POST operations (effectively read-only)
ports:
- 192.168.1.12:8080:8080
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro # Mounted as read-only
restart: unless-stopped
homepage:
image: ghcr.io/gethomepage/homepage:latest
container_name: homepage
volumes:
- /path/to/config:/app/config
ports:
- 3000:3000
restart: unless-stopped

Quindi dentro il file docker.yaml di deve scrivere:

ilmiodocker:
host: dockerconproxy
port: 8080

Accedere alla web interface di Homepage

Ultimate tutte le configurazioni possiamo accedere alla dashboard. Apriamo il browser e digitiamo l'URL:

http://192.168.1.12:3000

Per conoscere l'IP locale del nostro Raspberry Pi basta affidarci a questo pratico comando da shell:

hostname -I

Come output dovremmo ricevere qualcosa di simile a video:

192.168.1.12

3000 è invece la porta su cui sta ascoltando Homepage.

Come potete notare il progetto è davvero versatile e molto semplice da utilizzare anche per coloro che sono alle prime armi con le board ARM o con i sistemi operativi Linux in generale.