Imported from hadagalberto/media-stack (AGENTS.md). Install upstream with npx skills add hadagalberto/media-stack. Copyright stays with the author.

AGENTS.md — guia pra IA instalar essa stack

Instruções pra qualquer agente de IA (Claude Code, Cursor, Aider, ChatGPT com execução de comandos, etc.) ajudar um humano a instalar e configurar esta stack. Leia isto inteiro antes de rodar qualquer comando.

O que é isso

Stack Docker Compose de streaming privado: Jellyfin + Radarr/Sonarr/Prowlarr (automação de download) + qBittorrent atrás de VPN (gluetun) + Caddy (HTTPS automático via Let's Encrypt, opcional). Um único docker-compose.yml, com duas escolhas independentes via Docker Compose profiles — não são arquivos separados, é o mesmo compose ligando/desligando serviços:

1. Pacote de serviços — COMPOSE_PROFILES inclui full ou não:
   • Básica (sem full): Jellyfin, Radarr, Sonarr, Prowlarr, gluetun+qBittorrent, unpackerr — 7 serviços, o essencial.
   • Completa (full): Básica + Bazarr, Jellyseerr, Homepage, recyclarr, decluttarr, Jellystat, Dozzle, Uptime Kuma, FileBrowser, Apprise.
2. Como acessar — COMPOSE_PROFILES inclui proxy ou não:
   • Com domínio (proxy): sobe o Caddy, HTTPS automático via subdomínios (radarr.seudominio.com, etc.).
   • Sem domínio (sem proxy): Caddy não sobe. Acesso direto por IP:porta, usando o arquivo extra docker-compose.ports.yml (ver seção 5 abaixo). Sem HTTPS.

As duas combinam com vírgula: COMPOSE_PROFILES=full,proxy, COMPOSE_PROFILES=proxy, COMPOSE_PROFILES=full, ou vazio (Básica sem domínio). Pergunte ao humano antes de começar as duas escolhas (ou deixe o ./configure.sh perguntar — ver abaixo). A pergunta "tem domínio?" importa bastante pra segurança — ver seção "Nunca faça isso sem confirmação".

Ordem de execução (não pule etapas)

1. Pré-requisitos — confirme com o humano, não assuma:

   • Conta de VPN WireGuard (ex.: ProtonVPN) — precisa da chave privada. Obrigatório nos dois modos.
   • Espaço em disco num único filesystem pra DATA_ROOT (hardlink entre torrents e biblioteca depende disso — se forem discos diferentes, importar duplica o espaço em vez de linkar).
   • Pergunte: "você tem um domínio apontando pro servidor?"
     • Se sim: precisa de DNS wildcard (A seudominio.com e A *.seudominio.com) e portas 80/443 livres (Caddy usa as duas).
     • Se não: nada disso é necessário — modo IP + portas (ver passo 5). Pergunte também se o servidor tem IP público — isso muda o que você recomenda no passo 5.

2. ./setup.sh — instala Docker/Compose (idempotente, detecta se já tem), cria ${DATA_ROOT}/{torrents,media}, copia os .example → arquivos reais (.env, Caddyfile, config/) se ainda não existirem (não sobrescreve nada que já foi editado).

3. Preencha o .env — duas formas, escolha UMA:

   • Interativo com o humano: rode ./configure.sh e deixe ele responder as perguntas (Básica/Completa, domínio/IP, VPN, etc.). É um wizard read -p comum — se você (a IA) estiver rodando em modo não-interativo sem conseguir repassar stdin ao humano, use a segunda opção.
   • Você preenche direto: pergunte ao humano os valores (domínio se tiver, e-mail, provedor VPN + chave WireGuard, timezone) e edite o .env você mesma com base no .env.example — os comentários explicam cada variável, incluindo COMPOSE_PROFILES (combine full e/ou proxy com vírgula). Nunca invente valores de segredo (chave VPN, senhas) — pergunte, não adivinhe.

4. Cole o hash da senha no Caddyfile — só se o humano tem domínio (pulou pra IP + portas? pule este passo, Caddyfile não é usado). Gere com:

   docker run --rm caddy:latest caddy hash-password --plaintext 'SENHA_ESCOLHIDA_PELO_HUMANO'

   Cole o hash em (adminauth) no Caddyfile (não no .env). Nunca escolha a senha por conta própria — pergunte ao humano ou gere e mostre pra ele guardar.

5. Suba a stack — comando muda conforme domínio ou não:

   # Com domínio (COMPOSE_PROFILES tem "proxy"):
   docker compose up -d
   
   # Sem domínio (IP + portas):
   docker compose -f docker-compose.yml -f docker-compose.ports.yml up -d

   Depois: docker compose logs -f (Ctrl+C sai sem derrubar containers).

   No modo sem domínio, antes de rodar isso: se o humano confirmou que o servidor tem IP público (não é só rede local/VPN pessoal), avise que Radarr/Sonarr/Prowlarr/Bazarr não têm login por padrão nesse modo (o Caddy que fazia Basic Auth não sobe) — recomende ativar Settings → General → Security → Authentication → "Forms (Login Page)" em cada um antes ou logo depois de subir. Não decida sozinha por ele, mas não deixe de avisar.

6. Verifique a saúde antes de dizer que terminou:

   docker compose ps                    # todos "Up", gluetun "healthy"
   docker compose logs gluetun --tail 30   # VPN conectou? erro de chave?

   Se gluetun não ficar healthy, o qbittorrent não sobe (kill switch arquitetural, não é bug) — o problema quase sempre é a chave WireGuard errada no .env. Se for modo com domínio, confira também docker compose logs caddy --tail 30 (certificado emitido?).

7. Interligação dos serviços — isso não é automático, precisa entrar em cada UI web e conectar. Siga a seção "🔌 Interligação dos serviços" do README.md na ordem: qBittorrent → Prowlarr → Radarr/Sonarr → Jellyfin → (Completa: Jellyseerr → Bazarr → extras). URLs de acesso: com domínio, servico.seudominio.com; sem domínio, http://IP:PORTA (tabela na seção "Sem domínio" do README.md). Cada API key copiada de um serviço vai pro .env ou direto na UI do outro — peça pro humano copiar/colar as API keys vendo a tela dele, ou navegue você mesma se tiver acesso de browser/API.

Nunca faça isso sem confirmação explícita

• docker compose down -v — o -v apaga os volumes (bancos do Jellystat, configs). docker compose down sozinho é seguro (mantém dados).
• Editar/apagar qualquer coisa dentro de ${DATA_ROOT} sem perguntar — é a biblioteca de mídia do humano.
• Inventar ou gerar sozinha: senha de admin do Caddy, chave VPN, domínio. Esses valores têm que vir do humano.
• Commitar .env, Caddyfile (sem ser o .example) ou config/ — já estão no .gitignore, não force git add -f neles.
• Trocar RADARR_API_KEY/SONARR_API_KEY regenerando a chave na UI depois de já interligado — quebra Prowlarr/Jellyseerr/Homepage que já usam a chave antiga.
• Subir o modo IP + portas num servidor com IP público sem antes avisar que Radarr/Sonarr/Prowlarr/Bazarr ficam sem login (não tem o Basic Auth que o Caddy dava) — pergunte se é rede local/VPN pessoal antes de tratar isso como "pronto, terminou".

Erros comuns (confira antes de reportar "quebrado")

Onde ficam as coisas

• .env — todos os segredos e escolha de perfil (COMPOSE_PROFILES: full = pacote completo, proxy = tem domínio/Caddy).
• docker-compose.ports.yml — override só usado no modo sem domínio (-f docker-compose.yml -f docker-compose.ports.yml).
• Caddyfile — hash da senha de admin + mapeamento de subdomínios (só existe/importa no modo com domínio).
• config/<serviço>/ — dados/config persistente de cada container.
• ${DATA_ROOT}/torrents/ e ${DATA_ROOT}/media/ — mídia de verdade (fora do repo, definido no .env).
• README.md — documentação completa pra humano; use como referência mais detalhada quando este arquivo não cobrir o caso.