Files
Febe/docs/docker.md
T
Alby96andClaude Opus 5.5 6e95aef5cc Documenti: processo, CI ed etichette dell'immagine
docs/processo.md descrive il percorso di una modifica come in un'azienda: rami,
commit, richieste di unione, controlli richiesti e protezione di main da
configurare su Gitea, che cosa garantisce ciascun lavoro della CI, etichette del
registro (:main, :sha-, :X.Y.Z, :latest), pulizia, rilievi di sicurezza,
rilasci e correzioni urgenti, e che cosa solo la prima esecuzione vera può
provare. CLAUDE.md e la guida per lo sviluppo dicevano che la verifica girava a
ogni push, e non era vero: ora descrivono la CI com'è. docs/docker.md dice quali
etichette ha l'immagine e come risalire all'esecuzione che l'ha costruita.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 10:57:22 +02:00

16 KiB
Raw Blame History

Febe in Docker (e su Unraid)

La veste Docker di Febe (specifica §11): un solo contenitore con l'interfaccia web, il motore, un Chromium vero su un display virtuale (Xvfb) e la libreria su disco. Si usa dal browser di casa; il browser di Febe si vede e si usa dalla vista remota della pagina Impostazioni ▸ Collegamento.

Prima di tutto. Scaricare con un programma è contro le condizioni d'uso di Instagram. Febe va piano per ridurre il rischio per l'account (ritmo umano, tetti, fermo al primo segnale), ma non può azzerarlo.

