Installa Fisherboy

Fisherboy viene distribuito come singola immagine Docker autonoma (ghcr.io/diegoparras/fisherboy:latest). La stessa immagine esegue l’API, il worker e l’interfaccia web opzionale; un servizio Redis fa da supporto alla coda dei job.

Requisiti

• Docker (Docker Desktop su Windows/Mac, oppure Docker Engine su Linux).
• Un servizio Redis per la coda — incluso nei file compose forniti.
• Circa 1 GB di disco per l’immagine (include Chromium per i livelli con browser).
• Non serve alcun servizio esterno per partire: senza alcun ANONIMAL_URL impostato, viene usato l’anonimizzatore regex integrato.

Fail-closed per impostazione predefinita

Senza password dei ruoli (e senza API_TOKEN o opt-in esplicito per lo sviluppo) configurati, Fisherboy rifiuta ogni richiesta con 401. Imposta almeno SECRET_KEY e GOD_PASSWORD prima di effettuare il login.

Avvio rapido (Docker Compose)

Il percorso più veloce — standalone, con l’interfaccia web:

git clone https://github.com/diegoparras/fisherboy.git
cd fisherboy
cp .env.example .env          # imposta SECRET_KEY + GOD/ANGEL/HUMAN_PASSWORD
docker compose -f docker-compose.standalone.yml up -d --build
# → apri http://localhost:8000

Il file docker-compose.standalone.yml avvia tre servizi — l’API (fisherboy-api, sulla porta 8000), il worker (fisherboy-worker) e Redis (fisherboy-redis) — tutti su una rete privata.

Comandi utili a seguire:

docker compose -f docker-compose.standalone.yml logs -f    # segui i log
docker compose -f docker-compose.standalone.yml down       # ferma

Esegui l’immagine pubblicata

Non vuoi compilare? Scarica l’immagine precompilata (pubblicata da GitHub Actions):

docker pull ghcr.io/diegoparras/fisherboy:latest

Eseguila manualmente con un container Redis accanto:

docker run -d --name fisherboy-redis redis:7-alpine

docker run -d --name fisherboy-api --env-file .env \
  -e APP_MODE=standalone \
  -e REDIS_URL=redis://fisherboy-redis:6379/0 \
  -p 8000:8000 --link fisherboy-redis \
  ghcr.io/diegoparras/fisherboy:latest

docker run -d --name fisherboy-worker --env-file .env \
  -e APP_MODE=standalone \
  -e REDIS_URL=redis://fisherboy-redis:6379/0 \
  --link fisherboy-redis \
  ghcr.io/diegoparras/fisherboy:latest python -m app.worker

L’API è il comando predefinito dell’immagine (uvicorn app.main:app --host 0.0.0.0 --port 8000); il worker viene avviato con python -m app.worker.

.env minimale

Copia .env.example in .env e imposta almeno:

APP_MODE=standalone
SECRET_KEY=<una lunga stringa casuale>
GOD_PASSWORD=<la tua password di amministratore>
ANGEL_PASSWORD=<opzionale>
HUMAN_PASSWORD=<opzionale>
COOKIE_SECURE=0          # 0 per http://localhost locale (senza HTTPS)

Consiglio

Genera rapidamente una chiave: python -c "import secrets; print(secrets.token_hex(32))".

Primo avvio

1. Avvia lo stack (docker compose -f docker-compose.standalone.yml up -d --build). La prima compilazione richiede alcuni minuti; gli avvii successivi sono istantanei.
2. Apri http://localhost:8000.
3. Nella schermata di login, inserisci la tua GOD_PASSWORD.

Esecuzione locale usa e getta

Per un’esecuzione locale, mai esposta, puoi saltare il login impostando FISHERBOY_OPEN_GOD=1 in .env — entra automaticamente come dios. Non usarlo mai su nulla raggiungibile da altri.

Due modalità

Fisherboy funziona in una di due modalità, scelta tramite APP_MODE. Il nucleo è identico; la modalità decide solo se l’interfaccia web viene montata e dove viene delegata la conversione dei documenti.

	standalone	sidekick
Interfaccia web	sì, propria	no, headless
Interfaccia	UI + REST + MCP	REST + MCP
Uso	self-host, personale	dietro Escriba, rete interna

Per la modalità sidekick dietro Escriba, usa docker-compose.yml, che si unisce alla rete esterna escriba_internal per raggiungere Anonimal ed Escriba.

Principali variabili d’ambiente

Variabile	Predefinito	Cosa fa
APP_MODE	sidekick	standalone (monta l’interfaccia web) o sidekick (headless).
SECRET_KEY	—	Obbligatoria con l’autenticazione. Firma il cookie di sessione; usa lo stesso valore su ogni replica.
GOD_PASSWORD / ANGEL_PASSWORD / HUMAN_PASSWORD	—	Password dei ruoli. Impostane almeno una per abilitare il login.
COOKIE_SECURE	1	Invia il cookie di sessione solo su HTTPS. Imposta 0 per http locale.
FISHERBOY_OPEN_GOD	0	Solo per lo sviluppo: accesso aperto come dios senza login. Mai in produzione.
REDIS_URL	redis://fisherboy-redis:6379/0	Coda + store delle envelope.
ANONIMAL_URL	—	Anonimal (dentro Escriba) per il NER completo. Vuoto ricade sull’anonimizzatore regex integrato.
MAX_FETCH_TIER	3	Tetto di escalation (0 statico, 1 TLS, 2 stealth, 3 browser).
PROXIES	—	Pool di proxy separati da virgola/riga.
MAX_JOBS_PER_MIN	60	Limite di frequenza degli invii di job per IP.
CRAWL_MAX_PAGES	100	Limite massimo di pagine per job.
LLM_API_BASE_URL / LLM_API_KEY / LLM_MODEL	—	Per output_format=json (estrazione tramite LLM).
ALLOW_PRIVATE_TARGETS	0	Solo per sviluppo/test — disabilita la protezione SSRF. Mai in produzione.

L’elenco completo e commentato si trova in .env.example nel repository. Per Docker Desktop, EasyPanel e il deployment in produzione, vedi docs/DEPLOY.md.

Leggi la documentazione