Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Mzbb6zeFTjT6Rp8b92AVkA
185 lines
13 KiB
Markdown
185 lines
13 KiB
Markdown
# 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"`.
|