Files
Febe/docs/docker.md
T

185 lines
13 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).
## 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, `seccomp.json` | 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`: il controllo dell'origine usa quel nome | 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.
L'avvio del contenitore copia il profilo in `/dati/seccomp.json` a ogni partenza, così sul server c'è sempre la versione
dell'immagine; Docker però lo legge quando **crea** il contenitore, quindi la prima volta il file va messo a mano
(vedi Unraid, sotto).
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`, blocco dopo tentativi
ripetuti); ogni comando e l'apertura della vista remota controllano che la richiesta arrivi dall'interfaccia stessa.
## Installazione su Unraid
1. Dal terminale di Unraid, **una volta sola**, metti il profilo seccomp dove il modello lo cerca:
```sh
mkdir -p /mnt/user/appdata/febe
wget -O /mnt/user/appdata/febe/seccomp.json \
https://gitea.encke-hake.ts.net/Alby96/Febe/raw/branch/main/docker/chromium/seccomp.json
```
2. Il registro di Gitea dell'immagine è `gitea.encke-hake.ts.net/alby96/febe` (lo stesso host su cui la pubblica il
rilascio). Se Unraid non riesce a scaricarla, accedi al registro dal terminale (`docker login gitea.encke-hake.ts.net`).
3. Docker ▸ Aggiungi contenitore ▸ modello da `docker/unraid/febe.xml` (o dall'indirizzo del modello). 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, `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).
```sh
FEBE_PASSWORD='una frase lunga' docker compose -f docker/compose.yml 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 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"`.