Instalar o Fisherboy

O Fisherboy é distribuído como uma única imagem Docker autocontida (ghcr.io/diegoparras/fisherboy:latest). A mesma imagem roda a API, o worker e a interface web opcional; um serviço Redis dá suporte à fila de jobs.

Requisitos

• Docker (Docker Desktop no Windows/Mac, ou Docker Engine no Linux).
• Um serviço Redis para a fila — incluído nos arquivos compose fornecidos.
• Cerca de 1 GB de disco para a imagem (ela inclui o Chromium para as camadas de navegador).
• Nenhum serviço externo é necessário para começar: sem ANONIMAL_URL definido, o anonimizador de regex embutido é usado.

Fail-closed por padrão

Sem senhas de papel (e sem API_TOKEN ou opt-in explícito de dev) configurados, o Fisherboy rejeita toda requisição com 401. Defina pelo menos SECRET_KEY e GOD_PASSWORD antes de fazer login.

Início rápido (Docker Compose)

O caminho mais rápido — autônomo, com a interface web:

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

O arquivo docker-compose.standalone.yml sobe três serviços — a API (fisherboy-api, na porta 8000), o worker (fisherboy-worker) e o Redis (fisherboy-redis) — todos em uma rede privada.

Comandos úteis de acompanhamento:

docker compose -f docker-compose.standalone.yml logs -f    # acompanhar logs
docker compose -f docker-compose.standalone.yml down       # parar

Rodar a imagem publicada

Não quer construir? Baixe a imagem pré-construída (publicada pelo GitHub Actions):

docker pull ghcr.io/diegoparras/fisherboy:latest

Rode-a manualmente com um container Redis ao lado:

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

A API é o comando padrão da imagem (uvicorn app.main:app --host 0.0.0.0 --port 8000); o worker é iniciado com python -m app.worker.

.env mínimo

Copie .env.example para .env e defina ao menos:

APP_MODE=standalone
SECRET_KEY=<uma string aleatória longa>
GOD_PASSWORD=<sua senha de admin>
ANGEL_PASSWORD=<opcional>
HUMAN_PASSWORD=<opcional>
COOKIE_SECURE=0          # 0 para http://localhost local (sem HTTPS)

Dica

Gere uma chave rapidamente: python -c "import secrets; print(secrets.token_hex(32))".

Primeira execução

1. Inicie a stack (docker compose -f docker-compose.standalone.yml up -d --build). A primeira construção leva alguns minutos; as inicializações posteriores são instantâneas.
2. Abra http://localhost:8000.
3. Na tela de login, informe sua GOD_PASSWORD.

Execução local descartável

Para uma execução local, nunca exposta, você pode pular o login definindo FISHERBOY_OPEN_GOD=1 no .env — ele entra como dios automaticamente. Nunca use isso em algo acessível por outros.

Dois modos

O Fisherboy roda em um de dois modos, escolhido por APP_MODE. O núcleo é idêntico; o modo apenas decide se a interface web é montada e onde a conversão de documentos é delegada.

	standalone	sidekick
Interface web	sim, a sua própria	não, headless
Interface	UI + REST + MCP	REST + MCP
Uso	self-host, pessoal	por trás do Escriba, rede interna

Para o modo sidekick por trás do Escriba, use docker-compose.yml, que se junta à rede externa escriba_internal para alcançar o Anonimal e o Escriba.

Principais variáveis de ambiente

Variável	Padrão	O que faz
APP_MODE	sidekick	standalone (monta a interface web) ou sidekick (headless).
SECRET_KEY	—	Obrigatória com auth. Assina o cookie de sessão; use o mesmo valor em cada réplica.
GOD_PASSWORD / ANGEL_PASSWORD / HUMAN_PASSWORD	—	Senhas de papel. Defina ao menos uma para habilitar o login.
COOKIE_SECURE	1	Envia o cookie de sessão apenas via HTTPS. Defina 0 para http local.
FISHERBOY_OPEN_GOD	0	Somente dev: acesso aberto como dios sem login. Nunca em produção.
REDIS_URL	redis://fisherboy-redis:6379/0	Fila + armazenamento de envelopes.
ANONIMAL_URL	—	Anonimal (dentro do Escriba) para NER completo. Vazio faz fallback para o anonimizador de regex embutido.
MAX_FETCH_TIER	3	Teto de escalonamento (0 estático, 1 TLS, 2 stealth, 3 navegador).
PROXIES	—	Pool de proxies separado por vírgula/linha.
MAX_JOBS_PER_MIN	60	Rate-limit de submissões de jobs por IP.
CRAWL_MAX_PAGES	100	Limite rígido de páginas por job.
LLM_API_BASE_URL / LLM_API_KEY / LLM_MODEL	—	Para output_format=json (extração via LLM).
ALLOW_PRIVATE_TARGETS	0	Somente dev/teste — desabilita a proteção SSRF. Nunca em produção.

A lista completa e comentada está em .env.example no repositório. Para Docker Desktop, EasyPanel e deploy em produção, veja docs/DEPLOY.md.

Ler a documentação