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

227 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:
```sh
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.
```sh
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`.
```sh
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):
```sh
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"`.