Che cosa c'è nell'immagine

  • Debian stabile ridotta (debian:trixie-slim). Su Ubuntu il pacchetto Chromium è uno snap e nei contenitori non funziona.
  • Febe pubblicato autosufficiente per linux-x64: nell'immagine non c'è il runtime .NET.
  • chromium e chromium-l10n, xvfb, ffmpeg (miniature dei video importati), ICU, caratteri di sistema con le emoji (fonts-noto-color-emoji, fonts-liberation, fonts-dejavu-core), certificati, tzdata, la lingua it_IT.UTF-8 generata.
  • tini come processo 1 (inoltra lo stop a Febe e raccoglie i processi di Chromium rimasti orfani) e setpriv per scendere all'utente PUID/PGID. Nessuno script fa da supervisore: è Febe ad avviare e riavviare Xvfb e Chromium.
  • Un file di criteri di Chromium (/etc/chromium/policies/managed/febe.json) che spegne il salvataggio delle password e la compilazione automatica: con l'archivio di base finirebbero in chiaro nel profilo. Nel profilo resta solo la sessione.
  • L'immagine si costruisce solo con le prove verdi: la compilazione e tutte le prove girano dentro la costruzione (quelle con il browser vero lì si saltano da sole, perché nello stadio di compilazione non ci sono Chromium e Xvfb; girano nella CI e in sviluppo).
  • I pacchetti di Debian sono aggiornati al momento della costruzione (anche le correzioni uscite dopo l'immagine di base). Prima di ogni pubblicazione la CI fa partire il contenitore senza rete fino al controllo di salute e lo scansiona con Trivy: una vulnerabilità CRITICAL con correzione disponibile ferma la pubblicazione (docs/processo.md, «Rilievi di sicurezza»).

Etichette dell'immagine

Sul registro di Gitea, 192.168.30.23:3000/alby96/febe:

Etichetta Che cos'è Quando cambia
:latest l'ultima versione rilasciata senza trattino: quella del modello di Unraid e di compose.yml a ogni rilascio stabile
:X.Y.Z una versione rilasciata (anche X.Y.Z-rc.N per un'anteprima) mai: serve per tornare a una versione precisa
:main l'ultimo commit di main che ha passato la verifica a ogni unione in main: per provare, non per l'archivio vero
:sha-<7 caratteri> un commit di main preciso mai

Ogni immagine costruita dalla CI dice da dove viene, nelle etichette Docker febe.ci.workflow, febe.ci.run, febe.ci.ref e febe.ci.commit e in org.opencontainers.image.version e .revision: docker inspect --format '{{json .Config.Labels}}' <immagine>.

Volumi

Volume Uso Dove metterlo
/dati Database (febe.sqlite), profilo del browser con la sessione di Instagram (browser/), miniature, copie giornaliere del database (copie/, sette giorni), registro (registro/, quattordici giorni), file temporanei Su un disco locale del server. Su Unraid: /mnt/user/appdata/febe (la cartella delle applicazioni sul disco di cache). Mai una condivisione di rete: SQLite e il profilo del browser lì si rovinano, e Febe si rifiuta di partire
/libreria Foto e video, una cartella per account, con _febe.jsonl Dove vuoi, anche su una condivisione. Febe non cancella e non sostituisce mai un file da solo
/importa Cartelle da importare (pagina Importa) Sempre in sola lettura (:ro): Febe copia, gli originali non si toccano

Variabili

Variabile Significato Predefinito
FEBE_PASSWORD Password dell'interfaccia. Obbligatoria: senza, il motore e il browser non partono e l'interfaccia mostra solo la pagina che spiega il problema nessuno
FEBE_PORTA Porta dell'interfaccia dentro il contenitore 8480
TZ Fuso orario: fascia del motore, date nei nomi dei file, fuso dichiarato dal browser Europe/Rome
LANG Lingua del contenitore e quindi del browser it_IT.UTF-8
PUID, PGID Utente e gruppo con cui gira Febe e di cui sono i file 99, 100 (Unraid)
FEBE_HOST Facoltativa: i nomi con cui raggiungi l'interfaccia, separati da virgole (tower.local,192.168.1.10). Se c'è, ogni altro nome è rifiutato (oltre a 127.0.0.1 per il controllo di salute) qualunque nome
FEBE_PROXY_FIDATO 1 se davanti c'è un proxy con HTTPS che passa X-Forwarded-Host e X-Forwarded-Proto: il controllo dell'origine usa quel nome, e quando il proxy dice https il cookie di sessione è Secure (il browser non lo manda mai in chiaro) spenta
FEBE_SENZA_SANDBOX 1 avvia Chromium con --no-sandbox: è il compromesso descritto sotto, da usare solo se il profilo seccomp non si può usare spenta
FEBE_CHROMIUM, FEBE_PORTA_DEBUG, FEBE_DISPLAY Avanzate: eseguibile di Chromium, porta di debug (sempre su 127.0.0.1), display di Xvfb /usr/bin/chromium, 9222, :99

La password dell'interfaccia non si passa mai sulla riga di comando e non finisce nei registri.

Porte

Si pubblica solo la porta dell'interfaccia (8480). La porta di debug del browser (9222) ascolta solo su 127.0.0.1 dentro il contenitore: non va mai pubblicata, e Febe si rifiuta di usare il browser se la trova aperta altrove.

Utente: PUID e PGID

L'avvio crea, se mancano, il gruppo PGID e l'utente PUID, assegna /dati a quell'utente (la prima volta, o quando cambi PUID/PGID: allora anche il contenuto) e passa a quell'utente con setpriv. /libreria non viene mai cambiata ricorsivamente: se Febe non riesce a scriverci, il registro lo dice. Febe non gira come root: con PUID=0 il contenitore si ferma con un messaggio.

Sandbox di Chromium (S5)

Esito della prova del 13 ottobre 2026 (dettagli in docker/chromium/LEGGIMI.md):

  • come utente normale, fuori da Docker, la sandbox di Chromium parte da sola (spazi dei nomi utente);
  • dentro Docker, con il profilo seccomp predefinito, Chromium non parte affatto: No usable sandbox!. Il profilo di Docker vieta la creazione di spazi dei nomi utente a chi non ha CAP_SYS_ADMIN;
  • con il profilo seccomp dedicato di Febe (docker/chromium/seccomp.json: quello di Docker più clone e unshare) la sandbox è completa (chrome://sandbox: «You are adequately sandboxed») e il resto del filtro di Docker resta attivo. È l'impostazione consigliata, già scritta in compose.yml e nel modello di Unraid.

Docker legge il profilo sul server, quando crea il contenitore. Per questo il file sta fuori dal volume /dati: /dati è dell'utente del contenitore, e un file lì dentro potrebbe essere cambiato da chi riuscisse a far eseguire qualcosa a quell'utente (per esempio attraverso un difetto del browser), che allenterebbe così il proprio filtro alla ricreazione successiva. L'immagine contiene il profilo in /usr/share/febe/seccomp.json, solo da leggere; lo si estrae una volta (vedi Unraid, sotto) o si usa quello di docker/chromium/ accanto a compose.yml. Il contenitore non lo tocca: si ripete l'estrazione solo quando le note di una versione lo chiedono.

Le prime anteprime copiavano il profilo in /dati/seccomp.json a ogni avvio: se «Extra Parameters» indica ancora quel file, estrai il profilo nel posto nuovo e correggi il percorso (il registro del contenitore lo ricorda a ogni avvio).

Se il profilo dedicato non si può usare, le alternative sono due, in quest'ordine:

  1. --security-opt seccomp=unconfined: la sandbox di Chromium resta attiva, ma il contenitore perde tutto il filtro seccomp di Docker.
  2. FEBE_SENZA_SANDBOX=1: Chromium parte con --no-sandbox. È un compromesso: una pagina che sfruttasse un difetto del browser non troverebbe la sandbox di Chromium a fermarla, solo i limiti del contenitore. Si accetta soltanto perché quel browser visita esclusivamente Instagram, e solo se le due strade sopra non sono possibili. Chromium mostra anche una barra d'avviso in alto, che toglie circa 50 pixel alla pagina.

Febe non sceglie da solo: se Chromium non parte, il registro dice perché e rimanda a questa sezione.

Sicurezza: da leggere prima di installare

  • Mai esporre l'interfaccia su Internet senza una VPN (per esempio WireGuard o Tailscale) o un proxy con HTTPS davanti. Dalla vista remota passa la password di Instagram: in Docker tasti, password e codici di Alberto attraversano la rete di casa e la memoria del server per arrivare al browser di Febe. Non vengono registrati né conservati, ma su HTTP in chiaro sono leggibili da chi sta sulla stessa rete.
  • Chi ha /dati, o una sua copia, ha la sessione di Instagram. Vale anche per le copie di sicurezza della cartella delle applicazioni (per esempio il plugin di backup di Unraid): trattale come una password.
  • Contenitore e Febe per Windows non vanno usati insieme sullo stesso account. Un account, un motore: due Febe che raccolgono con lo stesso account sommano le visite e raddoppiano il rischio.
  • La sessione nasce e resta nel browser del contenitore: i cookie non si copiano da un'altra macchina.
  • L'interfaccia è protetta da password (cookie di sessione HttpOnly, SameSite=Strict, Secure quando arrivi in HTTPS, anche attraverso il proxy fidato; blocco dopo tentativi ripetuti); ogni comando e l'apertura della vista remota controllano che la richiesta arrivi dall'interfaccia stessa. Dopo la password, la pagina di accesso torna solo a una pagina di Febe, mai a un altro sito.

Installazione su Unraid

  1. L'immagine è 192.168.30.23:3000/alby96/febe:latest, sul registro dei container del Gitea di casa (lo stesso su cui la pubblica il rilascio). Il registro risponde in HTTP: il Docker di Unraid deve averlo fra gli insecure-registries, come per le altre immagini di casa (Encelado, Mimante). Se Unraid scarica già quelle, è a posto; altrimenti aggiungi "insecure-registries": ["192.168.30.23:3000"] alla configurazione del demone Docker e riavvia Docker. Se il pacchetto non è pubblico, accedi dal terminale: docker login 192.168.30.23:3000.

  2. Dal terminale di Unraid, una volta sola, estrai il profilo seccomp dall'immagine e mettilo dove il modello lo cerca, fuori dalla cartella dei dati:

    docker run --rm --entrypoint cat 192.168.30.23:3000/alby96/febe:latest \
      /usr/share/febe/seccomp.json > /mnt/user/appdata/febe-seccomp.json
    
  3. Docker ▸ Aggiungi contenitore ▸ modello da docker/unraid/febe.xml (o dal suo indirizzo, http://192.168.30.23:3000/Alby96/Febe/raw/branch/main/docker/unraid/febe.xml). Controlla:

    • porta 8480;
    • /dati su /mnt/user/appdata/febe (disco di cache);
    • /libreria dove vuoi le foto; /importa in sola lettura;
    • password dell'interfaccia (obbligatoria, nascosta);
    • TZ, PUID 99, PGID 100 tra le impostazioni avanzate;
    • in «Extra Parameters»: --restart=unless-stopped --stop-timeout 30 --security-opt seccomp=/mnt/user/appdata/febe-seccomp.json.
  4. Apri http://<IP di Unraid>:8480/, entra con la password, vai in Impostazioni ▸ Collegamento ▸ «Accedi a Instagram»: la vista remota mostra la vera pagina di accesso; scrivi tu nome utente, password ed eventuale codice, poi «Ho finito». Febe comincia qualche minuto dopo, con l'avvio graduale.

  5. Il collegamento sopravvive ai riavvii: la sessione resta nel profilo del browser in /dati/browser.

Docker Compose

docker/compose.yml è un esempio pronto: immagine, porta, volumi (con /importa in sola lettura), variabili, profilo seccomp con percorso relativo al file (chromium/seccomp.json, fuori da /dati), restart: unless-stopped, 30 secondi per fermarsi. init: true non serve (c'è già tini) e nemmeno shm_size (Chromium usa /tmp al posto della memoria condivisa). Anche qui il registro 192.168.30.23:3000 deve stare fra gli insecure-registries del Docker.

FEBE_PASSWORD='una frase lunga' docker compose -f docker/compose.yml up -d

Fuori dal repository si usa l'archivio febe-compose-X.Y.Z.tar.gz allegato alla release: contiene compose.yml e, accanto, chromium/seccomp.json.

tar -xzf febe-compose-X.Y.Z.tar.gz && cd febe-compose-X.Y.Z
FEBE_PASSWORD='una frase lunga' docker compose up -d

Salute

GET /salute risponde senza password {"stato":"ok"} (200) oppure {"stato":"problema"} (503) quando un problema di configurazione ferma Febe (password mancante, /dati non scrivibile o su un disco di rete). L'immagine ha un HEALTHCHECK che lo chiede ogni 30 secondi con il programma stesso (/app/febe --controllo-salute: nell'immagine non c'è curl). Unraid mostra lo stato accanto al contenitore; da terminale: docker inspect --format '{{.State.Health.Status}}' febe.

Problemi comuni

Che cosa vedi Che cosa fare
L'interfaccia mostra solo una pagina «Manca la password dell'interfaccia» Imposta FEBE_PASSWORD e riavvia il contenitore
«La cartella dei dati è su un disco di rete» o «non può scrivere» Collega /dati a una cartella su un disco locale (su Unraid l'appdata sul disco di cache) e controlla PUID/PGID
Nel registro: «Il browser non parte… No usable sandbox» Manca il profilo seccomp: vedi «Sandbox» sopra
Unraid non crea il contenitore: «opening seccomp profile … no such file» Manca /mnt/user/appdata/febe-seccomp.json: passo 2 dell'installazione
Unraid non scarica l'immagine: «http: server gave HTTP response to HTTPS client» Il registro 192.168.30.23:3000 non è fra gli insecure-registries: passo 1 dell'installazione
La porta è occupata Cambia la porta pubblicata (o FEBE_PORTA)

Il registro di Febe è in /dati/registro/febe-AAAA-MM-GG.log e nell'output del contenitore (docker logs febe). Contiene azioni ed esiti, nomi utente sì; mai password, cookie, tasti, didascalie, corpi delle risposte né indirizzi firmati del CDN.

Arresto e aggiornamento

  • Allo stop (docker stop, aggiornamento, riavvio di Unraid) Febe chiude la vista remota, ferma il motore (la sessione in corso si chiude), poi Chromium con SIGINT, così la sessione di Instagram è scritta nel profilo, poi Xvfb. Lascia 30 secondi (--stop-timeout 30, stop_grace_period: 30s); di solito ne bastano pochi.
  • Aggiornare: scarica la nuova immagine e ricrea il contenitore (su Unraid «Force update» o «Check for updates»). /dati e /libreria restano; il database si aggiorna da solo all'avvio (migrazioni numerate, in una transazione). Per sicurezza, prima di un aggiornamento importante puoi copiare a mano /dati/febe.sqlite a contenitore fermo.
  • Copie del database: una al giorno in /dati/copie/febe-AAAA-MM-GG.sqlite, sette giorni. Per tornare indietro: ferma il contenitore, sostituisci /dati/febe.sqlite con una copia, riavvia. Se il database va perso, la pagina Impostazioni ▸ Dati lo ricostruisce dalla libreria (_febe.jsonl) senza riscaricare nulla.

Sviluppo senza Docker

Il server si avvia anche fuori dal contenitore, contro il sito di prova locale invece di Instagram (regola 1: mai Instagram dalle prove):

dotnet run --project tools/Febe.SitoDiProva -- --porta 8481 --porta-cdn 8482
FEBE_PASSWORD=prova dotnet run --project src/Febe.Server -- \
  --dati /tmp/febe/dati --libreria /tmp/febe/libreria --importa /tmp/febe/importa --ascolta 127.0.0.1 \
  --sito-di-prova http://127.0.0.1:8481 --accesso-di-prova --prima-sessione 5
  • --sito-di-prova accetta solo indirizzi di questo computer; il «CDN» è 127.0.0.2 sulla porta successiva, oppure --cdn-di-prova. Mappe dei bersagli, lettori e segnali diventano quelli del sito di prova (*.prova.json).
  • --accesso-di-prova apre il sito una volta all'avvio, così il suo cookie di sessione esiste come dopo un accesso.
  • --prima-sessione N fa partire la prima sessione dopo N secondi invece di 2–10 minuti.
  • Come root servono --senza-sandbox (Chromium lo pretende) e, se Chromium non è nel PATH, FEBE_CHROMIUM.
  • Prova d'insieme automatica: dotnet test tests/Febe.Tests --filter "FullyQualifiedName~Febe.Tests.Server".