O report procedia, e a correção já está disponível na v1.16.0.

Atualize pra v1.16.0

Se você usa o ai-jail, o update é o de sempre:

# Arch Linux (AUR)
yay -Syu ai-jail-bin

# Homebrew (macOS / Linux)
brew update && brew upgrade ai-jail

# crates.io
cargo install ai-jail --force

# mise
mise cache clear && mise upgrade github:akitaonrails/ai-jail

O que mudou na v1.16.0

Até a v1.15.x, o ai-jail montava o socket do Docker dentro da jaula automaticamente, sempre que /var/run/docker.sock existia no host. Read-write. Sem aviso, sem flag, sem pedir opinião. Eu documentei isso no README como “favorece usabilidade”, e era verdade: agente de coding frequentemente precisa rodar um docker compose pra subir banco de testes, e o passthrough automático poupava configuração.

A partir da v1.16.0 o comportamento inverteu:

• O passthrough do socket ficou desligado por padrão. Só entra se você pedir explicitamente com a flag --docker ou com no_docker = false no .ai-jail.
• Quando você liga e existe um socket no host, o ai-jail imprime um aviso na largada deixando claro que aquilo equivale a dar root no host pro processo dentro da jaula.
• O ai-jail status agora mostra Docker como disabled (default), pra ninguém achar que ligou sem querer.
• Nos modos --lockdown e browser profile o socket nunca entra, como já era antes.

Mudança de comportamento, sim, e de propósito. Se o seu workflow depende de Docker dentro da jaula (o meu depende em alguns projetos), o opt-in é uma linha no .ai-jail do projeto:

no_docker = false

O nome do campo ficou feio (no_docker = false pra ligar, eu sei), mas configs antigas continuam parseando igual e o --no-docker / no_docker = true funcionam como antes. Só o default mudou. Os detalhes estão nas release notes da v1.16.0.

O que o issue #88 mostrou

O report do mdindoffer é daqueles que todo mantenedor quer receber: resumo preciso, repro em poucas linhas, proposta de correção. A essência:

O ai-jail montava o socket cru do Docker dentro da sandbox, read-write. O daemon do Docker roda como root no host. Logo, um agente dentro da jaula podia rodar isto:

docker run --rm -v /:/host alpine sh -c 'cat /host/etc/shadow'

E pronto. Leitura de qualquer arquivo do host, como root. Isso derrota de uma vez só o $HOME em tmpfs, o --mask, o --deny-path e o Landlock, porque a ação deixa de acontecer dentro da sandbox: acontece no daemon, que vive fora e acima de qualquer namespace que o bwrap criou. O agente nem precisa escapar da jaula quando a jaula tem uma porta que dá direto na sala de máquinas.

Em retrospecto, deixar isso ligado por padrão foi uma falha de design. Eu sabia que o passthrough era “perigoso” no abstrato, tanto que escrevi isso no README. O que eu não tinha internalizado: perigoso desse jeito, com esse default, já é vulnerabilidade.

O mdindoffer ainda propôs o caminho de hardening definitivo: em vez de montar o socket cru, interpor um proxy filtrado (estilo o wollomatic/socket-proxy) que só aceita bind mounts de caminhos que o agente já pode escrever dentro da jaula. Está no radar pra uma versão futura. Pra fechar o buraco agora, opt-in com aviso explícito resolve o default, que era onde o problema morava.

A classe de vulnerabilidade: docker.sock é root

Essa não é a primeira vez que eu esbarro nessa história, e aposto que também não é a sua. “Quem tem acesso ao socket do Docker tem root no host” é um dos clássicos da segurança de containers, documentado pela própria Docker na página de daemon attack surface: só usuários confiáveis devem controlar o daemon, porque o Docker permite compartilhar qualquer diretório do host com um container, sem restrição nenhuma de acesso.

O motivo técnico é simples. O dockerd é um daemon que roda como root e obedece comandos que chegam pela API no socket Unix /var/run/docker.sock. A CLI docker é só um cliente dessa API. Quando você pede docker run -v /:/host, quem cria o container e monta o filesystem inteiro do host dentro dele é o daemon, com privilégio total. E processo dentro de container roda como uid 0 por padrão, que o kernel enxerga como uid 0 de verdade (salvo user namespace remapping, que quase ninguém liga). A conta fecha: acesso de escrita no socket equivale a root no host. O grupo docker é sudo sem senha com outro nome.

A demonstração, na sua máquina

Se você tem Docker instalado e seu usuário no grupo docker, reproduz agora. Sem sudo, sem explorar bug nenhum:

# confirme que você é um usuário comum
$ id
uid=1000(akitaonrails) gid=1000(akitaonrails) groups=...,docker

# tente ler o /etc/shadow diretamente: negado, como esperado
$ cat /etc/shadow
cat: /etc/shadow: Permission denied

# agora peça pro daemon fazer isso por você
$ docker run --rm -v /:/host alpine sh -c 'head -3 /host/etc/shadow'
root:$6$...:...
bin:!:...
daemon:!:...

E se quiser o pacote completo, uma shell de root no seu próprio host:

$ docker run --rm -it -v /:/host alpine chroot /host /bin/bash
# id
uid=0(root) gid=0(root) groups=0(root)

Nenhum exploit, nenhum 0-day. Você usou a API oficial, do jeito documentado, e saiu de usuário comum pra root em um comando. Era exatamente isso que um agente dentro do ai-jail conseguia fazer até hoje, mesmo com todas as camadas (bwrap, Landlock, seccomp, rlimits) ligadas.

Por que isso ainda existe?

Se todo mundo sabe disso há mais de uma década, por que ninguém “consertou”? A resposta curta: isso é arquitetura, e arquitetura não se resolve com patch.

• O daemon root com API todo-poderosa foi o design que fez o Docker simples de operar. Autorização granular por requisição existe na forma de authorization plugins, mas é opt-in, chata de configurar, e eu conto nos dedos os setups que já vi usando.
• O userns-remap existe desde o Docker 1.10 e mapeia o root do container pra um usuário sem privilégio no host. Vem desligado de fábrica, porque quebra compatibilidade com imagens e volumes que assumem uid 0.
• O rootless mode roda o daemon inteiro como o seu usuário, com o socket em $XDG_RUNTIME_DIR/docker.sock. Funciona, mas tem restrições de rede e storage, e a internet inteira de tutoriais assume o daemon root no caminho clássico.
• O Podman nasceu rootless e sem daemon justamente por causa dessa crítica. Tem uma seção inteira sobre ele logo abaixo.

Resumindo: isso vai continuar existindo. Toda ferramenta que monta /var/run/docker.sock dentro de um ambiente “pra conveniência” abre o mesmo buraco, consciente ou não. CI que monta o socket pra build de imagem, IDE remota, code-server, sandbox de agente de IA (oi, eu), plugin de painel web. O ajuste fica sempre do lado de quem monta o ambiente.

Curiosidade: isso é tudo, menos novo

Se você me acompanha há algum tempo, essa história toda deve ter dado déjà vu. Em 2023 eu gravei o [Akitando #139] - Entendendo Como Containers Funcionam, onde eu explico o que um container realmente é: um processo comum do Linux, limitado por cgroups, enganado por namespaces, com as capabilities cortadas. Sem mágica e sem máquina virtual. E olha o que já estava na lista de links daquele episódio: um walkthrough de privilege escalation via Docker, demonstrando exatamente o truque do docker run -v /:/host. O buraco que o issue #88 explorou dentro do ai-jail é o mesmo que eu já apontava num video de 2023, e que já era manjado muito antes disso.

Ninguém sabe disso melhor que a Red Hat. O Podman nasceu lá em 2018 como resposta direta a essa arquitetura: sem daemon central, rootless por padrão. Cada container vira filho direto do seu usuário, via fork-exec, sem um processo todo-poderoso rodando como root intermediando nada. O “docker.sock é root” simplesmente não existe nesse modelo, porque não existe nem docker.sock, nem daemon, nem root.

E antes que você pergunte: sim, eu uso Podman em algumas coisas e recomendo. Mas ele também não é solução perfeita, e vale entender o porquê.

O que o Podman faz bem:

• A arquitetura certa. Daemonless e rootless desde o dia zero. A classe inteira de vulnerabilidade deste artigo perde o sentido.
• Compatibilidade de CLI. alias docker=podman cobre a maioria esmagadora dos comandos do dia a dia. Build, run, push, pull: mesmos comandos, mesmas flags.
• Integração com systemd. Os Quadlets são, na minha opinião, o jeito mais limpo de rodar container como serviço no Linux. O Docker nunca chegou perto disso.

E onde ele tropeça:

• O socket de compatibilidade não é 100%. O Podman oferece um socket compatível com a API do Docker (o podman.socket), e muita ferramenta funciona em cima dele. Mas “muita” não é “toda”: Testcontainers, alguns plugins de IDE, ferramentas de CI mais exóticas tropeçam em diferenças de comportamento. Funciona até o dia em que não funciona, e aí você perde uma tarde debugando.
• Compose é cidadão de segunda classe. O docker compose oficial até conversa com o socket do Podman, e existe o podman-compose, mas nenhum dos dois tem a mesma redondeza do par original. Projeto com compose complicado é onde a migração costuma enroscar.
• Rootless tem preço. A rede rootless (slirp4netns, e hoje o pasta) tem limitações: sem ping por padrão, IP de origem esquisito, throughput menor. Imagem que assume uid 0 e volume com permissão errada pedem ajuste. Nada grave, mas é atrito.
• Docker Desktop é um produto. No macOS e no Windows, o Docker Desktop entrega uma experiência polida que o Podman Desktop ainda está alcançando. Pra muita gente, esse é o único contato com containers que existe.

Somando tudo, você chega na resposta de por que o mundo continua no Docker: inércia de ecossistema. Todo tutorial, todo CI, toda imagem de exemplo, todo docker run colado de Stack Overflow assume o daemon root no caminho clássico. O Docker virou o nome da categoria, tipo Bombril. Migrar pro Podman é tecnicamente fácil e politicamente caro: é você contra o conhecimento acumulado da internet inteira.

Um detalhe que importa pra quem usa sandbox: montar o socket do Podman rootless dentro de uma jaula é bem menos catastrófico que montar o do Docker. O “daemon” equivalente roda como o seu usuário, então um agente mal-intencionado ganharia os seus privilégios, não root. Continua ruim (dá pra sobrescrever o seu ~/.ssh com eles, por exemplo), mas é outro campeonato. Mesmo assim, o default do ai-jail continua valendo: não montar socket nenhum, de runtime nenhum. Opt-in é opt-in.

Boas práticas pra isso não morder você

A lista que eu aplico e recomendo:

1. Trate o grupo docker como sudo sem senha. Antes de adicionar qualquer usuário ou serviço nele, pergunte se você daria sudo irrestrito pra aquilo. É a mesma coisa.
2. Nunca monte /var/run/docker.sock em ambientes não confiáveis. Agente de IA, job de CI que roda código de pull request de estranho, container de terceiro. Faça um grep -r docker.sock nos seus docker-compose, manifests de CI e configs de ferramentas. Aparece em mais lugares do que você lembra.
3. Precisou expor pra algo semiconfiável? Use um socket proxy. O wollomatic/socket-proxy e o docker-socket-proxy da Tecnativa ficam entre o cliente e o daemon com allowlist de endpoints e bloqueio de bind mounts arbitrários. Read-only por padrão, você liga só o que precisa.
4. Prefira rootless sempre que possível. Podman rootless no Linux é o caminho mais limpo; o rootless mode do próprio Docker é a segunda opção. O daemon deixa de ser root e essa classe inteira de problema perde a mordida.
5. Em CI, construa imagem sem daemon privilegiado. Kaniko e Buildah constroem imagens rootless, sem precisar montar socket nenhum no job.
6. Não conseguiu rootless? Ligue o userns-remap. Custa uma tarde de testes com seus volumes e compra isolamento real entre o root do container e o root do host.
7. No ai-jail, deixe o default trabalhar por você. Docker desligado, e --docker só nos projetos onde você confia no workload como confiaria num sudo. Regra prática: se você não daria sudo cego pro agente naquele diretório, também não dê --docker.

Conclusão

Uma sandbox bem construída perde boa parte do valor se tiver uma porta dos fundos aberta por conveniência. O bwrap, o Landlock, o seccomp e os rlimits do ai-jail continuam fazendo o trabalho deles, mas nenhum deles enxerga o que acontece quando o processo lá dentro pede gentilmente pro daemon root do host montar o filesystem inteiro num container. Camada de segurança que você não audita vira decoração.

Meu agradecimento público ao @mdindoffer: report limpo, repro mínima, severidade correta e ainda por cima proposta de solução. É assim que se reporta vulnerabilidade em projeto open source.

Se você quer o contexto completo de como eu uso sandbox no dia a dia, escrevi sobre isso em Como me precaver pros meus agentes não apagarem minhas coisas?. A história do ai-jail está em AI Agents: Garantindo a Proteção do seu Sistema e na reescrita em Rust.

Agora vai lá e roda o upgrade.

No meu canal eu inclusive usei jogos antigos pra ensinar fundamentos de computação. No Akitando sobre Super Mario e computadores antigos eu explico 6502, mapa de memória, PPU, limitações de hardware e por que aqueles jogos eram programados daquele jeito. Se você nunca viu, recomendo assistir:

O problema é o de sempre: a cada poucos anos eu resolvo montar uma máquina nova de emulação, baixo de novo os emuladores principais da vez, e lá vou eu repetir o mesmo ritual masoquista. PCSX2, RPCS3, Eden, Azahar, Dolphin, RetroArch, Flycast, shadPS4 e por aí vai. Cada um com suas manias. Cada um com sua forma particular de te fazer perder horas.

Em teoria, montar tudo isso deveria ser divertido. Na prática, leva dias. E não é exagero. Dolphin ainda consegue ser um dos piores porque controle de GameCube e Wii não tem nada de padrão. RPCS3 exige tuning por jogo. Eden precisa de DLC, update e cheats no lugar certo. shadPS4 é um festival de tentativa e erro. Quando eu finalmente terminava de configurar tudo, eu já não queria mais jogar porcaria nenhuma. Eu só queria fechar os menus e ir fazer outra coisa.

Eu já cheguei a dizer que talvez a graça estivesse justamente no tuning. Não acho mais isso. Depois de repetir esse processo vezes demais, eu cansei. Eu quero jogar os jogos, não preencher formulário escondido em GUI de emulador.

O problema não era Linux

Eu já resolvi esse tipo de coisa de várias formas no passado. Anos atrás eu rodava Linux no host e um Windows virtualizado com GPU passthrough pra jogar dentro da VM. Na época era o que fazia sentido. Eu fiz um vídeo inteiro sobre isso:

Mas isso foi antes do trabalho monumental da Valve, do Proton, do Wine moderno e de toda a comunidade open source que empurrou o desktop Linux pra um lugar muito melhor. Hoje dá pra evitar Windows na maior parte dos casos. No outro vídeo abaixo eu explico a evolução de CPU, GPU, OpenGL, Vulkan e por que chegamos nesse ponto:

Meu mini-PC dedicado a games com RTX 4090 continua sendo minha principal máquina de Steam, especialmente agora que montei um cockpit decente de sim racing. Nele eu uso EmuDeck, que nasceu justamente pra automatizar instalação e configuração de emuladores no Steam Deck, depois passou a suportar Windows também, e ajuda bastante a reduzir a complicação de montar esse tipo de ambiente. Mas meu desktop principal também é forte demais pra ficar subutilizado. Ele tem uma RTX 5090, e hoje eu uso essa GPU principalmente pra testar LLMs e benchmarking, como contei em Testando LLMs Open Source e Comerciais. Seria um desperdício não usar isso pra gaming também.

Só que no Linux eu queria outra coisa. Eu não queria uma caixa-preta fazendo tudo por mim sem eu saber exatamente o que estava sendo alterado, principalmente no meu PC principal, que é minha máquina de trabalho. Eu queria um setup meu, feito “na mão” no sentido certo da expressão: não clicar GUI por GUI, mas entender o que está sendo configurado, manter os arquivos sob meu controle, e conseguir reconstruir tudo do jeito que eu gosto. Eu sei que o pessoal do NixOS vai pular aqui pra dizer “é só usar Nix” — explico mais abaixo por que descartei essa rota. Também não queria transformar a minha máquina de trabalho num carnaval de pacote de emulador, tema GTK, wrapper, launcher, runtime esquisito e config enterrada em ~/.config. Nem queria dual boot ou VM. Em 2026, a melhor resposta pra isso, na minha opinião, é Distrobox.

Pelo que o próprio projeto explica, Distrobox é um wrapper em cima de podman, docker ou lilipod pra criar containers fortemente integrados ao host, com acesso a HOME, Wayland/X11, áudio, dispositivos USB, storage externo e GPU. Ou seja: exatamente o tipo de isolamento pragmático que eu queria. Não é uma fronteira de segurança, e o próprio site deixa isso claro. Não use pensando em sandbox de alta segurança. Use pensando em separar ambientes sem ficar pagando o preço de uma VM.

E antes que alguém repita a confusão de sempre: container não é máquina virtual. Eu explico isso com calma neste outro episódio:

O setup

A ideia é simples: um Arch Linux vanilla dentro de um Distrobox chamado gaming, com os caminhos do NAS montados em read-only, a biblioteca Steam acessível onde faz sentido, e todos os emuladores instalados lá dentro. Como o container tem acesso a GPU NVIDIA, áudio, USB e demais periféricos, eu separo trabalho de jogo na mesma máquina sem penalidade prática de performance.

O bootstrap inicial é mais ou menos isso:

distrobox create --name gaming --image archlinux:latest --nvidia \
  --home /mnt/data/distrobox/gaming \
  --volume /mnt/data/steam:/mnt/data/steam \
  --volume /mnt/terachad/Emulators:/mnt/terachad/Emulators:ro

Só esse começo já tem pegadinha. O archlinux:latest dentro de Distrobox vem sem [multilib] no pacman.conf, com um sudoers mal configurado, e com o velho problema do --nvidia: as libs do driver do host entram bind-mounted read-only, então qualquer instalação que dependa de nvidia-utils quebra com conflito de arquivo. Só isso já é o tipo de dor de cabeça que, alguns anos atrás, me faria abrir meia dúzia de abas, mais uma penca de terminais, e gastar uma noite inteira em tentativa e erro.

Desta vez eu fiz diferente.

Claude Code como assistente de infraestrutura

Eu venho ficando cada vez mais confortável em usar Claude Code como meu assistente de infraestrutura nas minhas máquinas pessoais. Eu não faria isso cegamente em servidor de cliente. Mas em máquina minha, em ambiente que eu posso destruir e reconstruir quantas vezes eu quiser, faz todo sentido. Escrevi sobre isso no artigo Migrando meu Home Server com Claude Code, quando usei Claude pra instalar e configurar openSUSE MicroOS, Docker, NFS, firewall, hardening e o resto todo sem eu precisar ficar lembrando comando chato de shell.

Então pensei: por que não fazer a mesma coisa aqui?

Foi exatamente o que eu fiz. Comecei com prompts bem objetivos, sempre pedindo duas coisas ao mesmo tempo: fazer o trabalho e documentar o suficiente pra eu poder reconstruir tudo depois. O histórico mais importante ficou em docs/distrobox-gaming-prompts.md.

Vale um esclarecimento: aqueles prompts no GitHub não são as minhas mensagens cruas, do jeito que saíram na hora. Depois que tudo funcionou, eu pedi pro próprio Claude reescrever os prompts de forma organizada e detalhada, só pra fins de documentação. Os prompts originais eram bem mais simples e bem menos específicos. Eu descrevia o objetivo e deixava o Claude descobrir sozinho paths, arquivos de configuração, formatos e comandos necessários.

O primeiro prompt criou a box com --nvidia, --home separado e os mounts corretos. O segundo resolveu os três problemas clássicos do Arch dentro de Distrobox: sudo, multilib e o dummy package de nvidia-utils. O terceiro instalou a base de gaming, inclusive um detalhe que eu teria esquecido fácil se estivesse fazendo na mão: pipewire-pulse, necessário pra vários emuladores não ficarem mudos nem perderem sincronia.

O ponto não é o texto em si. O ponto é o método. Eu não preciso lembrar a ordem exata, nem as opções precisas, nem onde está a documentação de cada detalhe. Eu descrevo o objetivo e deixo o agente carregar o piano. Fico no papel de tech lead: observando, revisando, corrigindo direção quando precisa, e mandando continuar.

O projeto no GitHub

O setup vive em akitaonrails/distrobox-gaming, estruturado como um projeto Ansible. 17 roles cobrem desde criação da box, bootstrap de pacotes, seed de configs, instalação de DLC, configuração de controle, até verificação pós-setup. Os playbooks principais são:

• site.yml: setup completo do zero
• reset-configs.yml: reset só das configs (útil quando você quer zerar tuning e redeployar)
• backup.yml / restore.yml: snapshot e restauração do container inteiro via podman commit
• refresh-shadps4.yml: atualização standalone do shadPS4
• install-xenia.yml: instalação opcional do Xenia Manager (Wine prefix)

O passo a passo completo está em docs/rebuild-runbook.md. As decisões de pacote (por que AUR em vez de Flatpak, por exemplo) estão em docs/distrobox-gaming-packages.md.

Por que não Nix?

Alguém vai perguntar. “Você tá recriando ambiente reproduzível. Por que não usar NixOS, ou pelo menos nix-shell/flakes?”

Eu considerei e descartei. O ecossistema de emuladores que eu preciso vive no AUR. Pacotes -bin do AUR são wrappers de AppImage que empacotam o binário oficial do upstream sem compilar nada. rpcs3-bin, pcsx2-latest-bin, eden-bin, duckstation-qt-bin, shadps4-bin — esses binários acompanham o upstream praticamente no dia do lançamento. No Nixpkgs, muitos desses emuladores ficam semanas ou meses atrás do release, e alguns nem existem. Criar um overlay Nix pra cada emulador que eu preciso, manter, e lidar com os patches de compatibilidade quando upstream muda, é trabalho que eu não quero ter.

Tem também o modelo mental. Eu não quero aprender a linguagem Nix, o sistema de derivações e o modelo de avaliação pra montar um ambiente de games pessoal. Ansible eu já conheço, as roles são pastas com tasks em YAML, e o debug é ansible-playbook -vvv. Quando dá errado, eu leio a mensagem de erro, abro o task que falhou, e sei exatamente onde mexer. Se eu precisasse do mesmo nível de reprodutibilidade em escala, num cluster, com rollback atômico, aí sim Nix teria argumento. Pra um distrobox com emuladores na minha máquina pessoal, Ansible resolve com muito menos atrito.

Flatpak também foi testado e descartado. O bwrap (bubblewrap) do Flatpak não aninha direito dentro das mount namespaces do Docker, então apps Flatpak simplesmente não rodam dentro de distrobox. A alternativa seria instalar Flatpak no host, mas aí você volta ao problema de poluir a máquina de trabalho com pacotes de gaming. Além disso, as versões Flatpak de emuladores ficam bem atrás do AUR — o pcsx2-latest-bin do AUR tracka o AppImage 2.7.x, enquanto o Flathub ainda distribui a v2.6.3.

Plataformas cobertas

O setup cobre 12 plataformas hoje:

RetroArch entra por cima pra cobrir o resto (NES, SNES, Genesis, N64, arcade, etc.), com 21 cores do buildbot e 8 asset packs (databases, shaders, cheats, overlays, autoconfig).

Frontend é ES-DE. As definições dos sistemas customizados ficam em ansible/group_vars/all/esde.yml e cada emulador entra com um wrapper que já sobe com as variáveis certas de GPU (voltarei nisso).

GPU hardforce pra NVIDIA

Num sistema híbrido com NVIDIA dGPU + AMD iGPU (meu caso no desktop), Vulkan às vezes escolhe o iGPU sozinho e o resultado é emulador rodando a 15 fps enquanto a 5090 fica parada. A solução é forçar o ICD Vulkan da NVIDIA em todos os launchers.

Cada entrada de desktop rendereizada pelo Ansible exporta VK_ICD_FILENAMES apontando pro ICD da NVIDIA, e o wrapper do ES-DE faz a mesma coisa antes de lançar qualquer core. Em combinação com a flag --nvidia na criação da box, que bind-monta os drivers do host em read-only, o resultado é previsível: Vulkan sempre na dGPU NVIDIA, independente do estado do sistema na hora.

Isso vale principalmente pra quem tem setup híbrido. Num desktop com só uma GPU, o ICD filtering é placebo, mas também não atrapalha.

PS2: PCSX2 com tuning por jogo

A linha Gran Turismo é meu vício declarado. Cada versão precisa de tweak específico. O setup do PCSX2 hoje tem configs globais razoáveis (Vulkan, 4x SSAA, widescreen 16:9, Xbox-style bindings, FXAA + PCRTC antiblur, 16x anisotropic, deinterlace Automatic) e per-game INIs pros títulos que eu realmente jogo:

• Gran Turismo 3 A-spec (SCUS-97102 + bundle PBPX-95503): widescreen pnach, pack de retextura opcional (desabilitado por default porque NFS causa flicker em cutscenes de showcase de carro)
• Gran Turismo 4 USA (SCUS-97328): HD HUD do Silentwarior112, pack completo de retextura, patches do Silent pra gatilho e câmera, widescreen pnach
• Gran Turismo 4 Spec II (SCUS-97436, CRC 4CE521F2): caso especial — os HD packs de GT4 vanilla são linkados via symlink porque o Spec II tem mesma estrutura mas CRC diferente. Widescreen pnach renomeado pra bater com o CRC. Deinterlace mode 8 (Adaptive TFF), ShadeBoost tuning (+10 saturação, +3 brilho, +2 contraste) pra corrigir ghosting de pause-interlace e saturação anêmica do upscale
• Enthusia Professional Racing (SLUS-20967): HD textures + widescreen
• Ridge Racer V (SLUS-20002): widescreen + no-interlace pnach

Os pnach files do Silent e da comunidade são baixados automaticamente pelo role pcsx2_textures, que também faz o deploy do pack de cheats do NAS e instala os HD packs do Spec II via symlink. Widescreen é ligado via gamesettings por CRC (PCSX2 identifica jogo por CRC antes de aplicar o pnach).

Sobre versão do PCSX2: o pcsx2-latest-bin do AUR tracka a linha 2.7.x, que é onde todas as features modernas estão (texture replacement, FXAA, PCRTC antiblur). O pcsx2 padrão dos repos oficiais do Arch ainda está na 2.6.3. A diferença é mais de 250 commits de correção e feature novo.

PS3: RPCS3 com per-game configs curados

RPCS3 tem um detalhe chato: configs por jogo ficam em ~/.config/rpcs3/custom_configs/config_<SERIAL>.yml. O formato do arquivo tem versão, e se você gerar um YAML manualmente com versão errada, o RPCS3 rejeita silenciosamente e volta pro default. Isso custou tempo pra descobrir.

A role rpcs3_per_game_configs resolve isso assim:

1. Query o compatibility DB da comunidade RPCS3 pra pegar os presets recomendados por título
2. Aplica overrides curados por cima pra títulos que eu sei que precisam de ajuste específico (tipicamente GT5 e GT6)
3. Salva o YAML com a filename convention exata (config_<SERIAL>.yml, prefixo config_ obrigatório)

Na linha Gran Turismo:

• GT5 (BCUS98114, BCES00569): Resolution Scale 300%, Shader Precision Ultra, Force High Precision Z, SPU XFloat Accurate, Multithreaded RSX. Combinação que mata o dithering típico do RSX sem quebrar a GT series safety config (WCB/RCB off).
• GT6 (BCES01893 + variantes regionais): caso especial, versão travada em v1.05. Patches 1.06+ regridem com superfícies pretas em carros no menu garagem. O script extract_ps3_dlc.py tem per-title PATCH ceiling justamente pra pinar o GT6 no 1.05 mesmo quando o PSN cuspe patches mais novos. Além disso, Force CPU Blit ligado é mandatório (sem ele, flicker de tela inteira). O trade-off é que o retrovisor fica permanentemente preto — ligar WCB restauraria o retrovisor mas downgradaria pra 720p nativo. Prefiro perder o retrovisor.

Mais detalhes desses dois em docs/gt5-rpcs3.md e docs/gt6-rpcs3.md.

Update checker de PS3

Pra não ter que abrir a GUI do RPCS3 e ficar clicando em Download Game Updates jogo por jogo, criei um script em Python: check_ps3_updates.py. Ele percorre os jogos instalados em dev_hdd0/game, parseia o PARAM.SFO pra pegar a versão atual de cada título, consulta o servidor de updates da PSN (a0.ww.np.dl.playstation.net) e compara com o cache local de patches. --list mostra o diff; --download baixa o que falta. --max-version respeita os teto por título (ex: 1.05 pro GT6).

O primeiro scan na minha biblioteca achou 51 de 72 jogos com update disponível, 69 patches faltando localmente, uns 24 GB no total. Só o GT6 sozinho tinha 16 patches faltando, da 1.07 até 1.22, que eu descartei pelos motivos acima.

Os patches chegam como pacotes PSN tipo 0x0001 sem criptografia, então o próprio extract_ps3_dlc.py consegue instalar depois. A chamada padrão:

distrobox enter gaming -- python3 scripts/extract_ps3_dlc.py \
  "/mnt/terachad/Emulators/EmuDeck/roms_heavy/ps3-DLC" \
  --dest "/mnt/data/distrobox/gaming/.config/rpcs3/dev_hdd0/game"

Acompanhar versão de DLC de PS3 manualmente, jogo por jogo no RPCS3, é inviável. Vira lista de tarefas eterna e você só descobre que tinha patch 1.22 quando o jogo crasha.

PS1: DuckStation com per-game

A trilogia Gran Turismo começa no PS1, e a qualidade ali só sobe se você ligar as coisas certas:

• Gran Turismo (SCUS-94949): built-in WidescreenHack do DuckStation (não existe cheat pra esse jogo), PGXP ligado
• Gran Turismo 2 Simulation (SCUS-94455): widescreen cheat + 8 MB RAM cheat (fix de áudio em track crowded), filter JINC2
• Gran Turismo 2 Arcade (SCUS-94488): mesmo tratamento do Simulation

Global defaults: Vulkan, 8x upscale, JINC2 como filter default.

Os cheats pro GT2 saem de um repositório de widescreen fixes e são ligados automaticamente na pasta de cheats do DuckStation.

Switch: Eden com DLC, update e cheats

No Switch, eden-bin é o emulador. A integração automatiza três coisas que antes eu fazia na mão:

1. Install de DLC e update: o role install_dlcs aponta pro diretório de dumps no NAS, identifica os arquivos .nsp/.nsz/.xci/.xcz, e instala tudo em ~/.local/share/eden/nand/user/Contents/registered/. Se o dump está bagunçado (patches e DLC misturados em flat folder), o script reorganize_switch_nsps.py sorteia tudo por Title ID antes.

2. Cheats Atmosphere: os cheats em formato Atmosphere vão symlinkados pro load path do Eden (~/.local/share/eden/load/<TITLE_ID>/cheats/). O role switch_cheats faz isso por todos os títulos cobertos pelo pack do NAS.

3. Update checker: check_switch_updates.py lista títulos com update disponível vs o que tá instalado localmente. Útil pra não perder patch importante de jogo que sai atualização ainda.

Atenção ao detalhe que me queimou: QT_STYLE_OVERRIDE precisa ser desarmado antes de lançar o eden-bin, senão ele conflita com Kvantum e quebra a UI. O wrapper já faz o unset antes do exec.

Xbox 360: Xenia Manager via Wine

Xbox 360 ainda é território áspero no Linux. Não tem emulador nativo decente. A melhor rota hoje é Xenia rodando via Wine, gerenciado pelo Xenia Manager.

Isso é opt-in no meu setup. O playbook install-xenia.yml cria um Wine prefix dedicado, baixa o Xenia Manager, e registra os launchers. Não faz parte do site.yml principal porque nem todo mundo quer Wine no meio do caminho.

Project Forza Plus (Forza Motorsport 2/3/4)

Forza antigo ainda é o rei do simcade de geração passada. Rodar FM2/3/4 no Xenia requer mods da comunidade Project Forza Plus: patches de compatibilidade, mods de performance, instalação de title updates específicos. Documentei o processo em docs/project-forza.md.

Project Gotham Racing 3 e 4

PGR3 roda razoavelmente bem no Xenia Canary. PGR4 precisa de ajuste específico: render_target_path_vulkan = "fsi" no config, senão algumas races quebram com artefato visual. Documentei o setup em docs/xbox360-pgr.md. Áudio do PGR4 no NVIDIA ainda tem problema de XMA decoding que gera garbage intermitente. Tem issue aberta no xenia-canary, sem resolução up até agora.

Title Updates em batch

Title Update pra jogo de Xbox 360 era distribuído pela Xbox Live, que já foi desligada. A alternativa é o archive.org, que tem o catálogo completo preservado. Escrevi scripts/download-xbox360-tus.py pra automatizar:

distrobox enter gaming -- python3 scripts/download-xbox360-tus.py \
  --src /mnt/terachad/Emulators/EmuDeck/roms_heavy/xbox360 \
  --dest /mnt/terachad/Emulators/EmuDeck/roms_heavy/xbox360-updates \
  --dry-run

O script precisa do CLI internetarchive autenticado (ia configure uma vez, guarda o token). Ele scaneia a pasta de jogos, faz match contra o manifest do archive.org (cacheado localmente), prioriza por região (USA > World > Europe > Japan), e baixa via ia download --checksum com retry automático. Os .zip resultantes vão pro Xenia Manager via Manage → Install Content, que extrai pro diretório correto (000B0000/).

O setup completo tá em docs/xbox360-title-updates.md.

Steam no distrobox

Desde que o Proton virou cidadão de primeira no Linux, faz sentido ter Steam também no gaming box. Adicionei o pacote steam no Ansible (que puxa multilib e dependências 32-bit), montei /mnt/data/steam em read-write pra a biblioteca persistir fora do container, e criei launcher no host.

Na prática, isso me permite rodar jogos Steam via Proton lado a lado com emulação, sem precisar alternar ambiente. O mini-PC com RTX 4090 continua sendo a máquina principal de Steam no cockpit de sim racing. O desktop é fallback e ambiente de teste.

Shell e controle por controle

Shell mínimo dentro da box

Quando eu entro no gaming box via distrobox enter gaming, eu quero prompt decente mesmo pra troubleshooting rápido. Instalei zsh + starship com config mínima, zero plugins exóticos. Não é meu setup de dev full, é só “prompt que mostra path e git branch sem me dar vergonha”.

Dolphin e o inferno do controle moderno

Dolphin sempre foi o rei do atrito manual. Se você usa um controle mais moderno, como meu 8BitDo Ultimate 2, precisa lembrar como eu gosto do mapeamento de GameCube, como adapto o Wii Remote, quando usar perfil de Nunchuk, quando trocar pro Classic Controller. Eu não tenho a menor paciência pra reconstruir isso na mão toda vez. Os perfis ficam prontos em config/emulator-overrides/dolphin/Profiles/ e são copiados pelo role seed_configs. Detalhes em docs/controller-hotkeys.md.

Alguns tropeços que sobraram

Nem tudo virou magia. Emulação sempre tem casca de banana.

Flycast, por exemplo, tem uma armadilha irritante. O arquivo emu.cfg usa chaves rend.* dentro da seção [config]. Se você cria uma seção [rend] separada, parece certo, mas o emulador simplesmente ignora e depois reescreve tudo com default medíocre. A correção virou wrapper dedicado em $DG_BOX_HOME/bin/flycast-hires:

$DG_BOX_HOME/bin/flycast-hires \
  -config config:pvr.rend=4 \
  -config config:rend.Resolution=2880 \
  -config config:rend.EmulateFramebuffer=no \
  -config config:rend.WideScreen=yes

Detalhes em docs/flycast-resolution.md.

shadPS4 ainda está longe de ser um caso encerrado. O setup atual é focado em Driveclub, com config espelhada, patch XML e links dos sys_modules do firmware 11.00. E isso não foi por acaso: eu gosto muito de Driveclub. Aliás, é praticamente o único jogo ainda preso no PS4 que eu realmente queria conseguir rodar direito. Eu já vi vários vídeos no YouTube mostrando o jogo funcionando, mas até agora eu mesmo não consegui fazer isso rodar de forma satisfatória no Linux. Documentado em docs/driveclub-shadps4.md. A parte boa é que agora eu não dependo mais de memória muscular pra lembrar como lançar, com qual patch, em que pasta, com quais módulos. A parte ruim é que emulação de PS4 ainda é emulação de PS4. Não existe script que faça upstream amadurecer mais rápido. Se alguém souber como fechar essa configuração no Linux, olhe o projeto no GitHub e mande um PR.

Ridge Racer V tem um flickering de textura de carro documentado nas issues do PCSX2 (#3639, #13729). O renderer Hardware é aceitável pra jogo de corrida onde você não fica admirando parado o modelo. Software renderer resolve mas mata performance. Escolhi aceitar o flicker.

O ganho real não é só automação

Seria fácil resumir isso como “olha que legal, usei IA pra automatizar shell script”. Não é isso.

O ganho real é mais chato e mais importante: eu parei de gastar energia mental com trabalho braçal. Não precisei mais lembrar comando raro. Não precisei manter dezenas de abas com wiki, issue, fórum e README. Não precisei deixar meia dúzia de terminais espalhados dando tail em log enquanto tento lembrar que opção escondida de GUI o emulador insiste em regravar no primeiro boot. Eu passei a trabalhar em conversa.

Eu digo pro agente o objetivo. Ele procura os arquivos, lê os logs, encontra o formato certo do config, compara defaults, propõe correções, escreve script, valida paths, verifica UID/GID, confere symlink quebrado, gera wrapper, exporta launcher. Eu continuo responsável pelas decisões, claro. Mas parei de ser digitador de comando raro.

Esse é o ponto que mais me interessa no uso de coding agents em Linux. Eles reduzem dramaticamente a fricção de entrada. Muita gente desiste do desktop Linux não porque o sistema seja incapaz, mas porque a curva de tuning historicamente foi irritante demais. Ter um assistente capaz de ler docs, cruzar config, propor automação e executar com supervisão muda esse jogo.

Se você quiser reproduzir

O repo foi publicado pra isso:

git clone https://github.com/akitaonrails/distrobox-gaming.git
cd distrobox-gaming/ansible
ansible-galaxy collection install -r collections/requirements.yml
cp host_vars/localhost.yml.example host_vars/localhost.yml
$EDITOR host_vars/localhost.yml  # ajuste paths da sua máquina
ansible-playbook site.yml

Xenia é opt-in:

ansible-playbook install-xenia.yml

Leia o README.md e o docs/rebuild-runbook.md antes. Eu não distribuo ROM, BIOS, firmware nem chaves. O repo só detecta, linka e configura o que você já tem na sua própria máquina.

Se você preferir a rota com Claude Code

Minha recomendação é simples:

1. Comece pelo objetivo, não pelo comando. “Quero um distrobox Arch com GPU NVIDIA, home separado, ROMs read-only e Steam rw” é melhor do que despejar meia linha de shell sem contexto.
2. Peça sempre pra documentar o que está fazendo. Se der certo, promova o resultado a script ou role. Se não documentar, você acabou de fabricar uma gambiarra descartável.
3. Trabalhe em fases. Criação da box. Bootstrap. Config de emuladores. Export de launchers. Verificação. Foi exatamente assim que eu quebrei o problema.
4. Peça verificações objetivas. command -v, existência de arquivos, symlinks quebrados, UID/GID, path de ROM, áudio, GPU. A melhor automação é a que falha cedo.
5. Não use agente como papagaio de comando. Use como assistente técnico. Você continua revisando as decisões e mandando ajustar o rumo.

Pra mim, esse foi o ganho. Eu saí do zero pra uma máquina de emulação muito mais completa sem precisar customizar tudo na unha, em GUI, uma janela por vez. E, dessa vez, terminei com energia pra fazer o que eu queria desde o começo.

Jogar.

Com o novo Minisforum MS-S1 Max que comprei, decidi fazer a migração direito. E decidi usar Claude Code desde o início pra acelerar o processo. É um servidor caseiro, só eu uso, o risco de fazer besteira é baixo. Mas se fosse um servidor de produção real, eu jamais faria isso sem review humano rigoroso em cada passo.

O que segue é o relato da migração e o guia pra quem quiser replicar. Se um dia eu precisar reconstruir do zero, esse post é a documentação.

Escolha do sistema operacional

Por que não Ubuntu Server de novo

Eu usei Ubuntu Server no NUC por praticidade. Mas do-release-upgrade é uma roleta russa. Toda vez que o Ubuntu lança versão nova, a atualização é um risco real de quebrar coisas. Pacotes mudam, configs são sobrescritas, dependências conflitam. Pra um servidor que precisa estar sempre rodando, isso é inaceitável.

Por que não Arch Linux

Eu uso Arch no desktop e gosto. Mas Arch é uma rolling release sem nenhuma garantia de estabilidade. Pra um desktop onde eu posso parar e resolver problemas, ótimo. Pra um servidor headless que roda 49 containers Docker e precisa funcionar depois de cada reboot, não.

Fedora CoreOS vs openSUSE MicroOS

As duas opções modernas pra servidor de containers são Fedora CoreOS e openSUSE MicroOS. As duas são sistemas imutáveis: o root filesystem é read-only, atualizações são atômicas (ou aplicam inteiro ou não aplicam nada), e rollback é instantâneo.

A diferença: Fedora CoreOS usa Ignition (configuração declarativa antes do primeiro boot) e é projetada pra ser provisionada automaticamente. MicroOS usa transactional-update e permite uso interativo normal. Pra um home server onde eu quero SSH e mexer manualmente quando precisar, MicroOS se encaixa melhor.

O que torna MicroOS diferente

O conceito de sistema imutável muda como você opera o servidor:

Toda instalação de pacote ou edição de /etc passa por transactional-update, que cria um snapshot btrfs novo, aplica a mudança nesse snapshot, e no reboot seguinte o sistema boota no snapshot atualizado. Se a mudança quebrar alguma coisa, você faz transactional-update rollback e volta pro snapshot anterior em segundos.

Atualizações são automáticas e diárias. O transactional-update.timer baixa patches, cria snapshot, e o rebootmgr reinicia numa janela configurada (no meu caso, entre 4h e 5h30 da manhã). Se a atualização quebra o boot, o GRUB automaticamente volta pro snapshot anterior.

SELinux vem enforcing por padrão. Isso causou 90% dos problemas durante a migração, mas é a configuração certa pra segurança.

Setup inicial

Hardware

• AMD Ryzen AI Max+ 395, 128GB LPDDR5X
• 96GB alocados como VRAM via BIOS (UMA Frame Buffer Size)
• NVMe de 2TB (sistema + Docker)
• Rede cabeada 2.5Gbps
• Synology DS1821+ NAS em 192.168.0.21 (NFS)

Primeiros passos

Instalação do MicroOS é padrão. Depois:

# Criar usuário com UID que bate com o NAS (pra NFS funcionar sem problemas de permissão)
useradd -u 1026 -m akitaonrails
passwd akitaonrails

# Configurar sudo (dentro de transactional-update shell)
sudo transactional-update shell
# dentro: adicionar akitaonrails ao sudoers
exit
sudo reboot

NFS do Synology

O NAS Synology exporta /volume1/TERACHAD via NFS. O ponto de montagem no MicroOS é /var/mnt/terachad (não /mnt/, que fica no root imutável).

No /etc/fstab (aplicado via transactional-update):

192.168.0.21:/volume1/TERACHAD /var/mnt/terachad nfs4 nfsvers=4.1,rsize=262144,wsize=262144,hard,_netdev 0 0

Detalhes que importam: nfsvers=4.1 porque 4.2 não funcionou com o Synology. rsize=262144,wsize=262144 (256KB buffers) foi a maior melhoria de performance NFS. hard em vez de nofail pra que o mount retente indefinidamente se o NAS desconectar temporariamente.

GPU / ROCm

Esse passo deu trabalho. O Radeon 8060S do AI Max+ 395 é gfx1151, que o ROCm não suporta oficialmente. Foram necessários três passos, e os três são obrigatórios:

1. BIOS: setar UMA Frame Buffer Size pra 96GB
2. Kernel: adicionar amdttm.pages_limit=25165824 amdttm.page_pool_size=25165824 em /etc/kernel/cmdline
3. Docker: usar HSA_OVERRIDE_GFX_VERSION=11.5.1 em todo container ROCm

Sem o passo 2, o ROCm só vê 15.5GB mesmo com a alocação do BIOS. Os números são 96GB / 4KB (page size) = 25.165.824 pages.

sudo transactional-update shell
echo "amdttm.pages_limit=25165824 amdttm.page_pool_size=25165824" >> /etc/kernel/cmdline
exit
sudo sdbootutil update-all-entries  # FORA do transactional shell
sudo reboot

Verificação:

cat /sys/class/drm/card1/device/mem_info_vram_total
# 103079215104 (96 * 1024^3)

Docker no MicroOS

sudo transactional-update --non-interactive pkg install docker
sudo reboot

sudo systemctl enable --now docker
sudo usermod -aG docker akitaonrails
# logout e login pra o grupo pegar

# Instalar docker-compose standalone (o pacote openSUSE não inclui)
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64" \
  -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
mkdir -p ~/.docker/cli-plugins
ln -s /usr/local/bin/docker-compose ~/.docker/cli-plugins/docker-compose

daemon.json

{
  "log-level": "warn",
  "log-driver": "local",
  "log-opts": {"max-size": "10m", "max-file": "5"},
  "selinux-enabled": true,
  "live-restore": true,
  "userland-proxy": false,
  "exec-opts": ["native.cgroupdriver=systemd"]
}

live-restore: true faz containers sobreviverem restart do daemon Docker. userland-proxy: false usa iptables direto em vez de processos proxy (menos overhead). selinux-enabled: true é obrigatório no MicroOS.

SELinux e Docker: a maior fonte de problemas

Isso merece uma seção inteira porque foi responsável por 90% dos bugs durante a migração.

No MicroOS com SELinux enforcing, todo container que escreve em diretório bind-mounted do host precisa de tratamento especial. Existem duas abordagens: o sufixo :Z nos volumes e a opção security_opt: label:disable.

NUNCA use :Z. Use security_opt: label:disable.

O :Z diz pro Docker relabeling o diretório do host com o contexto SELinux do container. Parece a coisa certa. Na prática:

• Bancos SQLite quebram. O relabeling muda o contexto do arquivo e o SQLite pode recusar abrir o WAL journal.
• Mounts NFS ignoram :Z silenciosamente. O NFS não suporta xattrs do SELinux. O kernel ignora o flag sem erro, mas o container continua sem permissão.
• Mounts :ro,Z tentam relabeling mesmo sendo read-only, o que falha em NFS e pode corromper contexto em paths locais.

A solução correta pra todo container nesse sistema:

services:
  meuservico:
    security_opt:
      - label:disable     # desliga enforcement SELinux pra esse container
    volumes:
      - ./data:/data      # SEM :Z
      - ./config.yml:/etc/config.yml:ro  # SEM :Z mesmo em :ro

label:disable desliga enforcement de labels SELinux apenas pra aquele container, não pro sistema inteiro. Combinado com o isolamento de rede e processos do Docker, é seguro pra home server.

A migração dos stacks

Todos os stacks Docker foram reorganizados em /var/opt/docker/<stack>/docker-compose.yml. No servidor antigo, estavam espalhados em /home/akitaonrails/docker/, /home/akitaonrails/<servico>/, sem padrão.

Substituições aplicadas em todos os compose files

Stack de media (Plex, Radarr, Sonarr, etc.)

O stack de media é o mais complexo. Plex precisa de IP próprio na LAN (macvlan) pro streaming direto funcionar. O setup:

docker network create -d macvlan \
  --subnet=192.168.0.0/24 \
  --gateway=192.168.0.1 \
  -o parent=enp97s0 \
  plex_macvlan

No compose, o Plex precisa estar em duas redes: a macvlan (pro IP 192.168.0.6) e a bridge default (pra outros containers como Seerr conseguirem se comunicar):

plex:
  networks:
    plex_macvlan:
      ipv4_address: 192.168.0.6
      mac_address: "02:42:c0:a8:00:06"
    default: {}    # obrigatório — sem isso, Seerr não enxerga o Plex

Detalhe que quase me quebrou: o Plex guarda paths absolutos no banco de dados. Se o volume interno do container mudou de /media pra /data, o Plex não encontra mais nada. Tem que usar exatamente o mesmo mount target do compose antigo.

Ollama com ROCm

Stack novo, não existia no servidor anterior:

ollama:
  image: ollama/ollama:rocm
  container_name: ollama
  devices:
    - /dev/kfd:/dev/kfd
    - /dev/dri:/dev/dri
  security_opt:
    - seccomp:unconfined
    - label:disable
  group_add:
    - "485"   # render group GID
    - "488"   # video group GID
  environment:
    - HSA_OVERRIDE_GFX_VERSION=11.5.1
    - PYTORCH_ROCM_ARCH=gfx1151
    - OLLAMA_KEEP_ALIVE=30m
    - OLLAMA_NUM_PARALLEL=4
    - OLLAMA_FLASH_ATTENTION=1
    - OLLAMA_KV_CACHE_TYPE=q8_0
  volumes:
    - /var/lib/ollama:/root/.ollama
  ports:
    - "11434:11434"

OLLAMA_FLASH_ATTENTION=1 ativa flash attention. OLLAMA_KV_CACHE_TYPE=q8_0 usa KV cache em 8-bit, cortando bandwidth necessária por token pela metade. São otimizações de performance gratuitas.

Monitoramento (Grafana + Prometheus)

O Grafana usa named volume (grafana_data) que NÃO é incluído em backups normais de filesystem. Foi o motivo pelo qual perdi todos os dashboards na primeira tentativa. A solução é backup explícito do named volume:

# No servidor antigo:
docker run --rm -v grafana_data:/data:ro -v /tmp:/backup alpine \
  tar czf /backup/grafana_data.tar.gz -C /data .

# Transferir e restaurar no novo:
docker run --rm -v grafana_data:/data -v /tmp:/backup alpine \
  sh -c "cd /data && tar xzf /backup/grafana_data.tar.gz"

Mesma coisa pro Portainer (portainer_data). Qualquer volume definido no bloco volumes: do compose sem host path precisa desse tratamento.

Cloudflare Tunnel

Eu uso Cloudflare Tunnel pra acessar todos os serviços fora de casa sem abrir portas no roteador. A migração foi a mais fácil: copiar o arquivo de credenciais JSON do túnel e o config.yml, atualizar os IPs de .145 pra .90, e subir o container. O túnel mantém o mesmo ID, não precisa recriar DNS.

Os hostnames ficam em config.yml: portainer, grafana, plex, seerr, qbittorrent, syncthing, radarr, sonarr, bazarr, prowlarr, vault, gitea, kavita, e outros. Tudo acessível via https://<servico>.example.com de qualquer lugar.

Gitea (registry de imagens)

O Gitea funciona como registry Docker privado na porta 3007. Os projetos Frank FBI, Frank Mega, Frank Yomik e Mila têm imagens Docker que são buildadas e pushadas pro Gitea. Pra funcionar, o daemon.json do Docker precisa de:

{
  "insecure-registries": ["192.168.0.90:3007"]
}

O SSH do Gitea deu problema na migração: o app.ini antigo tinha SSH_LISTEN_PORT=22, mas o entrypoint do container também inicia sshd na porta 22. Conflito. Solução: GITEA__server__SSH_LISTEN_PORT=2222 como variável de ambiente no compose.

Todos os 49 containers rodando

O servidor migrado roda 49 containers em 15 stacks. O stack de media sozinho tem 10 containers (Plex, Radarr, Sonarr, Bazarr, Prowlarr, qBittorrent, SABnzbd, Jackett, FlareSolverr, Seerr). Os projetos pessoais (Frank FBI, Frank Mega, Frank Yomik, Mila) somam mais 11. Monitoramento com Grafana, Prometheus, node-exporter e cAdvisor. Utilitários como Portainer, Vaultwarden, Syncthing, Organizr, Watchtower. Gitea como registry Docker privado. Immich como Google Photos self-hosted. Kaizoku pra manga com Kavita como reader. Ollama com ROCm. E o Bitcoin Core/Fulcrum indexando a blockchain do NAS.

Backups: duas camadas

Camada 1: snapshots btrfs locais (snapper)

O /var vive numa partição btrfs de 3.7TB. O snapper cria snapshots automáticos: 7 diários + 1 semanal. São crash-consistent, não application-consistent (postgres pode ficar levemente inconsistente se tiver write pesado no momento do snapshot).

Pra recuperar um arquivo apagado acidentalmente:

sudo snapper -c var list
sudo cp /var/.snapshots/5/snapshot/opt/docker/media/radarr/appdata/config/radarr.db \
        /var/opt/docker/media/radarr/appdata/config/radarr.db

Pra rollback completo de um stack:

sudo docker compose -p media down
sudo snapper -c var undochange 7..0 /var/opt/docker/media
sudo docker compose -p media up -d

Camada 2: restic pro NAS (off-machine)

O restic roda toda noite às 3h, faz backup incremental pra /var/mnt/terachad/homelab-backups/. Retenção: 7 diários + 4 semanais. Deduplicação por conteúdo, então Plex config (19GB) e Gitea repos (12GB) transferem apenas deltas.

Antes do restic rodar, um pg_dump exporta os bancos postgres (Immich, Kaizoku). Os dumps vão pra /tmp/homelab-db-dumps/ e são incluídos no backup.

O que NÃO é incluído no backup (re-downloadável): blockchain Bitcoin (785GB no NAS), imagens Docker (re-pullable), modelos Ollama (re-downloadable), cache do HuggingFace/EasyOCR, transcoding temporário do Plex.

Diretórios grandes e re-downloadáveis foram convertidos em subvolumes btrfs pra que o snapper os ignore: /var/lib/ollama e /var/opt/docker/bitcoin/fulcrum/fulc2_db.

Tuning de performance

btrfs com compressão zstd

Adicionei compress=zstd:1 no fstab pra partição /var. O zstd nível 1 tem overhead de CPU quase zero em NVMe e comprime bem metadata Docker, JSON configs e logs. Dados incompressíveis (SQLite, postgres) são ignorados automaticamente pelo btrfs.

zram swap

Com ~30GB de RAM disponível pro sistema (96GB vão pra VRAM), swap comprimido em memória ajuda. O zram cria um dispositivo de swap de ~15GB (ram/2) com compressão zstd, muito mais rápido que swap em disco.

# /etc/systemd/zram-generator.conf
[zram0]
zram-size = ram / 2
compression-algorithm = zstd
swap-priority = 100

btrfs nodatacow em diretórios de banco de dados

Copy-on-write + escrita aleatória de banco de dados = write amplification. Desabilitei CoW nos diretórios que guardam SQLite e postgres:

sudo chattr +C /var/opt/docker/gitea/data/gitea.db
sudo chattr +C /var/opt/docker/immich/db/
sudo chattr +C /var/opt/docker/media/radarr/appdata/config/

CPU em modo performance

Num servidor headless, não faz sentido economizar energia:

echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/energy_performance_preference

Persistido via systemd service cpu-epp.service.

Docker shutdown fix

Problema que descobri: o Docker vem com KillMode=process, que significa que no shutdown do sistema, o systemd mata só o dockerd e deixa todos os containerd-shim (um por container, ~49 no meu caso) órfãos. O systemd-shutdown precisa caçar eles um a um depois que o journal já parou, causando um hang silencioso de vários minutos.

Fix:

# /etc/systemd/system/docker.service.d/shutdown.conf
[Service]
KillMode=control-group
TimeoutStopSec=30

Os problemas que encontramos

Essa é a tabela de problemas reais que tivemos durante a migração. Se você está planejando algo parecido, leia antes de começar:

O que dizer pro Claude Code antes de começar

Se eu fosse refazer a migração do zero, daria estas instruções pro Claude Code na primeira mensagem. Na ordem de importância:

Diga que SELinux está enforcing e que ele NÃO deve usar :Z em nenhum volume Docker, e sim security_opt: label:disable em todo serviço. Diga que /var/mnt/terachad/ é mount NFS e que :Z nunca deve aparecer em paths NFS. Diga pra sempre olhar o compose original antes de reescrever e só mudar IPs, paths e nomes de container, sem inventar novos layouts de volume. Avise que named volumes precisam de backup explícito (Grafana, Portainer). Explique que Plex roda em macvlan e precisa de default: {} nas networks. Informe que a GPU é gfx1151, não suportada oficialmente, e que precisa de UMA 96GB no BIOS + kernel TTM params + HSA_OVERRIDE_GFX_VERSION=11.5.1. E diga que Bitcoin/Fulcrum não processam variáveis de ambiente, tudo vai como argumento no command:.

Essas instruções teriam evitado 80% dos problemas que encontramos.

Layout final do servidor

/var/opt/docker/
├── bitcoin/          (bitcoind + fulcrum)
├── cloudflared/      (túnel Cloudflare)
├── frank_fbi/        (análise de fraude por email)
├── frank_mega/       (clone do Mega)
├── frank_yomik/      (tradução de mangás)
├── gitea/            (registry Docker)
├── immich/           (Google Photos self-hosted)
├── kaizoku/          (manga downloader + reader)
├── media/            (Plex + *arr stack)
├── mila/             (bot Discord)
├── monitor/          (Grafana + Prometheus)
├── ollama/           (LLM local com ROCm)
├── rip/              (HandBrake)
└── utils/            (Portainer, Vaultwarden, Syncthing, etc.)

/var/mnt/terachad/    (NFS do Synology)
├── Bitcoin/data/     (blockchain, 785GB)
├── Downloads/        (torrents + nzbget)
├── Videos/           (Radarr movies + Sonarr series)
└── Ollama/models/    (overflow de modelos se disco local encher)

Aviso sobre usar IA pra administrar servidor

Eu usei Claude Code pra acelerar a migração. Criou compose files, escreveu scripts de backup, configurou firewall, diagnosticou problemas de SELinux. Funcionou bem pro meu caso: home server, só eu uso, e eu estava revisando cada passo.

Mas tem armadilhas. O Claude não sabe que :Z quebra SQLite a menos que você diga. Ele não sabe que o Fulcrum não aceita env vars a menos que já tenha visto o Dockerfile. Ele vai inventar layouts de volume “melhores” que quebram o Plex porque o Plex guarda paths absolutos no banco de dados.

Se fosse produção real: não faça isso sem review. Cada compose file que o Claude gerar, leia inteiro antes de aplicar. Cada comando destrutivo (rollback, delete, recreate), confirme manualmente. E tenha backups testados antes de começar. O Claude é bom pra gerar a primeira versão e diagnosticar erros, mas as decisões de arquitetura e as validações de segurança são suas.

Os posts anteriores sobre o home server que podem dar contexto adicional:

• Meu “Netflix Pessoal” com Docker Compose
• Acessando meu Home Server com domínio de verdade
• Protegendo seu Home Server com Cloudflare Zero Trust
• Instalando Grafana no meu Home Server
• Vaultwarden self-hosted

Mais importante: ter uma senha forte, aleatória, exclusiva e diferente para CADA site, app ou serviço que usa. Nunca, jamais, reusar uma senha. Por que? Porque todo dia um desses sites é invadido e as senhas são vazadas. Se você procurar por você mesmo no site Have I Been Pwned certamente vai achar contas suas que já vazaram. E se você compartilha essa mesma senha com 10 outros sites, alguém já deve ter entrado na sua conta a essa altura.

Assista meu video sobre segurança:

Ter preguiça de usar um gerenciador de senhas é só uma desculpa idiota de gente preguiçosa. E um programador sequer tem direito de usar essa desculpa.

Omarchy 1Password

Quem acompanha o DHH desde os primórdios de quando Macs eram a melhor plataforma pra desenvolvedores, lembra que ele sempre foi fã do 1Password, um dos que funcionava melhor em iPhones.

Eu migrei de volta pra Android e Linux muitos anos atrás, em 2015. Eu usava 1Password, mas em Android o app era tenebroso de feio de ruim de usar. Por isso desisti dele e fiquei migrando entre vários outros apps. Seja Google Authenticator, seja Lastpass (que não recomendo).

Sei que tem diversos outros open source que as pessoas preferem, mas eu acabei caindo no Bitwarden, que é BONITO tanto em Android como a extension pra navegadores. Além disso ele tem componentes abertos e permite self-hosting.

Mais do que isso, ele não dificulta que você exporte todos os dados da sua conta e importe em outro lugar. Diferente de apps como o Twilio Authy, que te bloqueia de tudo e por isso deixei de usar.

Bitwarden tem gerador seguro de senhas aleatórias, tem suporte a 2FA TOTP, dá pra armazenar anotações (tipo mini textos) seguras e muito mais. Os apps integram com biometria do celular, então é bem conveniente de usar.

Ainda mantenho meu Bitwarden dentro do Secure Vault da Samsung, o Samsung Knox Vault. Então são 2 níveis de segurança. E quando preciso andar em algum lugar suspeito, não levo meu celular principal, só um burner-phone sem nada de importante logado.

Olhem como é bonito. Eu gosto dele e uso já faz alguns anos. Minhas senhas variam entre 21 a 42 caracteres aleatórios, um diferente pra cada site. Eu atualizei todas as senhas de tudo mais de uma vez nos últimos anos, e todas as contas tem 2FA/TOTP cadastrado no Bitwarden também, assim consegui sair do Authy.

Instalando VaultWarden Self-Hosted

Mais importante, chegou a hora de hostear meu próprio servidor de Bitwarden, o vaultwarden que é uma alternativa open source, código aberto no GitHub, então você mesmo pode fuçar pra aprender ou até contribuir com ele. Novamente, subo tudo com Docker Compose no meu Home Server, então só precisei adicionar este trecho no meu arquivo:

  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://bitwarden.fabioakita.dev"
      SIGNUPS_ALLOWED: "false"          # set to true only to create first user
      WEBSOCKET_ENABLED: "true"
      ADMIN_TOKEN: "iA...Q9"  # for /admin
      # SMTP (recommended)
      SMTP_HOST: "smtp.gmail.com"
      SMTP_PORT: "587"
      SMTP_SECURITY: "starttls"
      SMTP_USERNAME: "boss@akitaonrails.com"
      SMTP_PASSWORD: "xxx"
      SMTP_FROM: "boss@akitaonrails.com"
    volumes:
      - /home/akitaonrails/vaultwarden/data:/data
    ports:
      - "9999:80"
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "-", "http://localhost/health"]
      interval: 30s
      timeout: 5s
      retries: 5

Importante:

• Crie um ADMIN_TOKEN longo e aleatório. Use o próprio Bitwarden pra isso, mantenha secreto.
• Mude SIGNUPS_ALLOWED pra true somente uma vez, entre no site local e crie sua nova conta. Depois mude no arquivo pra false, reinicie o container. Dessa forma ninguém mais poderá criar nenhuma nova conta.
• É recomendado configurar um GMAIL SMTP pra mandar emails de notificações. Pra isso precisa criar uma senha de aplicativo no Google.

Pra criar uma senha exclusivamente pro vaultwarden, acesse Google App Passwords e gere uma nova senha secreta exclusiva:

Ele só vai mostrar essa senha uma única vez. Copie e cole direto no yaml do docker compose. Configurando e-mail bonitinho, toda vez que alguém fizer login, ele manda um e-mail notificando. Isso é bom pra ter certeza que não tem ninguém suspeito mexendo no seu servidor:

Agora só preciso subir o container:

docker compose -f utils-docker-compose.yml up -d

Roteando túnel do Cloudflared

Como já mostrei no post de Cloudflared agora quero poder acessar remotamente, via túnel seguro, usando uma URL pública como https://bitwarden.fabioakita.dev. Pra fazer isso temos que editar aquele arquivo /etc/cloudflared/config.yml e adicionar no final dele assim:

  - hostname: bitwarden.fabioakita.dev
    service: http://192.168.0.200:9999
    originRequest:
      httpHostHeader: bitwarden.fabioakita.dev
      http2Origin: true
  - service: http_status:404

Depois temos que reiniciar o serviço e também adicionar a rota manualmente:

sudo cloudflared tunnel route dns homelab bitwarden.fabioakita.dev
sudo systemctl restart cloudflared

E pronto! Talvez demore até 5 minutos pros DNS sincronizarem e tudo mais, mas daí é só entrar no seu navegador e vai ver isto:

Se aquele SIGNUPS_ALLOWED estiver true também vai ter um link pra “Criar nova conta”. No meu caso eu já fiz isso e desliquei, então só tem login mesmo.

Importando seus Dados

Antes de continuar, vamos abrir a extension do Bitwarden - que continua logado na versão cloud em bitwarden.com e exportar todos os meus dados:

Basta se autenticar, daí na barra inferior de ícones vai ter “Settings”, depois “Vault Options” e, finalmente “Export vault”. Deixe o padrão no formato JSON mesmo (vai ser um JSON encriptado) e faça download desse arquivo pra algum lugar seguro.

Agora podemos logar de volta na nossa versão self-hosted em https://bitwarden.fabioakita.dev e seguir pelo mesmo menu, mas escolher “Import”:

E pronto! Agora minha versão self-hosted está idêntica à versão cloud que vinha usando até agora.

Logando no novo servidor self-hosted

Agora basta deslogar tanto do App mobile quanto da extension do navegador. Daí na tela de login vai ter a seguinte opção:

Na extension web a janela não deixa ver essa opção, use o scroll do mouse e scrole até o fim da janela e vai ter essa opção pequena. Escolha “self-hosted” e vai abrir uma janela pra digitar a URL https://bitwarden.fabioakita.dev e pronto!

A partir daqui o uso é exatamente o mesmo de antes. A interface é a mesma, as opções são as mesmas. Configure biometria, PIN, timeout pra lock e tudo mais pra deixar do jeito que você gosta.

Faça a mesma coisa no app mobile e pronto!

Nessa nova conta que criamos no servidor self-hosted, não esqueça de habilitar 2FA também, que é a opção “Authenticator App” em “Settings/Security”:

Pra todas as outras contas, podemos registrar o 2FA dentro do Bitwarden. Mas pra conta master do próprio Bitwarden/Vaultwarden, precisamos usar um segundo app só pra isso.

Não sei se é o melhor, mas eu tenho gostado de usar o Aegis Authenticator no meu Android:

É open source, o código está no GitHub, então parece minimamente confiável. Também deixo ele dentro do Samsung Knox Vault. Só preciso dele quando preciso re-logar no Bitwarden/Vaultwarden. Pra logar nos Google, Steam ou qualquer outra conta, o 2FA de cada uma está dentro do Vaultwarden mesmo:

Conclusão

Agora só faltou mesmo me logar com minha conta antiga em bitwarden.com, que é a versão “oficial” no cloud e deletar minha conta, pra garantir que ninguém mais tenha acesso.

E pronto, PERMANENTEMENTE APAGADO! Não existe mais minhas contas num servidor qualquer que eu não controlo, mesmo que fosse encriptado.

Estou bem contente com esta solução. Agora meu Vaultwarden está num container, os dados do home server tem backup automático pro meu NAS, tudo é encriptado e só tem acesso via túnel seguro da Cloudflare. O risco é bem baixo e ninguém tem chance de ter acesso aos meus dados, porque eles não estão mais no “cloud”.

Meus dados são somente meus.

Fiquei com preguiça de instalar Grafana na época, mas resolvi fazer isso agora, e foi bem mais fácil do que eu esperava, por isso resolvi compartilhar como fiz.

A idéia é subir cAdvisor que faz monitoramento de recursos de containers e Prometheus que faz scraping de dados de recursos do sistema e consolidar os dados dos dois no Grafana que é uma aplicação web que permite montar dashboards gráficos pra monitorar seus sistemas. Se fizer direito, no final vai ter uma tela assim:

Instalação

Pra subir no meu home server é muito simples, eu faço tudo com Docker Compose, então:

# monitor-docker-compose.yml
networks:
  monitoring:
    driver: bridge

volumes:
  prometheus_data:
  grafana_data:

services:
  node-exporter:
    image: quay.io/prometheus/node-exporter:latest
    command:
      - --path.rootfs=/host
    pid: host
    restart: unless-stopped
    networks: [monitoring]
    volumes:
      - /:/host:ro,rslave
    security_opt: ["no-new-privileges:true"]
    read_only: true

  cadvisor:
    image: gcr.io/cadvisor/cadvisor:latest
    restart: unless-stopped
    networks: [monitoring]
    ports: ["8080:8080"]   # optional: expose UI locally
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    security_opt: ["no-new-privileges:true"]
    read_only: true

  prometheus:
    image: prom/prometheus:latest
    restart: unless-stopped
    networks: [monitoring]
    volumes:
      - prometheus_data:/prometheus
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.path=/prometheus
      - --storage.tsdb.retention.time=30d
      - --web.enable-lifecycle
    ports: ["9090:9090"]
    security_opt: ["no-new-privileges:true"]
    read_only: true

  grafana:
    image: grafana/grafana:latest
    restart: unless-stopped
    networks: [monitoring]
    depends_on: [prometheus]
    ports: ["3001:3000"]
    environment:
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: change-me
      GF_USERS_ALLOW_SIGN_UP: "false"
    volumes:
      - grafana_data:/var/lib/grafana
      - ./provisioning/datasources:/etc/grafana/provisioning/datasources:ro
    security_opt: ["no-new-privileges:true"]

Tem que prestar atenção nos mapeamentos de diretório local. Se colocar /etc/grafana/prometheus.yml por exemplo, tem que mudar esta linha:

...
    volumes:
      - prometheus_data:/prometheus
      - /etc/grafana/prometheus.yml:/etc/prometheus/prometheus.yml:ro
...

Falando nele, eis o prometheus.yml:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'prometheus'
    static_configs: [{ targets: ['prometheus:9090'] }]

  - job_name: 'node'
    static_configs: [{ targets: ['node-exporter:9100'] }]

  - job_name: 'cadvisor'
    static_configs: [{ targets: ['cadvisor:8080'] }]

Finalmente /etc/grafana/provisioning/datasources/datasource.yaml:

apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true

Cuidado também com mapeamento de portas, o recomendado é fazer assim:

ports: ["127.0.0.1:8080:8080"]

Isso porque cAdvisor e Prometheus só precisam estar acessíveis pro Grafana, dentro do home server, mas não tem porque dar bind em 0.0.0.0 e estar acessível pra fora do servidor. Aí é mais uma escolha. Como eu estou numa LAN caseira, e não tem túneis apontando pra esses serviços, pra mim tanto faz.

Se por acaso, como eu, também já tiver algum serviço pendurado na porta 8080, o cAdvisor vai falhar. Nesse caso remapeie as portas e reconfigure o Prometheus, ou só tire a linha de porta. Não precisa ter o cAdvisor exposto pra fora.

Outro detalhe é que por padrão Grafana sobe na porta 3000 mas eu mudei pra 3001 porque já tinha outro serviço nessa porta. Então, quando subir, eu posso acessar via http://192.168.0.200:3001.

Como expliquei no artigo de Cloudflared eu roteio esse endereço pro Cloudflare pra ter um domínio bonito como https://grafana.fabioakita.dev pra acessar tanto localmente quanto remotamente, se quiser. Depois leiam esses outros artigos pra entender como.

E pronto, agora é só subir os containers:

docker compose -f monitor-docker-compose.yml up -d

E acabou, super simples, eu deveria ter feito isso antes.

Como podem ver arquivo de Docker Compose, quando entrar no site pela primeira vez, o login vai ser com admin senha change-me, obviamente, a primeira coisa a fazer é trocar a senha:

Dashboards

Agora praticamente acabou. Podemos checar se o Prometheus está funcionando e integrado. Basta ir no menu “Connections” e “Data Sources”:

Grafana consegue consolidar dados de dezenas de fontes diferentes, Prometheus é só um deles. Em uma infra maior e mais complicada, essa lista estaria enorme.

Pra montar Dashboards, dá pra ir do zero e montar manualmente widget a widget, mas é mais fácil importar dashboards que já existem. Pra isso é só clicar na lupa lá no topo, na caixa de procura e escolher a opção “Import dashboards”:

Nessa página dá pra ou importar um arquivo JSON, ou copiar e colocar o JSON ou pesquisar pelo ID que já existe cadastrado no site grafana.com:

De cara, eu aprendi que existem 3 IDs que são úteis pra mim:

• 1860 - Node Exporter Full - que é a foto de tela que está no começo deste artigo e tem várias métricas do sistema como CPU, memória, disco, rede, etc. É o mais útil pra mim.
• 13484 - Docker/cAdvisor Exporter - que são as métricas de CPU, memória, mas dividido por cada container rodando no servidor.
• 3662 - Prometheus 2.0 overview - que é um resumo geral de saúde

Se gostar desses ou de outros dashboard, depois é só favoritar com um “pin” e pronto.

Por exemplo, este é o dashboard do cAdvisor:

Eu ainda não explorei outros dashboards. Se tiver recomendações de IDs pra dar import, não deixe de mandar nos comentários abaixo!

Com isso eu tenho uma visão rápida e bonita do uso de recursos do meu home server e consigo ver rapidamente se tem algo de estranho acontecendo. Não parece que esses serviços consumam muitos recursos então posso deixar rodando junto com os demais containers.

Eu tenho um bom Synology DS1821+ que também tem suporte pra rodar Docker, mas eu prefiro deixar o NAS somente pra funções de NAS e não arriscar comprometer meus dados com outras coisas rodando nele. Não é um “problema” ter um servidor só que faz tudo, mas já que eu posso, prefiro separar as coisas.

Esse Intel NUC roda um Ubuntu Server LTS headless (sem desktop manager), que eu uso só acessando via SSH (como expliquei no post anterior sobre SSH). Nele rodo coisas como Portainer, Plex, Sonarr, Bazarr, qBitTorrent e muito mais.

Da forma como está eu só adicionei uma entrada no /etc/hosts do meu desktop assim:

192.168.0.100 synology.lan
192.168.0.200 plex.lan

A partir de agora todos os meus domínios e endereços IPs vão ser falsos, obviamente.

Enfim, dessa forma eu posso abrir meu navegador e entrar em http://plex.lan:32400 pra acessar meu Plex, por exemplo. Mas isso tem três desvantagens:

1. Só no meu desktop consigo usar esses hostnames, do meu notebook precisaria editar o arquivo hosts também. Além disso preciso saber as portas pra cada container.
2. Não tenho SSL pra nada, então toda autenticação vai em texto aberto. Não é um problema muito grande porque o tráfego é somente interno na minha LAN local. Não tenho acessado de fora de casa.
3. Se por acaso eu quiser acessar de fora, nada disso funciona.

Existem dezenas de formas de resolver esse problema, soluções que envolvem WireGuard, ou soluções comerciais como TailScale ou coisas assim. Mas tem uma solução razoavelmente simples que resolve todos os problemas de uma só vez: Cloudflare Tunnels.

A idéia é criar túneis seguros via Cloudflare, pra ter acesso aos meus serviços na minha LAN interna SEM precisar expor portas pra fora do meu roteador ou coisas assim. Minha rede permanece isolada e inalterada.

1. Registrando Domínio

A primeira recomendação é registrar um domínio de verdade. Fazendo isso é possível ter certificados SSL de verdade que a própria Cloudflare gerencia e renova automaticamente.

Eu tenho alguns domínios registrados e não vou revelar qual uso pro meu Home Server. Vou usar esse vazio fabioakita.dev como exemplo só pra este post.

Domínios são baratos, faixa de USD 12 por ano, dependendo do nome que escolher. Escolha um curto e fácil de digitar.

2. Instalando Cloudflared

Com o domínio criado, agora precisamos instalar o serviço cloudflared no Home Server. Ele é quem vai se conectar aos servidores da Cloudflare a abrir o túnel pra dentro do meu servidor local. Clique no link pra instruções de como instalar, mas num Ubuntu Server 22.04 é assim:

# Add cloudflare gpg key
sudo mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null

# Add this repo to your apt repositories
echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared jammy main' | sudo tee /etc/apt/sources.list.d/cloudflared.list

# install cloudflared
sudo apt-get update && sudo apt-get install cloudflared

Agora precisamos fazer login:

# login
sudo cloudflared tunnel login

# adicione tunel homelab
sudo cloudflared tunnel create homelab

# crie diretório pra configurações
sudo mkdir -p /etc/cloudflared

Use as mesmas credenciais que usa pra logar no website da Cloudflare. Se tudo der certo, no final ele vai criar um arquivo em /root/.cloudflared/xxxxx-yyyy-zzzz...json, são suas credenciais, assim como uma chave privada SSH, não jogue num pendrive ou num drive de cloud da vida. Guarde muito bem. Vamos mover:

sudo mv /root/.cloudflared/*.json /etc/cloudflared
sudo chmod 600 /etc/cloudflared/*.json

Finalmente, precisamos criar um arquivo de configurações /etc/cloudflared/config.yml com todos os hostnames que queremos pra cada um dos containers, apontando pras portas corretas. Vou dar um trecho de exemplo da minha config, modificado com IPs falsos e o domínio falso:

# /etc/cloudflared/config.yml
tunnel: homelab
credentials-file: /etc/cloudflared/xxxx-yyyy-....json
ingress:
  ...
  - hostname: plex.fabioakita.dev
    service: http://192.168.0.254:32400
    originRequest:
      httpHostHeader: plex.fabioakita.dev
  - hostname: immich.fabioakita.dev
    service: http://192.168.0.200:2283
    originRequest:
      httpHostHeader: immich.fabioakita.dev
  - hostname: overseer.fabioakita.dev
    service: http://192.168.0.200:5055
    originRequest:
      httpHostHeader: overseer.fabioakita.dev
  - hostname: syncthing.fabioakita.dev
    service: http://192.168.0.200:8384
    originRequest:
      httpHostHeader: qbittorrent.fabioakita.dev
  - hostname: radarr.fabioakita.dev
    service: http://192.168.0.200:7878
    originRequest:
      httpHostHeader: radarr.fabioakita.dev
  - hostname: sonarr.fabioakita.dev
    service: http://192.168.0.200:8989
    originRequest:
      httpHostHeader: sonarr.fabioakita.dev
  - hostname: bazarr.fabioakita.dev
    service: http://192.168.0.200:6767
    originRequest:
      httpHostHeader: bazarr.fabioakita.dev
  - hostname: prowlarr.fabioakita.dev
    service: http://192.168.0.200:9696
    originRequest:
      httpHostHeader: prowlarr.fabioakita.dev
  - hostname: portainer.fabioakita.dev
    service: http://192.168.0.200:9000
    originRequest:
      httpHostHeader: portainer.fabioakita.dev
  - hostname: grafana.fabioakita.dev
    service: http://192.168.0.200:3001
    originRequest:
      httpHostHeader: grafana.fabioakita.dev
  - service: http_status:404 # this has to be the LAST ONE

Como podem ver, é um arquivo extremamente simples. Acho que qualquer um consegue entender o que isso faz. Modifique pras suas próprias necessidades.

Depois de salvar o arquivo e voltar pra linha de comando, precisa manualmente rodar este comando pra cada hostname:

sudo cloudflared tunnel route dns homelab plex.fabioakita.dev

Mas isso é muito trabalhoso, com esse tanto de hostname, achei mais fácil criar um script /etc/cloudflared/add.sh assim:

# run only once
TUN=homelab
CONF=/etc/cloudflared/config.yml
grep -E '^[[:space:]]*-[[:space:]]*hostname:' "$CONF" \
| awk '{print $3}' | tr -d '"' | tr -d "'" \
| while read -r h; do
    echo "adding $h"
    sudo cloudflared tunnel route dns "$TUN" "$h"
  done

Agora é só rodar: sudo sh /etc/cloudflared/add.sh, só uma vez! Então garanta que seu arquivo de config está correto antes!

Finalmente, podemos configurar o serviço pra reiniciar sozinho em todo boot:

sudo cloudflared --config /etc/cloudflared/config.yml service install

sudo systemctl enable --now cloudflared

3. Acessando seus serviços via túnel

Se nada deu errado, já acabou! Já pode ir direto pro seu navegador e testar:

Olha só que beleza. Note na barra de URL que digitei https://immich.fabioakita.dev e acessou normalmente. Aliás, se não conhecia o Immich funciona idêntico a um Google Photos, só que sob seu total controle! Tem app pra smartphone e sincroniza bonitinho.

Mais importante, note que está com HTTPS que foi provido pelo Cloudflare pro meu domínio inteiro. Quando fizer login, vai ser via túnel encriptado. E mais do que isso: mesmo se eu estiver via 5G, fora de casa, no meu celular, vou poder acessar minhas fotos usando esse endereço!

Do meu celular vai abrir um túnel seguro pra Cloudflare, e aquele serviço cloudflared no meu home server está também com um túnel seguro aberto pra Cloudflare, daí ele faz uma ponte entre os dois túneis e pronto! Tenho acesso remoto sem abrir meu servidor direto pra internet! O melhor dos dois mundos!

Não se esqueça de configurar todos os seus serviços com senhas fortes (eu gero elas via Bitwarden, mas qualquer um server 1Password, o que for):

4. Bridge pra vlans

Eu não lembro exatamente o motivo, mas só meu container de Plex deu mais trabalho. Isso porque ele usa uma VLAN diferente das demais. Novamente, não lembro porque fiz isso na época, mas está assim:

  plex:
    #image: plexinc/pms-docker:latest
    image: linuxserver/plex:latest
    restart: unless-stopped
    environment:
      - TZ=America/Sao_Paulo
      - PUID=1026
      - PGID=1026
      - VA_DRIVER=IHD
      - PLEX_HW_TRANS_MAX=16
      - PLEX_MEDIA_SERVER_OPTS=--network-host
    volumes:
      - /config:/config
      - /data:/data
      - /transcode:/transcode
      - /Videos:/media
    devices:
      - /dev/dri:/dev/dri
      - /dev/bus/usb:/dev/bus/usb
    healthcheck:
      test: curl --connect-timeout 15 --silent --show-error --fail http://localhost:32400/identity
      interval: 1m00s
      timeout: 15s
      retries: 3
      start_period: 1m00s
    mem_limit: 4g
    cpus: 5.0
    networks:
      plex_macvlan:
        ipv4_address: 192.168.0.254
        mac_address: "xx:xx:xx:xx:xx:xx"

networks:
  plex_macvlan:
    external: true
    name: plex_macvlan

Por causa disso o cloudflared não consegue rotear pra esse container. A forma de consertar isso é criando uma ponte dessa vlan pra minha ethernet.

sudo ip link add macvlan0 link enp3s0 type macvlan mode bridge
sudo ip addr add 192.168.0.200/24 dev macvlan0   # free IP in your LAN
sudo ip link set macvlan0 up

Obviamente, trocar enp3s0 pelo nome correto da sua ethernet. Cheque com ip addr ou ip link por exemplo. Só de rodar os comandos acima, se eu for no navegador e digitar https://plex.fabioakita.dev já deve conseguir acessar. Pra tornar isso permanente, precisamos do systemd:

# /etc/systemd/network/80-macvlan0.netdev
[NetDev]
Name=macvlan0
Kind=macvlan

[MACVLAN]
Mode=bridge

# /etc/systemd/network/80-macvlan0.network
[Match]
Name=macvlan0

[Network]
Address=192.168.0.200/24
Gateway=192.168.0.1
DNS=192.168.0.1

E agora, só reiniciar os serviços:

sudo systemctl restart systemd-networkd
ip addr show macvlan0

O “correto” seria meu Plex estar configurado com network_mode: hostmas, de novo, não lembro porque não estava e não estava a fim de desconfigurar tudo pra descobrir. Caso alguém tenha configurações similares, é assim que bypassa.

Falando em Plex, eu já tinha ouvido falar que tem que tomar cuidado com streaming via cloudflared, não sei se tem limites ou custos extras. Achei este artigo que fala mais sobre isso mas não parei pra ver a fundo. A única coisa que fiz extra, no dashboard da Cloudflare, foi adicionar uma regra pra não fazer CACHING do subdomínio plex, pra evitar custos adicionais.

Conclusão

Como podem ver, é extremamente fácil ter um home server, isolar tudo com Docker e depois expor seus containers via túnel seguro pra acessar remotamente. Nada disso significa segurança instantânea. Garanta que seus containers sempre estejam atualizados usando serviços como Watchtower, garanta que cada serviço tenha senhas fortes aleatórias e únicas - não use a mesma senha pra tudo. Garanta que seu firewall esteja bem configurado e ativo, mesmo numa LAN.

Muitos routers de Wi-Fi modernos permitem criar uma VLAN separada pra Wi-Fi pra visitas. Assim eles podem usar seu Wi-Fi mas não enxergam seus computadores, que vão estar logicamente isoladas em outra VLAN. Cheque a documentação do seu roteador. Eu uso uma TP-Link BE1900 Tri-Band Wi-Fi 7, mas pra maioria das pessoas ela é cara demais e excessiva demais. Pesquise bem. E não adianta ficar me perguntando de outros modelos: eu não testei todos pra saber as diferenças.

Se você viu nomes como Radarr, Sonarr e não sabe o que isso significa, leia o Wiki do Servarr que consolida todas as documentações desses serviços num único lugar. É a infraestrutura que permite você ter sua própria “Netflix Particular”.

Também não perguntem porque eu uso Plex e não Jellyfin. É escolha pessoal, escolha o que é melhor pra você. Eu gosto de Plex, já usei Jellyfin, e não pretendo mudar.

Eu odeio a idéia de pagar assinaturas pra tudo e não ter propriedade de nada. Acho dinheiro jogado fora. Eu prefiro TER as minhas próprias coisas sob MEU CONTROLE. É mais caro, é mais trabalhoso. Conveniência demais significa que você não tem controle de nada e sempre depende dos outros.

Eu odeio depender dos outros.

Mas não precisa usar estes menus. Vamos entender.

Num Arch Linux ou Ubuntu da vida, um amador instalaria ruby ou python fazendo algo assim:

# arch
yay -S ruby python3
# ubuntu
apt install ruby python3

Este é o jeito ERRADO.

Esses comandos vão instalar a versão mais nova de cada linguagens e toda vez que atualizar o sistema com yay -Syu ou apt upgrade, vai puxar as versões mais novas ainda.

Só que se você desenvolve projetos de verdade, não quer que as versões mudem.

A versão do deploy no servidor no cloud e a versão na sua máquina local TEM QUE SER AS MESMAS.

Se está usando Ruby v3.0.7 e Node.js 22.19.0, não pode ficar refém que quando atualizar seu sistema, do nada vai aparecer Ruby 3.4.5 e Node 24.7.0. Tudo vai começar a quebrar e você vai ficar super confuso sem saber porque. Esse é o erro mais primário que um júnior comete.

Pra evitar isso, cada projeto que está trabalhando PRECISA ESTAR TRAVADO EM VERSÕES FIXAS.

O jeito mais fácil de fazer isso em 2025 é usando MISE. Como falei, ele já vem instalado e ativado no Omarchy, mas se estiver usando outra distro basta instalar Mise manualmente:

yay -S mise

# .bashrc
eval $(mise activate bash)

Adapte isso pra ZSH, Fish ou outro shell que estiver usando, leia a documentação

Agora navegue pro diretório do seu projeto, por exemplo:

cd ~/Projects/AkitaOnRails.com

E trave as versões:

mise use ruby@3.2.3
mise use node@14.21.3

Isso vai criar o arquivo .tool-versions que você deve adicionar no git do seu repositório:

❯ cat .tool-versions
ruby 3.2.3
nodejs 14.21.3

❯ git add .tool-versions

E pronto, toda vez que fizer cd pro diretório, o Mise vai ativar exatamente a versão correta pra esse projeto. Veja:

AkitaOnRails.com [ master][$!?⇡][ v24.7.0][💎 v3.2.3]
❯ ruby -v
ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [x86_64-linux]

AkitaOnRails.com [ master][$!?⇡][ v24.7.0][💎 v3.2.3]
❯ which ruby
/home/akitaonrails/.local/share/mise/installs/ruby/3.2.3/bin/ruby

Note que, se estiver usando o prompt Starship como expliquei no post anterior, com um preset como Pure Prompt, ele mostra no prompt as versões de cada linguagem pra que fique fácil de ver se estiver numa versão errada.

No caso, se leu com atenção, já deve ter notado que SIM, ESTOU NA VERSÃO ERRADA do Node.js. Olhem como no prompt ele fala que estou usando Node 24.7.0 mas no arquivo .tool-versions ele pede 14.21.3.

O motivo de estar “missing” é porque esta máquina é recém-instalada, mas o projeto é velho.

Então vamos checar:

AkitaOnRails.com [ master][$!?⇡][ v24.7.0][💎 v3.2.3]
❯ mise list
Tool    Version            Source                                              Requested
go      1.25.0             ~/.config/mise/config.toml                          latest
node    14.21.3 (missing)  /mnt/data/Projects/AkitaOnRails.com/.tool-versions  14.21.3
node    22.18.0
python  3.13.7
ruby    3.2.3              /mnt/data/Projects/AkitaOnRails.com/.tool-versions  3.2.3
ruby    3.4.5

Veja como na listagem de mise list ele fala que 14.21.3 está “missing”. Então vamos instalar:

AkitaOnRails.com [ master][$!?⇡][ v24.7.0][💎 v3.2.3]
❯ mise use node@14.21.3
mise /mnt/data/Projects/AkitaOnRails.com/.tool-versions tools: node@14.21.3

AkitaOnRails.com [ master][$!?⇡][ v14.21.3][💎 v3.2.3]
❯

Com o comando mise use podemos pedir pra instalar e usar uma versão em particular. Se já não estiver instalado, ele vai instalar. Note como depois disso o prompt do Starship mudou pra refletir que agora estamos usando 14.21.3. Esse é o jeito certo.

Se não estiver necessariamente num diretório de projeto com versões travadas, ainda assim é possível rodar comandos usando uma versão específica, assim:

mise exec ruby@3.2.1 -- ruby ...

Digamos que queira gerar um projeto de Rails numa versão específica de Ruby:

mise exec ruby@3.2.3 -- rails new todo-exercise

Mesma coisa vale pra generators em Node, como Next.js ou qualquer outro framework.

Não chequei se o LazyVim no Omarchy já vem configurado assim, mas caso não venha, pro NeoVim suportar Mise precisa adicionar isso:

-- Prepend mise shims to PATH
vim.env.PATH = vim.env.HOME .. "/.local/share/mise/shims:" .. vim.env.PATH

Basta colocar isso em ~/.config/nvim/lua/config/mise.lua que ele deve carregar o path correto. Pra integrar com outros editores, cheque esta documentação. Tem um MONTE de opções avançadas que é bom ler a respeito na seção de Dev-Tools mas o básico é o que listei aqui.

E bancos de dados??

O mesmo vale pra bancos de dados. Cada projeto deve estar travado numa versão específica idêntica à que está rodando no servidor de produção e nunca deve depender dos pacotes do sistema operacional. Dá pra usar mise pra isso mas o mais recomendado é usar Docker. Cada projeto DEVE ter um docker-compose.yml pra subir somente os bancos de dados. Não precisa subir containers pra linguagens, pra isso é melhor usar Mise.

Se não entende Docker, eu fiz videos ensinando:

Somando Mise + Docker Compose + LazyVim, é tudo que se precisa pra ser um desenvolvedor web produtivo, além de usar os recursos da sua máquina de maneira eficiente. Todo desenvolvedor PRECISA aprender este combo de opções. Omarchy já trás tudo pré-instalado, por isso tem sido minha recomendação pra todo iniciante.

Não precisa se preocupar: Arch Linux (com archinstall), é tão fácil de instalar quanto um Ubuntu ou Linux Mint e o Hyprland do Omarchy é muito mais bonito e fluido que um MacOS. O melhor dos mundos. Aprenda hoje!

O Problema

Antes, pra contribuir no blog você precisava:

1. Instalar Hugo Extended
2. Instalar Go
3. Instalar Ruby
4. Configurar todas as dependências
5. Gerar o índice de posts manualmente

Isso criava barreiras pra novos contribuidores e podia causar conflitos com outras instalações no sistema. Um inferno.

A Solução: Docker

Agora você só precisa do Docker e Docker Compose. Tudo o resto roda em containers isolados.

Setup Rápido

# Clone o repositório
git clone https://github.com/akitaonrails/akitaonrails.github.io.git
cd akitaonrails.github.io

# Inicie o ambiente
./scripts/dev.sh start

# Acesse o blog
open http://localhost:1313

Pronto! O blog está rodando e você pode começar a contribuir.

Comandos Úteis

O projeto inclui scripts que facilitam o desenvolvimento:

# Ver todos os comandos disponíveis
./scripts/dev.sh help

# Criar um novo post
./scripts/dev.sh new-post "Título do Meu Post"

# Ver logs do servidor
./scripts/dev.sh logs

# Gerar índice de posts
./scripts/dev.sh generate-index

# Parar o ambiente
./scripts/dev.sh stop

Criando um Post

Criar um novo post é super simples:

./scripts/dev.sh new-post "Como Contribuir no Blog do AkitaOnRails"

O script automaticamente:

• Cria a estrutura de diretórios com a data atual
• Gera um arquivo index.md com front matter básico
• O servidor Hugo recarrega automaticamente

Estrutura de um Post

O arquivo criado terá esta estrutura:

---
title: "Título do Post"
date: "2025-08-29"
draft: false
description: "Descrição do post"
tags: [tag1, tag2]
categories: [categoria]
---

Conteúdo do post aqui...

Vantagens do Docker

Para Contribuidores

• Setup rápido: Apenas Docker necessário
• Ambiente isolado: Não interfere com sistema local
• Hot reload: Mudanças aparecem automaticamente
• Reproduzível: Funciona igual para todos

Para o Projeto

• Menos issues: Ambiente consistente
• Mais contribuidores: Barreira de entrada menor
• Manutenção: Fácil de atualizar dependências

Como Funciona

O ambiente Docker inclui:

• Hugo Extended: Gerador de sites estáticos
• Go: Para módulos Hugo
• Ruby: Para script de geração de índice
• Volumes: Para hot reload dos arquivos

O docker-compose.yml mapeia os diretórios locais para o container, então quando você edita um arquivo, o Hugo detecta a mudança e recarrega automaticamente.

Desenvolvimento Local (Alternativa)

Se preferir não usar Docker, ainda é possível instalar tudo localmente:

# Gerar índice
cd content && ruby generate_index.rb

# Rodar servidor
hugo server --logLevel debug --disableFastRender -p 1313

Mas o Docker é muito mais prático!

Próximos Passos

1. Teste o ambiente: Execute ./scripts/dev.sh start
2. Crie um post: Use ./scripts/dev.sh new-post
3. Explore o código: Veja como personalizar layouts
4. Contribua: Faça um Pull Request

Dica: O ambiente Docker salva automaticamente suas mudanças e recarrega o servidor. Basta editar os arquivos e ver as mudanças em tempo real! 🚀

Mais de ano atrás, quando fiz meus últimos videos sobre I.A. e nos podcasts eu sempre falava que rodava tudo na minha máquina. Mas nunca detahei como. Então hoje consertei isso com vários posts de blog e projetinhos no GitHub com Dockerfiles pra você mesmo rodar na sua própria máquina, sem configurar nada difícil.

Finalmente fiz um Dockerfile pra ComfyUI, que é a melhor interface gráfica pra edição de workflows de geração de imagens. Se você já trabalhou com Davinci Resolve Fusion ou Blender Geometry Nodes da vida, workflows são basicamente configurações de nós pra processar suas imagens, áudio, video e ir passando por processamentos não só de I.A.. É como programar visualmente. Por isso é uma ferramenta muito mais complicada do que o FramePack que mostrei no post anterior. Não é só clicar.

Recentemente todo mundo ficou histérico com as atualizações do ChatGPT e como ele “OH MY GOD” consegue gerar imagens em estilo de anime da Ghibli e ficaram spammando o mundo com memes idiotas em estilo anime. Histeria online é um saco mesmo. Mas como eu falei, por mais impressionante que seja, é isso: um gerador de memes. Não dá pra usar profissionalmente.

Cansei de tentar subir fotos minhas ou até fotos genéricas, de personagens fictícios, alguns até desenhos meus, e vira e mexe, aleatoriamente, o ChatGPT se recusa a gerar a imagem. Alegando privacidade, segurança, copyright e tudo mais que ele conseguir inventar de desculpa. Não dá pra confiar nisso pra trabalhar. Quem é profissional deveria ter controle completo sobre o processo e é isso que vou ensinar hoje.

Pra começar, clone meu repositório no GitHub e siga as instruções do README ou faça isto:

git clone https://github.com/akitaonrails/ComfyUI-Docker-CUDA-preloaded.git
cd ComfyUI-Docker-CUDA-preloaded
docker compose build

Sendo mais complexo, precisei colocar um Docker Compose desta vez. Então pra subir, depois do build finalizar, só fazer isso:

docker compose up

Agora vai demorar, porque por padrão ele vai baixar quase 500GB de modelos pré-treinados pra conseguir fazer quase tudo de imagens. Sim, pra brincar com I.A. localmente precisa ter infra. Ou se não, alugar máquina parruda com muito armazenamento numa RunPod da vida e rodar remoto. Tem como baixar menos modelos, vou explicar a seguir.

No Docker Compose. Recomendo evitar a opção “-d” de subir como daemon, porque é bom reservar um terminal pra ficar vendo os outputs (você pode dar docker compose logs --follow, se quiser também, mas é mais fácil direto).

O ComfyUI é um programa mais complexo que a média, muito mais que um FramePack da vida. Ele tem suporte a instalar “extensions” (plugins, addons, chame como quiser). E na verdade ele sozinho não faz muita coisa, precisa instalar várias extensions pra começar a ficar realmente útil. Vira e mexe alguma dessas extensions não trata erros direito e estoura no console, algo como isso:

É útil sempre ficar de olho no console pra descobrir se ele tentou carregar um arquivo que não existe. Daí dá pra pegar o nome do arquivo e buscar no Google, baixar e colocar no lugar certo. Ou se é uma extension muito bugada que é melhor tirar do diretório “custom_nodes”, e assim por diante. Sem ver o console, não aparece na interface web e você vai ficar a ver navios.

Muito dos modelos e extensions eu me baseei na configuraçãol Ultimate ComfyUI versão 3 recomendada pelo Aitrepreneur, de novo. Assista este video dele pra ter todos os detalhes e tudo que é possível fazer. Ele tem os scripts pra Linux, Windows, e os workflow na versão paga do Patreon dele e, claro, não vou compartilhar os workflows porque não são meus. Em teoria, minha config deve ser capaz de fazer o que ele ensina.

O workflow V3 do Aitrepreneur é muito ph0da. Mas eu não posso compartilhar porque é material fechado no Patreon dele, mas eis uma foto de tela do meu ComfyUI com tudo dele carregado:

Mas a config em si, eu refiz inteira pra funcionar neste Docker. Dá pra carregar qualquer outro workflow aberto que achar num Reddit da vida.

O que eu fiz foi o seguinte:

Models

No projeto tem que ter um diretório “models”, se não tiver crie, porque o docker compose vai mapear pra dentro do container. Quando iniciar, ele vai rodar o arquivo init_models.sh. Esse script vai carregar um arquivo de configuração que você pode editar depois: models.conf. Ele é enorme e um pedaço dele é assim:

...
[CONTROLNET]
https://huggingface.co/XLabs-AI/flux-controlnet-collections/resolve/main/flux-canny-controlnet-v3.safetensors
https://huggingface.co/XLabs-AI/flux-controlnet-collections/resolve/main/flux-depth-controlnet-v3.safetensors
https://huggingface.co/brad-twinkl/controlnet-union-sdxl-1.0-promax/resolve/main/diffusion_pytorch_model.safetensors|controlnet-union-sdxl-1.0-promax.safetensors
https://huggingface.co/lllyasviel/ControlNet-v1-1/resolve/main/control_v11p_sd15_canny.pth
https://huggingface.co/lllyasviel/ControlNet-v1-1/resolve/main/control_v11f1p_sd15_depth.pth
https://huggingface.co/lllyasviel/ControlNet-v1-1/resolve/main/control_v11p_sd15_openpose.pth
https://huggingface.co/Aitrepreneur/FLX/resolve/main/Shakker-LabsFLUX1-dev-ControlNet-Union-Pro.safetensors

[STYLE_MODELS]
https://huggingface.co/Aitrepreneur/FLX/resolve/main/flux1-redux-dev.safetensors

[SAMS]
https://huggingface.co/Aitrepreneur/FLX/resolve/main/sam_vit_b_01ec64.pth

Cada seção mapeia pra um sub-diretório, então “[SAMS]” vai mapear pra “models/sams” e baixar os binários nos lugares certos. Tem alguns especiais nas seções “[GIT_REPOS]”, para os que podem ser clonados via git ou “[CUSTOM]” pra arquivos que precisa baixar depois dentro desses projetos clonados, por exemplo. Não sei ainda se dá pra simplificar, mas isso eu peguei na config do Aitrepreneur.

O ideal é sempre manter essa lista organizada com modelos que acharem depois. Se quiserem contribuir também seria bacana. O motivo é que fica tudo espalhado em tudo que é site por aí, você baixa manualmente, daí move pro diretório dentro de “models”. Amanhã, se reinstalar sua máquina, e pra lembrar todos os sites? São dezenas de modelos disponíveis.

No outro post vou tentar resumir o que diabos são “checkpoints”, “diffusion models”, “loras”, “controlnet” e tudo mais. Mas por enquanto, a extensão dos arquivos não diz muita coisa. Dizer “.pt” por exemplo só quer dizer que é um arquivo que o PyTorch consegue abrir, mas não diz se é um clip ou um text encoder, por exemplo. Extensão “.safetensors” mesma coisa, pode ser qualquer coisa, e o ComfyUI precisa que cada arquivo esteja no sub-diretório correto pra conseguir usar depois, não pode sair movendo arquivo aleatoriamente.

O script “init_models.sh” roda toda vez que o Docker é reiniciado e é inteligente pra só baixar URLs que já não estão baixadas no diretório “models”. Por isso sempre roda quando o container sobe, no entrypoint. Essa é uma das vantagens da minha config: ela é tem manutenção automática.

Extensions e Dependências

Eu fiz um segundo script chamado init_extensions.sh, que também roda no entrypoint do container e você não deve mexer, mas ele carrega um outro arquivo de configuração chamado extensions.conf e, esse sim, você pode mexer e adicionar novas extensions depois. Um pedaço dele é assim:

[EXTENSIONS]
https://github.com/ltdrdata/ComfyUI-Manager.git
https://codeberg.org/Gourieff/comfyui-reactor-node.git
https://github.com/ssitu/ComfyUI_UltimateSDUpscale.git
https://github.com/kijai/ComfyUI-LivePortraitKJ.git
https://github.com/PowerHouseMan/ComfyUI-AdvancedLivePortrait.git
...

Aqui eu declaro todas as extensions que adicionam novas funcionalidades em cima do ComfyUI, em particular novos NODES, por isso ficam no diretório “custom_nodes”, que é um volume externo ao Docker e por isso é persistente, ou seja, toda nova extension sobrevive restarts do container.

Mas tem ainda um porém GRANDE: Dependências de Python. Um pesadelo.

A build da Imagem Docker faz um monte de pip install e como estou usando Virtual ENV, vai tudo instalado em /venv dentro do container, como deveria.

Porém, as extensions que são instaladas fora da build - toda vez que o container reinicia - costumam ser código Python e também tem mais dependências. Extensions são projetos no GitHub e podem estar mudando neste exato momento. Se mudar e fizer um git pull pra atualizar, precisa rodar o pip install -r requirements.txt. Mas se tiver dezenas de extensions, rodar pip install, de cada um, em cada restart do Docker é uma demora grande pra não fazer quase nada. Como eu disse, pesadelo.

Minha solução - pra me gabar um pouco - conserta boa parte dessa manutenção. Quando o script init_extensions.sh executa, se uma extension da lista já estiver instalada, ele vai pular. Daí vai gravar no diretório ./custom_nodes/.last_commit/*.commit o último commit de cada extension. Quando o Docker reiniciar, ele vai dar um git fetch e checar se o hash do último commit mudou.

Só se mudou, ele vai rodar pip install pra essa extension que ganhou atualização e pular todas as outras que não mudaram desde o último restart, economizando MUITO tempo e evitando que você precisa manualmente atualizar as coisas. Como estou usando VENV, vai ficar tudo persistido no volume “/venv”. Sim, é um VOLUME, porque ela muda depois do build a cada atualização de extension.

Dessa forma, tudo que tem na imagem vai ser copiada nesse volume, e tudo que as extensions instalarem por fora, também vai pra dentro desse volume. Toda vez que reiniciar, volta tudo como estava antes. Foi a solução que encontrei e até agora parece funcionar direitinho.

Mas é só questão de tempo pra alguma extension mal feita instalar dependências que quebrem outras dependências, ou um caso real que eu passei: tinha uma extension que crasheia sem mensagem de erro se estiver usando Python 3.11, o Zoe Depth Map da extension comfyui_controlnet_aux, um dos pacotes que parece que são populares.

Eu não tinha me dado conta que comecei usando uma image base de Docker de ubuntu22 em vez de ubuntu24, eu estava com medo de usar algo novo demais e quebrar, mas acabei usando velha demais e quebrou do mesmo jeito. Gerenciar versionamento é um saco. Enfim, mudei o Dockerfile pra ubuntu24.

Mas no volume externo do VENV agora sobrou um monte de dependências que se limitavam ao Python 3.11. Não tem problema, basta apagar o volume:

docker compose down # garantir que está parado
docker volume rm comfyui-venv
rm ./custom_nodes/.last_commits/*.commit

E pronto, o VENV vai reiniciar vazio, preencher com as dependências corretas de Python 3.12 da imagem e ao iniciar o container meu script init_extensions.sh não vai achar o “.last_commits” e vai forçar um pip install -r requirements.txt de todas as extensions, agora com Python 3.12. Super limpo e confiável.

Se mesmo assim tiver erro, aí pode ser bug numa extension em especial, só vá até o diretório dele em “./custom_nodes” e apague manualmente antes de reiniciar o container.

Acho que isso é o menos complicado que dá pra fazer nesse caso. Esse docker não foi feito pra rodar sozinho num servidor, é pra rodar na sua própria máquina local, onde você está monitorando o output do terminal mesmo.

Ah sim, se sair versão nova do ComfyUI aí tem que re-buildar a imagem e apagar o volume de VENV. A imagem é estática, não esqueçam. Dentro o Dockerfile faz um novo git clone e pega o commit mais novo. Daí vai instalar pacotes python mais novos, então precisa zerar o volume da VENV e fazer as extensions re-instalarem suas dependências depois também. É um enorme saco, mas é assim mesmo que funciona.

Conclusão

Feito tudo isso, com um simples docker compose up consigo ter um ambiente de ComfyUI estável e isolado do resto do meu sistema, sem sujar nada com milhares de dependências duvidosas. Quando terminar só fazer docker compose down ou “ctrl-c” no console dele e pronto, meu sistema continua limpo.

Além disso, diretórios como “models” e seus 500GB de modelos ficam separados, dá pra fazer backup pra outro lugar se precisar. E se quiser subir em outra máquina, basta levar somente esses diretórios e subir Docker Compose lá e tem que subir igualzinho, zero-setup. Esse foi meu objetivo ao Dockerzar ComfyUI, FramePack, Video2K, ter tudo portátil, isolado e limpo pra subir em qualquer máquina depois sem precisar ficar rodando scripts duvidosos de instalação direto na minha máquina.

No meu X eu já mostrei meu ComfyUI funcionando. Carreguei um workflow qualquer que achei na Web e olha só:

Nesse workflow eu subo uma imagem de referência e posso escrever um prompt de como quero transformar ela:

Com ComfyUI eu tenho controle sobre todas as etapas do processo, por exemplo, esse workflow consegue separar coisas como Mapa de Profundidade e Contorno de Bordas da imagem original, pra usar de contexto antes de fazer a imagem final, garantindo um resultado muito mais preciso:

E eis um resultado que já consegui usando o modelo “waiNSFIllustrious” que esse workflow sugere, que é um modelo treinado pra gerar imagens estilo anime (tem dezenas, pra vários estilos diferentes).

Mudando o modelo pra Mistoon, baseado em Stable Diffusion (SDXL), eis outro resultado, com o mesmo prompt, no mesmo workflow:

E posso ficar tunando dezenas de parâmetros dentro desse workflow, trocar vaes, text encodes, controlnets e muito mais até conseguir exatamente o resultado que eu quiser. Esse é o poder do ComfyUI e seus Custom Nodes e Workflows. É o que vou tentar explicar o básico no próximo post.

Já que estava no embalo de empacotar esse tipo de ferramenta em Docker, resolvi fazer mais um projetinho com um Dockerfile pra rodar no meu Manjaro Linux com RTX 4090. O bom do Aitrepreneur é que ele tem um Patreon que você pode assinar pra contribuir (é barato) e ele sempre sobe scripts pra rodar no RunPod caso você não tenha uma máquina parruda ou GPU, ou script .BAT pra rodar no seu Windows.

Meu projetinho está neste GitHub e pra usar é muito simples:

git clone https://github.com/akitaonrails/FramePack-Docker-CUDA.git
cd FramePack-Docker-CUDA
mkdir outputs
mkdir hf_download

# Build the image
docker build -t framepack-torch26-cu124:latest .

# Run mapping the directories outside:
docker run -it --rm --gpus all -p 7860:7860 \
  -v ./outputs:/app/outputs \
  -v ./hf_download:/app/hf_download \
  framepack-torch26-cu124:latest

Isso vai construir a imagem de Docker e rodar. E na primeira vez dá pra ver que ele vai baixar uma TONELADA de models, o HunyuanVideo, Flux e mais. Se prepara pra mais de 30GB. Mas é só na primeira vez porque eu mapeio o diretório de download pra fora, então se reiniciar o container ele já vai ter na próxima vez.

Quando terminar, é só acessar http://localhost:7860 e vai ver esta interface super simples:

Os controles são muito simples:

• Desabilite a opção “Use TeaCache” que deixa mais rápido mas aí você arrisca a ter aqueles defeitos de I.A. como mão com mais dedos e coisas assim.
• Total do Video pode ser até 2 minutos, mas só faça isso se realmente tiver paciência porque demora BASTANTE! Acho melhor começar mesmo testando com videos curtos de 5 a 10 segundos primeiro.
• Se sua GPU tiver pouca VRAM vai ser obrigado a mexer em “GPU Inference Preserved Memory (GB) (larger means slower)”. No meu caso que tenho 24GB de VRAM deixei como está, mas olha só rodando como ele consome:

Sim! 100% da GPU e quase 100% da VRAM, puxando mais de 350W da parede! (foda-se meio ambiente! kkkkk) A CPU até fica de boa, porque esse processo é feito pra realmente MASSACRAR a GPU. Se não tiver GPU boa, alugue uma máquina na RunPod como falei antes.

O video de 10 segundos no começo do post é uma foto da uma das action figures que eu mais gosto na minha coleção, o Link de Breath of the Wild. E isso é uma coisa que me deixou empolgado. Esta é a foto original que serviu de base pro FramePack fazer o video:

Fazer video de fotos de pessoas é sem graça e tedioso, mas agora que estou aprendendo a modelar 3D pra imprimir na minha Bambulab, imagina depois ainda conseguir fazer ele ficar animado?

Pra animar no Blender e renderizar, também é bastante processamento e demora. Mas com isso eu consigo rapidamente prototipar uma animação e ver como fica, pra ver se vale a pena fazer uma versão melhor no Blender depois. Abre muitas possibildades de experimentação!

Por mais impressionante que isso pareça, ele não faz QUALQUER COISA, tive várias experimentações que deram errado e a movimentação que ele faz é bem limitada, afinal ele só tem uma foto pra usar de referência e não tem dá pra fazer movimentos bruscos demais, tem limites. Mesmo assim é bem divertido de brincar. O fato dele conseguir identificar mais que seres humanos é um grande “plus” na minha opinião, porque é onde eu me interessei mais.

AH SIM! Lembram o outro blog post que publiquei hoje sobre fazer UPSCALE PRA 4K?? Dá pra usar aqui também, pegue um video que o FramePack gerou e você gostou muito e faça upscale pra 4K pra ter mais definição ainda! Aí fica em qualidade pra até usar em edição de videos.

Videos de 2 minutos deve levar horas pra fazer. 30 segundos levou quase 1 hora. Melhor coisa é ficar em videos de 5 segundos pra brincar e experimentar, só isso já leva aí quase meia hora. Aqui vão mais alguns exemplos tirados de fotos de itens da minha coleção (aqueles que vocês viam no fundo dos meus videos). Divirtam-se!

Este é um Ultraseven de mais de 30cm de altura que eu encontrei e trouxe direto de um sebo de Tóquio ano passado, um dos que eu mais gosto especialmente porque assisti muito no começo dos anos 80 quando eu era criança.

Falando em nostalgia, esse é outro item da hora da minha coleção, um Jiraya super detalhado feito pela Iron Studios. E animado até que ficou bem da hora. O que acharam?

Mas agora o meu FAVORITO, quem me acompanha no Instagram viu que faz algumas semanas que venho me dedicando a melhorar minhas técnicas de 3D e também de desenho e eu fiz um conceito de Mandaloriam + Judge Dredd:

.png?disposition=attachment&locale=en)

Depois vejam os outros desenhos no meu Instagram, mas enfim, eu precisava saber se o FramePack era capaz de animar também desenhos e SIM, ELE CONSEGUE!! OLHA QUE PH0DA!!! Esse me deixou impressionado, dá uma nova dimensão nas minhas coisas!

Sim, tudo isso é bem pesado, mas a vantagem é que eu posso experimentar INFINITAMENTE, porque tudo roda local. Num produto comercial de alguém no “cloud”, eu precisaria pagar alguma assinatura e ele ia me limitar, seria impossível ficar experimentando quando eu quisesse. Agora eu posso fazer tudo que eu quiser, quando eu quiser, como eu quiser, sem que ninguém nem nada possa encher meu s@co.

Aliás, se puderem assistam esse clip do “Boba Dredd” em tela cheia num monitor grande. Notaram que tá bem nítido? É porque eu passei no Video2K e fiz upscale pra 4x a resolução que o FramePack me deu. Juntando essas ferramentas dá pra fazer coisas BEM interessantes, depois me falem se conseguiram usar e o que fizeram de legal!

Pra quem coleciona, o problema é que muito anime dos anos 90 pra trás nunca saíram e nem nunca vão sair em Blu-Ray (1080p) nem UHD (4K). Só os mais famosos recebem tratamento de “remaster” (pegar as fitas master originais e recapturar em mais resolução). Então muito anime velho está preso na era de DVD (480p) ou VHS (480i).

Nem todo anime velho dá pra aumentar resolução, pode ficar “lavado” demais. Quem baixa torrent já deve ter visto upscalings mal feitos. Mas eu queria poder testar isso eu mesmo, na minha máquina local, com meus arquivos velhos. Eis um pequeno clip de exemplo:

É um pedaço do 1o episódio do lendário Rurouni Kenshin de 1996. Sim, hoje temos um remake, que estão refazendo do zero. Mas pra quem tem nostalgia pelo original, não tem substituição. A qualidade de DVD não está horrenda, dá pra assistir de boa ainda hoje assim mesmo. Mas fico curioso pra ver como fica em 4K.

Não fiz nenhuma pesquisa longa, mas um ano atrás eu tinha esbarrado no Real ERSGAN. Esse projeto está descontinuado faz uns 4 anos, então não sei o que é o mais moderno hoje. Mas os modelos pré-treinados deles ainda são úteis.

Ainda tem projetos que usam esse modelo, o que eu conheço é o Video2K Em Windows parece que tem até uma interface gráfica bonitinha, mas a vantagem pra Linux é que ele roda em Docker. Um exemplo seria assim:

docker run --rm --gpus all \
  -v "$PWD/videos_in":/input \
  -v "$PWD/videos_out":/output \
  ghcr.io/k4yt3x/video2x:6.4.0 \
  -i /input/old_anime.mp4 -o /output/old_anime_4K.mkv \
  -p realesrgan -s 4 --realesrgan-model realesr-animevideov3

Se tiver com sua NVIDIA configurada com o Container Toolkit, Cuda e tudo mais (pergunte ao ChatGPT), o Docker consegue mapear o dispositivo direto pra dentro do container. Isso facilita muito não deixar meu Linux sujo cheio de dependências e configuraçõe soltas por aí. Não faço mais nada desse tipo fora de containers.

Mas eu esbarrei com um problema. Se você estiver usando GPU AMD, só assim já deve funcionar, porque essa imagem Docker na verdade usa Vulkan e não CUDA. No meu caso eu tenho uma GPU integrada AMD primária e uma NVIDIA RTX 4090 secundária. Eu tentei passar direto:

❯ docker run --gpus all --privileged \
  --device=/dev/nvidia0 \
  --device=/dev/nvidiactl \
  --device=/dev/nvidia-uvm \
  --device=/dev/nvidia-modeset \
  --runtime=nvidia \
  -e VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/nvidia_icd.json \
  -e VK_LAYER_PATH=/usr/share/vulkan/explicit_layer.d \
  -v "$HOME/Downloads/Video2K/videos_in":/input \
  -v "$HOME/Downloads/Video2K/videos_out":/output \
  --rm -it \
  ghcr.io/k4yt3x/video2x:6.4.0 \
  -i "/input/(B-A)Rurouni_Kenshin_-_01_(A5D3CB57).mkv" \
  -o "/output/(B-A)Rurouni_Kenshin_-_01_(A5D3CB57)_upscaled.mkv" \
  -p realesrgan -s 4 --realesrgan-model realesr-animevideov3

Mas não vai de jeito nenhum. Se eu só disser “–gpus all” ele vai pegar a iGPU por padrão. Fazer o upscaling de um video acaba consumindo 100% da minha CPU, todas as 32 threads, mas minha GPU NVIDIA fica parada olhando sem fazer nada. Se eu tentar passar “/dev/dri/card0” ou “/dev/nvidia0”, ele dá erro e não consegue começar.

Então a partir daqui a solução é só pra quem tem NVIDIA:

Dockerfile CUDA

Desta vez resolvi não ser preguiçoso e organizar tudo no projetinho no Github. Clone direto de lá Batch Anime Upscaler Video2K Docker CUDA Só fazer assim:

git clone git@github.com:akitaonrails/Batch-Anime-Upscaler-Video2K-Docker-CUDA.git
cd Batch-Anime-Upscaler-Video2K-Docker-CUDA
mkdir input # coloque seus videos velhos aqui
mkdir output

docker build --build-arg HOST_UID=$(id -u) --build-arg HOST_GID=$(id -g) -t anime-upscaler:latest .

Se nada der errado, isso vai construir uma imagem de Docker com tudo que você precisa, daí é colocar seus videos no subdiretório que falei, ou outro que quiser e configurar no comando pra rodar:

 docker run --gpus all --rm \
  -v "./input":/input \
  -v "./output":/output \
  -e HOST_UID=$(id -u) -e HOST_GID=$(id -g) \
  anime-upscaler:latest

E é só isso. Demora bastante. Com meu Ryzen 7950X3D mais RTX 4090, ele processa a uma taxa de uns 13 frames por segundo. Então menos da metade da velocidade de playback. Se um video tiver 20 min, vai levar mais de 40 minutos pra processar cada um. É bom reservar um bom tempo, e por isso também é bom só pra videos que você realmente queira assistir.

O script original do Video2K suporta vários parâmetros, que eu deixei expostos como variáveis de ambiente no Dockerfile:

MODEL="${MODEL:-realesr-animevideov3}"
SCALE="${SCALE:-4}"
TILE="${TILE:-0}"
DENOISE="${DENOISE:-1.0}"
NUM_PROC="${NUM_PROC:-1}"

Daí dá pra mudar mexendo assim:

docker run --gpus all --rm \
  -e DENOISE=0.5 \
  -v ... \
  anime-upscaler:latest

Como podem ver, por padrão usamos o modelo pré-treinado “realesr-animevideov3” que é menos detalhado que o modelo de 6 bilhões de parâmetro mas é bem mais estável entre frames, que é mais importante pra um video. A maioria dos outros modelos que ele suporta, como “RealESRGAN_x4plus” ou “ESRGAN_x4” servem pra fotos e imagens mas não pra video. Video exige coerência temporal, que é bem difícil.

No máximo vale testar o modelo “realesr-general-x4v3” que dizem ser um pouco mais leve, caso sua máquina esteja capengando muito pra rodar o padrão. Mas aí vai ter que modificar o Dockerfile pra fazer download desse modelo e re-buildar:

# === OPTIONAL: Preload additional Real-ESRGAN models ===
# Uncomment any models you want available in the container at build time

# Anime 6-block model (better for anime stills, line art)
# RUN wget -q https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/RealESRGAN_x4plus_anime_6B.pth \
#     -O /opt/Real-ESRGAN/weights/RealESRGAN_x4plus_anime_6B.pth

# Original RealESRGAN 4x general-purpose model
# RUN wget -q https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/RealESRGAN_x4plus.pth \
#     -O /opt/Real-ESRGAN/weights/RealESRGAN_x4plus.pth

# RealESRGAN 2x model (lighter upscale)
# RUN wget -q https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/RealESRGAN_x2plus.pth \
#     -O /opt/Real-ESRGAN/weights/RealESRGAN_x2plus.pth

# ESRNet (non-GAN model, ultra-smooth)
# RUN wget -q https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/RealESRNet_x4plus.pth \
#     -O /opt/Real-ESRGAN/weights/RealESRNet_x4plus.pth

# General-purpose lightweight video-friendly model (with denoise control)
# RUN wget -q https://github.com/xinntao/Real-ESRGAN/releases/download/v0.3.0/realesr-general-x4v3.pth \
#     -O /opt/Real-ESRGAN/weights/realesr-general-x4v3.pth

# Anime video model (default in your setup)
# RUN wget -q https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesr-animevideov3.pth \
#     -O /opt/Real-ESRGAN/weights/realesr-animevideov3.pth

# Original ESRGAN (2018) model
# RUN wget -q https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/ESRGAN_x4.pth \
#     -O /opt/Real-ESRGAN/weights/ESRGAN_x4.pth

Eu não testei todos, mas pra quem quiser, acho que esses são os links. Mude no Dockerfile, faça o build, mude a variável MODEL e teste nos seus videos.

O que vale mexer são coisas como DENOISE, que está pra “1.0” que é máximo, mas isso pode deixar a imagem “esticada” demais. Vale testar valores menores, como “0.5”. Varia de caso a caso, só testando.

Outro fator é a escala, SCALE, que o default é “4x”, que transforma 1080p em 4K ou 720p em 1440p. Mas às vezes não precisa subir tanto, e nem adianta porque a imagem original já tem muito pouco detalhe mesmo. Talvez só 2x seja suficiente. O script suporta 2x, 3x, 4x mas tem teto na resoluçãod e 4K, então não adianta tentar transformar video que já é 4K em 8K por exemplo.

Minha RTX 4090 e meu Ryzen 9 são bem potentes. Processando só um video eu não vejo ele suando nem um pouco:

Claramente daria pra rodar mais videos em paralelo. Tem que tomar cuidado quando é desbalanceado. Se a CPU subir pra perto de 100% pra separar os frames, não adianta estar sobrando na GPU. Os dois tendo sobra, dá pra fazer o script subir mais de 1 processo na GPU e mandar frames em paralelo com a opção “-e NUM_PROC=2”. Olha como agora ele já usa mais da GPU e a CPU ainda tá sobrando. Talvez 3 seja o máximo, mas tem que testar, não é constante o tempo todo.

Isso pode diminuir o tempo total dramaticamente. Você pode escolher entre aumentar os processo na GPU pelo script ou ter dois diretórios separados de video e subir dois containers paralelos desse programa pra rodar ao mesmo tempo, o que funcionar melhor pra você.

Resultado Final

Vamos ver como ficou aquele primeiro clip com upscale 4x e denoise 1.0:

Dá uma diferença ENORME, mas se ficou “BOM” vai ser BEM subjetivo. Eu particularmente não achava o original ruim de assistir. Talvez se mexer no DENOISE pra um pouco menos ou SCALE pra 2x em vez de 4x já fique bom, não sei.

Pra comparar, eis outro clip na versão original antiga:

E de novo, como fica depois do upscale 4x:

Pelo menos está funcionando como deveria, a partir daqui é fazer algum tuning. Se alguém tiver mais dicas ou conhecer modelos ou projetos mais novos de upscaling open source, mande nos comentários abaixo!

Antes que alguém pergunte, porque não usar DLSS 3 da NVIDIA, que eles usam pra aumentar resolução de games? Resposta: porque eles não expõe essa funcionalidade como uma API que dá pra acessar, é só pros drivers proprietários deles em profile de jogo. Eles ligam e tunam caso a caso. Não tem API geral na lib CUDA.

Update pós-publicação

Resolvi testar o modelo RealERSGAN_x4plus_anime_6B, que é bem mais pesado que o realesr-animevideov3 que subi no repositório.

Mude o Dockerfile e adicione isto depois do wget do outro modelo:

RUN wget -q https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.2.4/RealESRGAN_x4plus_anime_6B.pth \
     -O /opt/Real-ESRGAN/weights/RealESRGAN_x4plus_anime_6B.pth

Esse modelo não tem como rodar em paralelo nem na minha RTX 4090, que fica constantemente em 100%. Se antes ia a uns 13 frames por segundo, com esse vai só a 3 frames por segundo. É 4x mais pesado e somente pra GPUs realmente parrudas. Se não tiver algo assim, fique na “realesr-animevideov3” mesmo ou no mais leve ainda (menos qualidade) “realesr-general-x4v3”. Esses modelos dependem muito da potência da GPU e principalmente, quantidade de VRAM.

Pra rodar adicione “-e MODEL=RealESRGAN_x4plus_anime_6B” no comando “docker run”.

Veja como ficou o mesmo clip de antes usando este modelo:

Pra ter gasto 4x mais recursos da minha máquina pra processar, o resultado final eu não achei que ficou tão diferente, e em algumas partes eu acho que ficou mais defeitos até. Então é isso, o resultado vai variar, tem que testar. Depende muito da qualidade do anime original, mas não é porque existe um modelo maior e teoricamente “melhor” que todo resultado vai ficar melhor.

Saí fuçando GitHub e tem uma página Awesome Image Colorization com vários papers de pesquisa. Muito útil pra quem for pesquisador mas totalmente inútil pra mim que não vou fazer um do zero kkkk. Tinha links pra alguns projetos como ChromaGAN, mas que está descontinuado faz uns 5 anos. E vários outros projetos que eu vi foram descontinuados lá atrás mesmo, não sei porque tem tão pouco open source ainda atualizado.

Mas felizmente esbarrei em um promissor: DDColor.

Bora clonar o repositório. E pra continuar, prefiro fazer tudo dentro de Docker. Ficar baixando dependência de python sempre zoa meu sistema e deixa um monte de lixo pra trás, então melhor coisa é isolar tudo. Outra coisa, precisa baixar os binários dos modelos pré-treinados. Só pra isso vou usar um pouco de Python por causa da lib “modelscope” que faz isso:

git clone https://github.com/piddnad/DDColor.git
cd DDColor

mkdir modelscope

# criar um novo venv dentro do projeto DDColor
python -m venv venv

venv/bin/pip3 install modelscope

venv/bin/python3 -c "from modelscope.hub.snapshot_download import snapshot_download; snapshot_download('damo/cv_ddcolor_image-colorization', cache_dir='./modelscope')"

Boa prática de Python acho que é fazer tudo dentro de uma VENV né? Enfim, isso deve baixar o binário do modelo, que pesa quase 900MB. Não é grande.

Agora precisamos de um Dockerfile:

# Use NVIDIA CUDA base image with cuDNN 8 and Python support
FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04

# Install Python and system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 python3-pip git libgl1 libglib2.0-0 && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /app

# Copy DDColor source code into the image
COPY . /app

# Install PyTorch (CUDA 11.8 compatible) and matching torchvision/torchaudio
RUN pip3 install torch==2.2.0 torchvision==0.17.0 torchaudio==2.2.0 \
    --index-url https://download.pytorch.org/whl/cu118

# Install Python dependencies, skipping dlib (not needed for inference)
RUN sed '/dlib/d' requirements.txt > temp-req.txt && pip3 install -r temp-req.txt && rm temp-req.txt

# Optional: install modelscope if you want to run snapshot_download manually inside the container
RUN pip3 install modelscope

Preguiça de abrir um pull request pra isso, se alguém quiser, mande lá.

Agora precisamos colocar uma imagem preto e branco em algum lugar:

mkdir input
mkdir results
mv ~/Downloads/bw.jpg input/

Como as fotos da minha namorada são familiares e particulares, obviamente não vou compartilhar, então peguei uma aleatória qualquer no Google Images:

Agora colocamos em “./input” e rodamos o Docker com este comando:

docker run --rm --gpus all \
  -v "$PWD/input":/workspace/input_images:ro \
  -v "$PWD/results":/workspace/results:rw \
  -v "$PWD/modelscope":/app/modelscope:ro \
  ddcolor:latest \
  python3 infer.py \
    --model_path /app/modelscope/damo/cv_ddcolor_image-colorization/pytorch_model.pt \
    --input /workspace/input_images \
    --output /workspace/results

Preste atenção no mapeamento de diretórios. E note a opção “–gpus” que só funciona no meu caso porque eu tenho uma RTX 4090 instalada aqui. Não tenho a mínima idéia se é a mesma coisa com AMD, mas como a imagem é baseada em cnDNN/CUDA, acho que não. Pergunte ao ChatGPT.

Se estiver tudo certo e rodar com sucesso, vai levar só 1 segundo e ter este output no terminal:

==========
== CUDA ==
==========

CUDA Version 11.8.0

Container image Copyright (c) 2016-2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved.

This container image and its contents are governed by the NVIDIA Deep Learning Container License.
By pulling and using the container, you accept the terms and conditions of this license:
https://developer.nvidia.com/ngc/nvidia-deep-learning-container-license

A copy of this license is made available in this container at /NGC-DL-CONTAINER-LICENSE for your convenience.

Output path: /workspace/results
100%|██████████| 1/1 [00:00<00:00,  4.09it/s]

E eis o resultado que aparece no diretório `./results":

Sim, eu fiquei impressionado. Mesmo a imagem sendo da Web, com marca d’agua e tudo, ele fez tudo direitinho e funcionou!!

Único problema é que ainda falta o problema de conseguir usar uma imagem de referência pra tentar pegar as cores. Esse é um problema mais difícil e eu perguntei ao ChatGPT que me respondeu isto:

Sem suporte nativo para imagem de referência:

O modelo DDColor, tanto na versão oficial hospedada no ModelScope quanto no repositório GitHub piddnad/DDColor, foi projetado apenas para colorização automática de imagens em preto e branco, sem aceitar uma imagem de referência como entrada. A própria descrição oficial deixa claro que o modelo recebe uma única imagem P&B e retorna uma imagem colorida.

O método forward do modelo espera apenas um tensor, referente à imagem P&B convertida em RGB artificial (na verdade, a luminância expandida para 3 canais). Ou seja, não há lugar no modelo para passar uma segunda imagem como referência de cores.

Isso também fica evidente no predict.py original da biblioteca Cog, que aceita apenas o parâmetro image como entrada — sem suporte a reference, ref_image ou algo do tipo.

Como resolver o problema: duas abordagens possíveis

Como o DDColor não suporta nativamente uma imagem de referência para guiar as cores, temos duas alternativas:

🔁 1. Usar um modelo especializado em colorização com referência

Existem modelos desenvolvidos especificamente para isso, como:

• Deep Exemplar-based Colorization (Zhang et al., CVPR 2018)

• ChromaGAN (2019)

• Exemplar-Transformer Colorization (Yin et al., ACM MM 2021)

• UniColor (Huang et al., 2022)

Esses modelos aceitam duas imagens:

• A imagem em P&B (entrada principal)

• Uma imagem colorida como referência de cores

Esses modelos mapeiam similaridades semânticas (ex: “pele aqui deve ter a mesma cor de pele dali”) e fazem uma transferência baseada no conteúdo da imagem, obtendo resultados muito mais detalhados e específicos. No entanto, isso exigiria:

• Baixar pesos diferentes

• Alterar completamente a arquitetura usada

• Adaptar o pipeline e a inferência

🎯 2. Usar transferência global de cor após a saída do DDColor (nossa abordagem atual)

A solução prática e leve que usamos foi:
➡️ Rodar o DDColor normalmente para gerar a imagem colorida automaticamente
➡️ Depois, ajustar globalmente as cores do resultado para ficarem mais parecidas com as da imagem de referência.

Esse ajuste é feito com o algoritmo de Reinhard et al. (2001):

1. Convertemos tanto a imagem de saída quanto a referência para o espaço de cor Lab.

2. Calculamos a média e o desvio padrão dos canais a e b (os que representam cor).

3. Ajustamos o resultado para ter a mesma distribuição estatística de cor que a imagem de referência.

4. Isso tende a deixar a imagem com o mesmo “clima” ou tom geral (mais quente, mais frio, mais vibrante).

Esse método é rápido, leve, e funciona sem alterar o modelo DDColor.

Continuando

Eu usei a modificação que ele sugeriu ao arquivo predict.py:

import os
import cv2
import numpy as np
import torch
import torch.nn.functional as F
from cog import BasePredictor, Input, Path
from basicsr.archs.ddcolor_arch import DDColor

def color_transfer(reference_bgr: np.ndarray, target_bgr: np.ndarray) -> np.ndarray:
    """Transfer color palette of reference image to target image using Lab mean/std."""
    # Convert BGR images to Lab color space (float32 for precision)
    ref_lab = cv2.cvtColor(reference_bgr, cv2.COLOR_BGR2LAB).astype("float32")
    tgt_lab = cv2.cvtColor(target_bgr, cv2.COLOR_BGR2LAB).astype("float32")
    # Split channels
    L_ref, a_ref, b_ref = cv2.split(ref_lab)
    L_tgt, a_tgt, b_tgt = cv2.split(tgt_lab)
    # Compute mean and std for reference and target (a and b channels)
    a_ref_mean, a_ref_std = a_ref.mean(), a_ref.std()
    b_ref_mean, b_ref_std = b_ref.mean(), b_ref.std()
    a_tgt_mean, a_tgt_std = a_tgt.mean(), a_tgt.std()
    b_tgt_mean, b_tgt_std = b_tgt.mean(), b_tgt.std()
    # Subtract target means, scale by reference/target std, add reference means
    # (Avoid division by zero in case of zero std)
    if a_tgt_std > 1e-6:
        a_tgt = ((a_tgt - a_tgt_mean) * (a_ref_std / a_tgt_std)) + a_ref_mean
    else:
        a_tgt = a_tgt - a_tgt_mean + a_ref_mean
    if b_tgt_std > 1e-6:
        b_tgt = ((b_tgt - b_tgt_mean) * (b_ref_std / b_tgt_std)) + b_ref_mean
    else:
        b_tgt = b_tgt - b_tgt_mean + b_ref_mean
    # Clip values to valid Lab range [0,255] after transfer
    a_tgt = np.clip(a_tgt, 0, 255)
    b_tgt = np.clip(b_tgt, 0, 255)
    # Merge channels back (use original L from target to preserve brightness)
    merged_lab = cv2.merge([L_tgt, a_tgt, b_tgt]).astype("uint8")
    # Convert back to BGR color space
    result_bgr = cv2.cvtColor(merged_lab, cv2.COLOR_LAB2BGR)
    return result_bgr

class ImageColorizationPipeline:
    """Helper pipeline to load DDColor model and process images."""
    def __init__(self, model_path: str, input_size: int = 256, model_size: str = "large"):
        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
        # Choose encoder backbone based on model size
        encoder_name = "convnext-t" if model_size == "tiny" else "convnext-l"
        # Initialize DDColor model
        self.model = DDColor(
            encoder_name=encoder_name,
            decoder_name="MultiScaleColorDecoder",
            input_size=[input_size, input_size],
            num_output_channels=2,    # model predicts ab channels
            last_norm="Spectral",
            do_normalize=False,
            num_queries=100,
            num_scales=3,
            dec_layers=9,
        ).to(self.device)
        # Load weights
        state = torch.load(model_path, map_location="cpu")
        # Some checkpoints store weights under 'params' key
        self.model.load_state_dict(state.get("params", state), strict=False)
        self.model.eval()
        self.input_size = input_size  # store for processing

    @torch.no_grad()
    def process(self, img_bgr: np.ndarray) -> np.ndarray:
        """Colorize a BGR image (numpy array) using the loaded DDColor model."""
        # Preserve original resolution L channel
        orig_h, orig_w = img_bgr.shape[:2]
        # Convert to Lab and extract L channel at original size
        img_lab = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2LAB).astype("float32")
        orig_L = img_lab[:, :, 0:1]  # shape (H, W, 1)
        # Prepare grayscale input at model resolution
        # Resize input to model expected size
        inp = cv2.resize(img_bgr, (self.input_size, self.input_size))
        inp_lab = cv2.cvtColor(inp, cv2.COLOR_BGR2LAB).astype("float32")
        L = inp_lab[:, :, 0:1]
        # Create grayscale Lab image by zeroing AB channels
        gray_lab = np.concatenate([L, np.zeros_like(L), np.zeros_like(L)], axis=2)
        # Convert back to RGB (now it's a gray RGB image of size input_size)
        gray_rgb = cv2.cvtColor(gray_lab.astype("uint8"), cv2.COLOR_LAB2RGB)
        # Prepare tensor and run model
        tensor = torch.from_numpy(gray_rgb.transpose(2, 0, 1)).float().unsqueeze(0).to(self.device)
        out_ab = self.model(tensor)  # output is (1,2,H_out,W_out) in Lab AB
        out_ab = out_ab.cpu().float()
        # Resize output AB to original image size
        out_ab_resized = F.interpolate(out_ab, size=(orig_h, orig_w), mode="bilinear", align_corners=False)
        out_ab_resized = out_ab_resized[0].numpy().transpose(1, 2, 0)  # (H, W, 2)
        # Combine original L and predicted AB, then convert to BGR
        out_lab = np.concatenate([orig_L, out_ab_resized], axis=2).astype("uint8")
        out_bgr = cv2.cvtColor(out_lab, cv2.COLOR_LAB2BGR)
        return out_bgr

class Predictor(BasePredictor):
    def setup(self):
        """Load models into memory for efficient multiple predictions."""
        # Determine paths for large and tiny model weights
        large_model_path = "checkpoints/ddcolor_modelscope.pth"
        tiny_model_path  = "checkpoints/ddcolor_paper_tiny.pth"
        # (Ensure the above files exist. If not, download from ModelScope or HuggingFace as described.)
        # Initialize pipelines for large and tiny models
        self.colorizer_large = ImageColorizationPipeline(model_path=large_model_path, input_size=512, model_size="large")
        self.colorizer_tiny  = ImageColorizationPipeline(model_path=tiny_model_path,  input_size=512, model_size="tiny")

    def predict(
        self,
        image: Path = Input(description="Grayscale input image."),
        reference: Path = Input(description="Optional reference image to guide colors", default=None),
        model_size: str = Input(description="Model size to use (large = highest quality, tiny = faster).",
                                choices=["large", "tiny"], default="large"),
    ) -> Path:
        """Run a single prediction. Colorizes the image, optionally using a reference image for color bias."""
        # Read input image
        img = cv2.imread(str(image))
        if img is None:
            raise ValueError("Failed to load input image")
        # Select model pipeline
        pipeline = self.colorizer_tiny if model_size == "tiny" else self.colorizer_large
        # Colorize the image using DDColor
        output_bgr = pipeline.process(img)
        # If a reference image is provided, transfer its color style to the output
        if reference is not None:
            ref_img = cv2.imread(str(reference))
            if ref_img is None:
                raise ValueError("Failed to load reference image")
            # Only apply transfer if reference is a color image
            if ref_img.shape[2] == 3:
                output_bgr = color_transfer(ref_img, output_bgr)
        # Save result
        out_path = "/tmp/out.png"
        cv2.imwrite(out_path, output_bgr)
        return Path(out_path)

Com essa modificação posso rodar com esse novo parâmetro, note a opção “–ref” que tem agora e coloque sua imagem no lugar certo:

❯ docker run --rm --gpus all \
  -v "$PWD/input":/workspace/input_images:ro \
  -v "$PWD/results":/workspace/results:rw \
  -v "$PWD/ref_images":/workspace/ref_images:ro \
  -v "$PWD/modelscope":/app/modelscope:ro \
  -v "$PWD/infer.py":/app/infer.py:ro \
  ddcolor:latest \
  python3 /app/infer.py \
    --model_path /app/modelscope/damo/cv_ddcolor_image-colorization/pytorch_model.pt \
    --input /workspace/input_images \
    --ref /workspace/ref_images/images.jpg \
    --output /workspace/results

Passei outra foto colorida de referência mas não dferença no resultado. Novamente, perguntei ao ChatGPT:

Por que você não percebeu diferença no resultado?

A transferência global de cor só altera a “paleta geral” — e não as cores de cada objeto.

Se a imagem de referência tem tons suaves ou parecidos com os que o DDColor já aplicaria automaticamente, o efeito final vai parecer idêntico.

Mas se você usar como referência uma imagem bem saturada (por exemplo, um céu alaranjado, ou um ambiente azul escuro), você verá a saída do DDColor ser puxada visualmente para aquele estilo.

Conclusão

Segui a sugestão e baixei outra imagem nada a ver, colorida, super saturada com cores vibrantes pra ver se fazia diferença. Esta é a imagem de referência que passei pro Docker:

E eis o novo resultado aplicando ela à imagem anterior em pós-processamento (esse passo não é mais I.A. é pós-processamento de imagem mesmo).

Comparem com a outra foto re-colorizada, vou colocar aqui embaixo de novo pra dar pra comparar:

Entenderam? Agora precisa ficar testando com referências diferentes pra ver a influência no resultado final, mas de fato, ele consegue aplicar o algoritmo de Reinhard e fazer uma transferência global de cor. Como o nome diz, é “global”, não “por objeto”, então é difícil conseguir controlar só partes da imagem e sim a imagem toda. Mas em teoria eu acho que você conseguiria fazer uma colorização manual no Photoshop com cores saturadas, perto de onde quer influenciar, pra tentar ajustar, mas eu não tentei isso ainda, depois se alguém fizer, mande nos comentários.

Mas é isso. Agora pelo menos eu consigo me divertir pegando fotos antigas de família e re-colorizar.

Todos os videos do meu canal, incluindo os arquivos originais, estão lá. Só isso dá terabytes. Todo minha biblioteca do Steam está lá, são uns 4 terabytes. Todos os meus jogos antigos, retro-games, também, incluindo ISOs de Xbox 360 e PS3. São mais 4 terabytes. Toda minha coleção de discos Ultra HD (BluRay 4K) eu ripei (fiz backup), são mais alguns terabytes. Neste instante já estou usando mais de 50 terabytes.

Antes que venham dar palpite, sim, isso não é pra qualquer um. Estamos falando de 8 HDs de 10.9 TB, mais upgrade de 2 HDs de 20 TB, mais outros 2 HDs de 20 TB de backup pra caso um deles dê pane, mais 2 NVMEs de 1 TB cada só pra ser cache, mais placa de rede de 10 Gbps. Além disso eu mantenho várias cópias online de parte desse conteúdo em Google Drive ou Dropbox, e um backup inteiro na Amazon Glacier, pra rara ocasião se minha casa pegar fogo, por exemplo. Estou preparado pra qualquer catástrofe, sempre.

A Synology é uma das melhores marcas de NAS caseiros. Sim, dá pra fazer bem mais sofisticado também, basta montar um servidor de verdade, com CPUs como AMD EPYC ThreadRipper, usando sistemas como TrueNAS. Mas aí é demais pra mim, já não me sinto confortável dando manutenção. Como eu disse, os limites cada um tem que saber os seus.

1o HD de 20TB terminou de se integrar ao RAID! Levou 2 dias inteiros!! Colocando o 2o HD ... de 4 😅 pic.twitter.com/Rv6dqBQr05

— Akitando.com (@AkitaOnRails) March 27, 2024

“Por que não deixar tudo online??” Pra maioria das pessoas é o caminho mais fácil mesmo. Como eu disse, meu caso é particular. Você NÃO QUER ter mais de 50 TERAbytes online. Minha rede cabeada local é de 10 Gbps, minha internet de fibra é míseros 0.5 Gbps (500 Mbps). Trafegar video de alta qualidae pela internet é horrivelmente lento. Eu quero tudo em tempo real, e pra isso só sendo rede cabeada local.

Isso dito, eu montei um segundo mini-computador, usando um Intel NUC, conectado na mesma rede cabeada com o NAS. É Core i7, 32GB de RAM, ethernet 2.5Gbps, com o único intuito de ser um servidor Ubuntu vazio (poderia ser qualquer Linux, só escolhi o mais fácil mesmo) que serve pra subir containers Docker.

Mesmo esse PC-zinho é overkill, muito mais do que é necessário. Muitos vão comentar que um Raspberry-Pi 5 seria suficiente, e não estão errados. A melhor solução é a que você tem orçamento pra comprar e se sente confortável em dar manutenção. Não tente copiar exatamente o setup de ninguém, estude o que melhor encaixa pra você. E não percam tempo dando pitaco no setup dos outros, façam o seu.

De qualquer forma, resolvi compartilhar com vocês todos os arquivos de docker-compose que estou usando pra subir os containers docker nesse servidor. Eis o repositório no GitHub.

AVISO: não esqueçam que precisa editar os diretórios nos scripts. Ele está configurado pra acessar o mount point do meu NAS em rede, que é /mnt/terachad. Arrume pra apontar pros lugares certos na sua máquina.

AVISO 2: existem muitos detalhes que não estou cobrindo neste artigo. Este fórum do Reddit tem mais detalhes e mais discussões. Dependendo se estiver com dúvidas ou problemas específicos, talvez esteja respondido lá.

Pra você não se perder no meio de tantos serviços, aqui está o desenho completo do que a gente vai montar, do pedido até assistir na TV, incluindo as camadas de proteção que impedem malware e download errado de entrar na sua biblioteca:

A ideia é essa: você pede num lugar (Seerr), o sistema encontra (Prowlarr e os indexers), baixa com proteção (qBittorrent e SABnzbd, mais as camadas de segurança), organiza no NAS (com legendas do Bazarr) e você assiste em qualquer tela (Plex e Navidrome). Deixa eu começar explicando um a um dos principais.

Portainer e Utilitários

Este é o trecho (veja completo no repositório):

volumes:
  portainer_data:

services:
  portainer:
    image: portainer/portainer-ce:latest
    restart: unless-stopped
    volumes:
      - portainer_data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - '9000:9000'

Portainer é um gerenciador visual dos recursos gerenciados pelo serviço de Docker na sua máquina. Objetivo é mais pra eu visualmente conseguir “bater o olho” e ver se tem algum container com problema ou pra testar algum ajustezinho rápido em alguma configuração antes de editar no arquivo de docker compose.

No arquivo utils-docker-compose.yml tem outros serviços como Organizr que eu instalei mas ainda não parei pra configurar nem ver se realmente quero manter. Tem o Librespeed, que funciona como aqueles testes de velocidade de internet, mas pra rede local. Tem o Watchtower, que monitora atualização das imagens de todos os containers Docker, faz o download e automaticamente manda reiniciar com versões novas, pra manter todos os containers sempre atualizados.

E pra acessar os serviços locais fora de casa, tem opções fáceis de VPN como o Tailscale ou o ZeroTier, com pouca configuração. Sim, sim, antes que alguém vá pros comentários, dá pra montar OpenVPN do zero, mas vai por mim, essas opções são infinitamente mais “plug and play” e possivelmente mais seguras, porque todo mundo instala, mas poucos têm a disciplina de dar manutenção e atualizar o que precisa o tempo todo. Hoje em dia eu acabei migrando pra um túnel da Cloudflare pra expor meus serviços, mas pra começar, um Tailscale da vida resolve super bem.

MakeMKV e HandBrake

Pra montar sua biblioteca pessoal de filmes, de forma legítima, o correto é você ser proprietário de discos de BluRay ou UHD e “ripar” eles. Se for esse o caso, recomendo comprar modelos de leitor de discos como o Pioneer BDR-XS07S Tem que ficar MUITO esperto porque não é qualquer leitor que funciona.

Veja no fórum do MakeMKV quais os modelos mais recomendados. Tem modelos que tiveram atualização de firmware que impedem deles serem usados pra ripar BluRay. Precisa achar modelos que ou não foram atualizados, ou que não é difícil fazer downgrade de firmware. O ideal é já comprar modelos que todo mundo sabe que funciona, e pra isso tem que fuçar fóruns como esse.

MakeMKV, como o próprio nome diz, “Faz arquivos de video MKV”, que é o bom e velho formato Matroska de envelope de video, um dos mais versáteis (porque suporta múltiplos streams não só de áudio, mas de legenda também).

Crash course: uma coisa é o codec que faz o encodings dos streams de video e streams de audio. Por exemplo, H.265 ou AV1, são codecs de video. MP3 ou AAC são codecs de áudio. Agora precisamos empacotar esses dois streams (ou mais, caso tenha múltiplas dublagens, por exemplo), num “envelope”, um “container”, um “formato de arquivo”, como arquivos “.mp4” ou “.mov”. Matroska é um formato de envelope de arquivo, que é bem flexível, permite múltiplos streams de tudo, incluindo de legenda, por isso é muito usado pra compartilhar em torrent.

Com esse container, você consegue acessar via navegador a interface gráfica do aplicativo (é como se fosse um cliente remoto de Windows, como VNC). Basta ter o leitor de Blu-Ray conectado via USB no seu computador e deve achar. Ele vai usar a biblioteca libredrive pra descriptografar os streams de dados do Blu-Ray, e por isso a importância das versões de firmware serem compatíveis (já terem sido quebrados).

Muitos não sabem que a gente chama tudo de “Blu-Ray” mas na realidade Blu-Ray é pra filmes encodados em versão Full HD, que é 1080p. As versões em 4K (2160p) vem em UHD, que é Ultra HD. A caixa de Blu-Ray costuma ser azul, as de UHD são pretas, você quer as UHD sempre que possível, claro. E eu tenho uma coleção enorme:

"onde eu tô gastando tanto espaço??"

Boa parte é fazendo Rip (backup) de todos os meus UHD (BluRay 4K). E isso porque estou re-encodando em bitrate menor depois de ripar kkkk pic.twitter.com/T1yPa6EIcV

— Akitando.com (@AkitaOnRails) March 26, 2024

A vantagem de um app como MakeMKV é conseguir descriptografar o stream de video e copiar bit a bit exatamente como está no UHD, a melhor qualidade possível. É o que se chama de REMUX (remuxing), que é extrair o stream do container e colocar em outro container sem re-encodar. Já deve ter visto em alguns arquivos de Torrent, é a melhor qualidade. Porém significa que vai gastar o mesmo espaço que no disco, uma faixa de 50 a 80 GIGAbytes, por filme. Cada uma dúzia de filmes vai consumir quase 1 terabyte. Dependendo de quantos filmes você quer ter, seu espaço livre vai acabar muito rápido.

Pra minimizar isso, podemos recodificar ou “re-encodar”. É como quando pegamos uma foto em RAW e re-encodamos pra um formato de menor qualidade, como PNG ou mesmo JPEG. Se souber onde procurar, vai achar os artefatos de compressão, mas no geral, compensa. Por exemplo, no meu caso, encodar pra H.265 10-bit, QP 15 Constant Quality.

A melhor opção é ter uma placa de video NVIDIA, com suporte a encoding de video via hardware NVENC e usar o melhor software pra encoding de video: Handbrake. No meu caso, eu escolho o perfil pré-configurado de Matroska H.265 MKV 4K60fps e mudo pra usar o encoder NVENC da minha placa RTX 4090, que isso acelera o encoding em múltiplas vezes.

No docker compose, assim como MakeMKV, posso subir esse app pra ter acesso via navegador web, assim:

  handbrake:
    restart: unless-stopped
    image: jlesage/handbrake
    ports:
      - "5801:5800"
    environment:
      - AUTOMATED_CONVERSION=0
      - HANDBRAKE_GUI=1
      - DARK_MODE=1
      - TZ=America/Sao_Paulo
    volumes:
      - "/home/akitaonrails/handbrake:/config:rw"
      - "/home/akitaonrails:/storage:ro"
      - "/mnt/terachad/Videos/BluRay:/watch:rw"
      - "/mnt/terachad/Videos/BluRayOptimized:/output:rw"
    devices:
      - /dev/dri:/dev/dri

Seu PC tem no mínimo uma placa de video Intel com suporte a encoding via hardware QSV ou melhor, da NVIDIA, com suporte a NVENC. Em ambos os casos, fazemos o container ter acesso a isso mapeando o dispositivo /dev/dri. Sem isso, o encoding vai ser via CPU, e vai demorar ordens de grandeza mais.

Lembrando que encoding via software, é mais lento mas vai ter qualidade superior a Intel QSV que, apesar de rápido, sempre me dá qualidade de video inferior. NVENC é o melhor dos dois mundos: excelente qualidade e muito rápido.

AVISO: no meu caso, quero a melhor qualidade possível, por isso faço backup de UHD, por isso mesmo torrent eu baixo BR-DISC que é backup de UHD, e isso é absurdamente pesado como expliquei. Daí eu manualmente refaço o encoding pro perfil Matroska H.265 como também expliquei.

Muitos não querem ter esse trabalho, pra isso não deixe de ler o fórum do Reddit que explica como configurar os próximos serviços pra não baixar arquivos grandes assim, eu não vou mostrar aqui, porque não é meu caso.

QBitTorrent

Por mais Blu-Ray e UHDs que você tenha ou consiga comprar, muita coisa nem existe em disco físico. Nesse caso, sua única opção é BitTorrent. E sim, é ilegal piratear, eu não estou incentivando pirataria bla bla bla …

Cada país tem uma lei, vá pesquisar. Vou assumir que todo mundo sabe com o que está fazendo e não é problema meu. Não adianta comentar sobre isso, não vou alongar isso. A Web já está abarrotada de material a respeito, vá no Google e procure você mesmo.

Primeira coisa que queremos é instalar QBitTorrent, provavelmente o melhor e mais completo aplicativo pra baixar torrent, e também tem interface web e funciona via Docker:

  qbittorrent:
    image: linuxserver/qbittorrent:latest
    restart: unless-stopped
    environment:
      - TZ=America/Sao_Paulo
      - WEBUI_PORT=8080
      - PUID=1000
      - PGID=1000
    volumes:
      - /home/akitaonrails/qbittorrent/config:/config
      - /mnt/terachad/Downloads/torrents:/downloads
    ports:
      - '8080:8080'
      - '62609:62609'

É importante lembrar de gerar uma porta aleatória nas configurações do QBitTorrent, como mostrado na imagem abaixo. Qualquer porta entre 1025 e 65535 deve funcionar, mas é possível que sua rede bloqueie alguma sequência de portas nesse intervalo, então tem que testar. Pesquise fóruns na web, cuidado que tem muita dica online que já está desatualizado.

Precisa entender o mínimo de redes, entender se está atrás de um NAT, como mapear portas externas, se tem firewall ativo bloqueando portas, etc.

Se o torrent não estiver baixando, “pode ser” isso. Coloco entre aspas porque é só uma possibilidade. Então clique em “random” pra escolher outra porta, edite a configuração de docker compose pra mapear a porta nova e reinicie o container.

Por alguma razão o gerenciamento de salvamento vem tudo como Manual, é importante mudar pra automático:

Outro detalhe é pedir pro QBitTorrent re-anunciar os downloads para os trackers quando a porta mudar. Pra isso habilite essa opção “Reannounce to all trackers when IP or port changed”, senão os downloads podem não reiniciar.

Agora o ajuste mais importante desta seção inteira, e que eu aprendi na marra: bloquear executáveis no momento do download. Um belo dia achei nove torrents “completos” na biblioteca cujo único conteúdo era um executável de Windows de quase 1 GB, sem video nenhum. E o pior, o nome do release era limpinho, coisa tipo Reacher S04E07 1080p WEB H264-CAKES ou Rick and Morty S09E10 ... EDITH.scr. Você olha o nome e jura que é o episódio. O .exe ou .scr estava escondido no arquivo lá dentro.

Filtro por nome não pega isso, porque o nome está limpo. A defesa que realmente funciona é bloquear a extensão na hora de gravar. No QBitTorrent, vá em Options, Downloads, e habilite “Excluded file names” com esta lista:

*.exe
*.scr
*.bat
*.cmd
*.msi
*.lnk
*.com
*.vbs
*.pif

Com isso, o arquivo malicioso simplesmente nunca é escrito no disco. O torrent “completa” sem nada de útil, o Sonarr ou Radarr percebem que a importação falhou, jogam aquele release na blocklist e saem procurando outro sozinhos. O malware nem toca no disco, e você nem repassa a porcaria seedeando pra frente. Essa é a primeira camada de defesa, e a mais eficaz.

Finalmente, como pesquiso coisas pra baixar? Posso manualmente ir no Google ou DuckDuckGo ou direto em sites como os do PirateBay da vida e buscar arquivos “.torrent” ou links magnéticos. Pra saber o que é isso, assista meu vídeo sobre Criptografia na Prática onde explico tudo sobre Torrent também.

O QBitTorrent tem suporte a plugins de pesquisa. Ele já vem com alguns habilitados. No canto inferior direito, tem o botão de “Search plugins”. Queremos adicionar o plugin que engloba tudo: o serviço Jackett.

Veja que ele quer um host com nome “jackett” habilitado na porta 9117, pra isso temos este trecho no docker compose:

  jackett:
    image: ghcr.io/linuxserver/jackett:latest
    restart: unless-stopped
    environment:
      - TZ=America/Sao_Paulo
      - PUID=1000
      - PGID=1000
    volumes:
      - /home/akitaonrails/jackett/downloads:/downloads
      - /home/akitaonrails/jackett/config:/config
    ports:
      - '9117:9117'

Ele vai subir um serviço onde podemos acessar a interface web assim:

É um serviço que consolida dezenas de sites de pesquisa de torrents num lugar só, consegue testar se estão online e, mais importante, fornece uma chave de API no canto superior direito, que devemos copiar e editar na configuração do plugin do QBitTorrent. Com isso é possível fazer pesquisar diretamente, recebendo respostas assim:

Veja na coluna da direita que lista de onde puxou esses resultados: está vindo do serviço Jackett.

Um aviso importante, porque isso mudou com o tempo: o Jackett aqui serve pra ISSO, a busca manual que você mesmo faz no QBitTorrent. Não caia na tentação de plugar o Jackett direto no Sonarr e no Radarr. A parte automática vai ser gerenciada pelo Prowlarr, que eu explico mais pra frente, e é ele que alimenta os indexers dos serviços. Eu mantenho o Jackett rodando só pra busca manual e, no máximo, como ponte pra algum tracker que o Prowlarr não suporta nativamente, tipo o RuTracker, que o Prowlarr consegue consumir através do Jackett.

Radarr (Filmes)

Procurar manualmente funciona, mas existem formas melhores: deixar um serviço fazer a procura e gerenciar o download pra você, e pra baixar filmes, podemos usar o serviço Radarr:

Pra isso, temos este trecho no docker compose:

  radarr:
    image: ghcr.io/linuxserver/radarr:latest
    restart: unless-stopped
    depends_on:
      - qbittorrent
    environment:
      - TZ=America/Sao_Paulo
      - PUID=1000
      - PGID=1000
    volumes:
      - /home/akitaonrails/radarr/appdata/config:/config
      - /mnt/terachad/Downloads/torrents:/downloads
      - /mnt/terachad/Videos/radarr/movies:/movies
      - /mnt/terachad/Videos/radarr/anime:/anime
    ports:
      - '7878:7878'

Veja que mapeei diretórios diferentes pra filmes ocidentais e filmes anime, é uma preferência minha, você pode organizar como quiser. Como avisei antes, não copie e cole igual estou mostrando aqui: ajuste os diretórios pra sua máquina.

O principal é que uma vez iniciado, podemos navegar pela interface web, pra opção “Settings”. Ali vai ter “Download Clients"e podemos registrar o serviço web de QBitTorrent:

Eu não mostrei, mas nas configurações do QBitTorrent vai ter um lugar pra cadastrar essa senha de admin pra acessar a API dele via web. Não esqueça de cadastrar lá e usar a mesma senha aqui. Assim o Radarr pode controlar o download de filmes diretamente com o QBitTorrent, sem você precisar se meter.

Tem um ajuste no Radarr que eu recomendo fazer logo de cara, porque ele vem com um buraco bobo: por padrão, TODA definição de qualidade vem com tamanho mínimo zero. Isso deixa passar arquivo falso minúsculo se passando por 4K. Eu já fui vítima: um tal Superman (2025) WEBDL-2160p.iso de 598 MB entrou como se fosse o filme e ficou meses aparecendo no Plex. Por dentro da ISO tinha um .exe de 597 MB disfarçado.

A correção é ir em Settings, Quality, e botar um piso de tamanho em cada definição de qualidade. Uso mais ou menos assim, em MB por minuto de video:

• 720p (HDTV/WEBDL/WEBRip/Bluray): 3
• 1080p (HDTV/WEBDL/WEBRip): 5, Bluray 1080p: 8, Remux 1080p: 25
• 2160p (HDTV/WEBDL/WEBRip): 10, Bluray 2160p: 15, Remux 2160p: 50

É baixo o suficiente pra aceitar um bom encode x265 enxuto, e alto o suficiente pra recusar um “4K” de menos de 1 GB, que só pode ser cilada. Um detalhe chato: o Radarr tem um bug em que salvar tudo de uma vez não persiste o tamanho mínimo, então tem que salvar qualidade por qualidade, uma de cada vez.

Sonarr (Séries de TV)

Mesma coisa que o Radarr, mas pra séries de TV, temos o serviço Sonarr:

Esse serviço é sensacional. Ele acha suas séries, cruzando com bancos de dados online com detalhes como temporadas, nomes de cada episódio e vários outros metadados. Daí ele não só consegue baixar episódios antigos, como mantém uma agenda pra ir baixando séries que ainda estão passando. Toda semana aparece episódio novo sozinho:

E mesma coisa do Radarr: em Settings e Download Clients, posso registrar meu QBitTorrent, daí o Sonarr se vira pra ir baixando os episódios:

E pra subir o serviço, no docker compose temos este trecho:

  sonarr:
    image: ghcr.io/linuxserver/sonarr:latest
    restart: unless-stopped
    depends_on:
      - qbittorrent
    environment:
      - TZ=America/Sao_Paulo
      - PUID=1000
      - PGID=1000
    volumes:
      - /home/akitaonrails/sonarr/appdata/config:/config
      - /mnt/terachad/Videos/sonarr:/tv
      - /mnt/terachad/Downloads/torrents:/downloads
    ports:
      - '8989:8989'

Mesma coisa que o Radarr, eu mapeei pastas diferentes pra anime e não-anime, que é questão de preferência da sua organização.

Tanto no Sonarr quanto no Radarr, tem uma configuração que virou obrigatória pra mim depois que comecei a levar cilada: um Release Profile que bloqueia nomes de release conhecidos por serem armadilha. Em Settings, Profiles, eu deixo uma lista de “Must Not Contain” com termos assim:

BROADCAST
FULL HD
.scr
.exe
SODAPOP
REACHERSON

Cada um desses tem história. BROADCAST, SODAPOP e REACHERSON são grupos que empacotam RAR dividido com uma pasta Sample/ que trava a importação (peguei quase 60 GB de lixo de um Welcome to Derry falso de uma vez). FULL HD é a assinatura de nome dos que carregam .exe. E .scr/.exe no nome é literal mesmo. Um aviso pra quem for copiar: o Radarr, por baixo, usa o mesmo campo ignored que o Sonarr, mesmo a interface chamando de “Must Not Contain”, então configure a mesma lista nos dois.

Ainda sobra uma classe que nenhum filtro pega sozinho: os fakes de pré-estreia. Aparece um Reacher S04E07 com zero seeds pra um episódio que só vai ao ar semana que vem. O Sonarr não recusa release com data anterior à estreia, então esses eu limpo na mão mesmo. A boa notícia é que, com o bloqueio de executável do QBitTorrent lá de cima, mesmo quando um desses baixa, ele vem vazio e é descartado automaticamente.

Downloads que travam

Um problema clássico do dia a dia: o torrent fica eternamente preso em “downloading metadata” ou “stalled”, com zero peers, e o Sonarr nunca desiste dele sozinho. Já tive episódio parado cinco dias atrás de um magnet morto enquanto o release bom passava batido, esperando a vez que nunca chegava.

A solução que montei é um script simples rodando uma vez por dia (um cron ou um systemd timer, tanto faz). Ele consulta a fila do Sonarr, do Radarr e do Lidarr pela API, acha os itens presos em “downloading metadata” ou “stalled with no connections” há mais de 72 horas, e manda remover com um comando só:

DELETE /api/v3/queue/{id}?removeFromClient=true&blocklist=true

Isso apaga o download morto, joga o release na blocklist pra não pegar de novo, e a aplicação sai atrás de outra fonte automaticamente. O pulo do gato é o cuidado pra ele NÃO mexer em download que só está lento (menos de 72h) nem em item esperando importação manual, senão você apaga coisa boa por engano. Na primeira vez que rodei, ele limpou dezenove downloads zumbis de uma vez só.

Prowlarr (indexador)

Pra tanto o Radarr e Sonarr saberem de onde puxar os torrents de séries e filmes, eles precisam pesquisar em indexadores ou trackers públicos (ou privados, se você tiver bons contatos - eu não tenho, nem pergunte). Pra isso temos Prowlarr. Esse é o serviço mais importante de todos, porque se esse não funcionar, nada vai baixar direito.

Levei um tempo pra chegar numa configuração boa, mas hoje tenho uma regra simples que resolve: o Prowlarr é o único lugar que gerencia indexer. Sonarr, Radarr e Lidarr NÃO devem ter indexer cadastrado direto, só os que o Prowlarr sincroniza. Todo indexer que eu tinha cadastrado na mão dentro do Radarr era fonte de dor de cabeça, inclusive um “Lime Torrents” que foi exatamente quem me serviu aquele malware da ISO do Superman. Apaguei todos e deixei só o Prowlarr alimentando os três.

Veja que lista dezenas de indexadores, ou trackers. É parecido com o Jackett. A diferença é que o Jackett é pra pesquisas manuais que você mesmo vai fazer, direto no QBitTorrent. Já os indexadores do Prowlarr vão ser configurados direto no Sonarr e Radarr. Aqui começa a confusão, vamos entender:

Tanto no Sonarr quanto no Radarr, além de Download Clients, onde podemos configurar o QBitTorrent, também vai ter essa opção de “Indexers”, onde podemos configurar em quais trackers procurar pela mídia.

Pense num tracker como um mini-Google público, é onde as pessoas registram seus torrents quando querem compartilhar. Torrents não são mágicos e nem aparecem do nada. Alguém tem que criar um registro em algum lugar. Mas não existe só “um” lugar: é uma rede distribuída e qualquer participante pode subir um tracker se quiser. É como se você pudesse subir seu próprio Google miniatura, só pra registrar arquivos de torrent.

É um saco ficar gerenciando isso. Alguns trackers pequenos resolvem sair do ar, novos aparecem, configurações são modificadas, e precisamos ficar gerenciando manualmente isso, tanto no Sonarr quanto no Radarr. Pra isso serve o Prowlarr: pra gerenciar os trackers pra você. Vamos entender como.

Nas configurações do Prowlarr, começamos configurando onde encontrar nossos serviços de Sonarr e Radarr:

Por exemplo, esta é a configuração do meu Sonarr. Notem que o hostname é “sonarr” e isso funciona porque no meu docker compose eu subo todos os serviços na mesma VLAN, e por padrão o docker registra como hostname o nome do serviço configurado no arquivo YAML. Se não entende Docker, não deixe de assistir meus videos sobre containers.

Também precisamos configurar acesso ao QBitTorrent:

Esse outro SABnzbd usa outro protocolo de downloads mais antigo, baseado em newsreader de USENET. Sim, aquela Usenet mesmo. Quem sabe, sabe. Eu deixo o torrent como principal, mas mantenho o SABnzbd configurado como segunda fonte, porque muito conteúdo só existe nesses grupos mais antigos. Se for usar, aplique a mesma proteção de extensão do QBitTorrent: no arquivo sabnzbd.ini, na seção [misc], coloque unwanted_extensions = exe, scr, bat, cmd, msi, lnk, com, vbs, pif e action_on_unwanted_extensions = 2, que manda abortar o download inteiro se aparecer um desses. Assim o Sonarr e o Radarr veem a falha e procuram outra fonte.

Finalmente, muitos trackers hoje implementam algum tipo de proteção contra bots usando captcha da Cloudflare, sabe aquele troço que fica “você é um humano?”. Pra passar por isso, precisamos do serviço Flaresolvrr, que podemos subir no docker compose assim:

  flaresolverr:
    image: ghcr.io/flaresolverr/flaresolverr:latest
    restart: unless-stopped
    volumes:
      - /home/akitaonrails/flaresolverr/config:/config
    ports:
      - '8191:8191'

No Prowlarr ele entra como um “indexer proxy”. Você cadastra o FlareSolverr apontando pra http://flaresolverr:8191/, cria uma tag pra ele, e marca com essa tag só os indexers que ficam atrás do Cloudflare. Aí esses passam a resolver o captcha por baixo dos panos, e os outros nem precisam passar por ele:

Ainda não acabamos. Na tela principal, é sair habilitando os indexers que fazem sentido pra você. Não habilite tudo: fica pesado e, pior, alguns indexers servem mais cilada do que conteúdo bom. Veja as tags de cada um. Tem indexer que é só de pornô, tem indexer só de conteúdo russo ou chinês, esses eu pulo.

Os que me servem bem hoje são o EZTV e o 1337x (os dois atrás do Cloudflare, então dependem do FlareSolverr), o YTS pra filme, e o AnimeTosho mais o Nyaa pra anime. No total sobra algo entre 18 e 21 indexers ativos por aplicação. E, mais importante do que habilitar os bons, é desabilitar os ruins: eu desliguei o LimeTorrents e o TorrentDownload, porque, somados, geraram mais de duzentos downloads e quase nenhuma importação aproveitável, além de serem fonte recorrente de malware e de fake. Menos indexer bom vale mais que um monte de indexer ruim.

No final, é bom clicar esse “Test All Indexers” pra checar quais ainda estão ativos ou não. E por fim, podemos clicar em “Sync App Indexers”, que vai cadastrar todos os indexers que sabemos que estão funcionando, nos registros do Sonarr e Radarr. Entenderam? O Prowlarr vai configurar os dois com os indexers mais atualizados, e remover os que não estão mais ativos. Não precisamos configurar cada um deles manualmente.

É importante entender isso, porque senão você vai ver o Sonarr e o Radarr não conseguindo baixar nada e não vai saber porque: mas é porque os indexers estão errados ou obsoletos ou insuficientes. Gaste bastante tempo lendo a documentação do Prowlarr.

Plex (Netflix Particular)

Pra assistir tudo que baixar, tem várias opções. Se é só pra você, basta ir baixando tudo num HD externo ou algo assim, e assistir diretamente do seu PC ou notebook. Dependendo da Smart TV ou console de videogame, também dá pra conectar seu HD ou pendrive via USB e assistir direto.

Se for um pouquinho mais sofisticado, e tiver um PC ou Raspberry Pi sobrando, dá pra instalar Sonarr, Radarr, e compartilhar o diretório de downloads pela rede, usando protocolos como CIFS, que é pra pasta compartilhada de Windows. Novamente, muitas Smart TVs e consoles suportam montar pastas compartilhadas pela rede.

Mas se quiser algo mais amigável e sofisticado, dá pra ter literalmente seu “Netflix Particular”, com uma interface gráfica parecida com qualquer plataforma de streaming, onde mostra thumbnails, descrições, detalhes do filme ou série, tocador de video e tudo mais e até sugestões do que assistir, sugestões de filme baseado no que está assistindo, informações de atores e tudo mais.

Existem vários projetos que fazem isso. Um deles, que a comunidade curte mais por ser 100% aberto, é o Jellyfin (derivado do antigo Emby). Recomendo que testem, tem tudo que a maioria das pessoas precisa. Basta mapear as pastas de downloas do Sonarr, Radarr e ele vai indexar tudo e organizar pra você. Daí, de qualquer PC, é só acessar a interface web e tudo só funciona.

Mas eu pessoalmente prefiro o Plex, que é mais antigo, é mais fechado (por isso alguns não gostam), mas por oferecer planos pagos com funcionalidades exclusivas, o nível de polimento é nitidamente melhor. A interface é bem mais bonita, e parece mais “profissional”. Jellyfin, por melhor que seja, ainda tem cara que foi um programador backend que fez, com muita má vontade em UX e design.

Além disso, pra assistir numa Smart TV ou Android TV da vida, precisa ter app no Google Play Store. Jellyfin não tem app pra tudo, algumas TV, não lembro se LG ou Samsung, nem tem o app disponível. Então precisa fazer side-load. Não é amigável. Plex, por outro lado, está disponível em bem mais lugares, então costuma ser mais “plug and play”, parecido com baixar app de Netflix ou Amazon Prime.

Plex também tem funcionalidades que “just works”, coisas triviais que se espera num tocador, como botão de “pular abertura” ou “resumir a partir de onde parou” ou “pular pro próximo episódio” ou “pesquisar e trocar legenda”. É isso que interfaces como essas vão te oferecer, daí a usabilidade é realmente muito parecida com assistir Netflix. Não tem isso se usar um tocador genérico de PC como um VLC da vida.

Pra subir é fácil, eis o trecho do meu docker compose:

  plex:
    image: plexinc/pms-docker:latest
    restart: unless-stopped
    environment:
      - TZ=America/Sao_Paulo
      - PUID=1000
      - PGID=1000
      - VA_DRIVER=IHD
      - PLEX_HW_TRANS_MAX=16
    volumes:
      - /home/akitaonrails/plex/config:/config
      - /home/akitaonrails/plex/data:/data
      - /home/akitaonrails/plex/transcode:/transcode
      - /mnt/terachad/Videos:/media
    devices:
      - /dev/dri:/dev/dri
      - /dev/bus/usb:/dev/bus/usb
    network_mode: host

Existe um pequeno detalhe que muitos não entendem: Plex faz transcoding dos videos. Ou seja, ele vai re-encodar o video antes de mandar pro app ou navegador que vai tocar, isso é pesado, é conversão de stream de video. Se seu servidor não for forte o suficiente, seu video vai ficar engasgando pra tocar.

Na realidade, é mais complicado do que isso. Existe um protocolo chamado “Direct Play” ou “Direct Stream”. Tem um artigo que explica isso no site do Plex. Se o PC, SmartTV, console, etc, tiverem suporte ao codec do video em questão, teoricamente o Plex só vai passar os bits direto, sem tentar converter nem nada. Entenda: nem todo dispositivo tem capacidade pra tocar qualquer codec de video.

A maioria do conteúdo hoje em dia é encodado em H.264 ou H.265 ou até AV1, que é mais novo e mais eficiente. Problema, digamos que você queira tocar num PC bem antigo ou num PS4 da vida. Eles vão ter suporte a H.264, talvez H.265, se tiver sorte, mas certamente não a AV1. Daí seria super lento tentar tocar usando só a CPU. O certo é ter instruções de hardware pra tocar AV1, especialmente num CPU antigo.

Então o Plex pergunta pro dispositivo: “você suporta AV1?” O tocador vai dizer “nope, sou fraco.” Então o Plex vai fazer o transcoding de AV1 pra H.264, por exemplo. Tudo isso é transparente pra você.

Mas aí você vai notar que na hora de tocar o video fica engasgando, pausa toda hora. Pode ser um problema de banda da sua rede ou, pode ser problema do seu servidor de Plex ser muito fraco ou, de não estar configurado pra transcoding via hardware, e estar indo na força bruta usando só a CPU.

Assista meu video sobre compressão, onde explico sobre codecs, mas em resumo, o correto é que seja lá qual PCzinho estiver usando pro seu Plex, que ele tenha o mínimo de capacidade de encoding de video em hardware. A maioria costuma ter pelo menos capacidade de H.264, como as instruções Intel QSV, veja se sua CPU tem esse suporte. Só não vai ter se for velho demais, tipo coisa de 10 anos pra trás. Se for um servidor forte, com GPU NVidia, vai ter coisas como NVENC, que dá suporte a H.265. Se for CPU Intel moderna, vai ter suporte a AV1.

Em todo caso, em Linux, essas instruções devem ficar expostas no dispositivo /dev/dri, e por isso precisamos mapear no container docker como fiz acima. Cheque se existe esse dispositivo.

Se estiver tudo certo, no Plex vai ter essa opção de configurar “Transcoder”:

Queremos nos certificar que a qualidade está em “Make my CPU hurt” e que a opção de “Use hardware acceleration when available” está hablitado também, daí ele vai usar o /dev/dri pra acelerar o transcoding. E isso faz uma diferença BRUTAL na velocidade. Se estiver com playback sendo engasgado, muito provavelmente é o transcoding.

Quando o dispositivo, seu smartphone ou sua TV, tem suporte ao exato codec usado no arquivo de video que queremos assistir, teoricamente, o Plex consegue passar o stream direto, sem transcodar, que é o mundo ideal, porque aí não processamento nenhum. Isso é Direct Play. Mas pra isso os arquivos de video precisam estar num determinado codec, numa determinada configuração. Mas mesmo num codec suportado, se sua TV for fraca e não suportar 4K, e pedir pro Plex em Full HD (1080p), daí o Plex vai transcodar de H.264 4K pra H.264 1080p, por exemplo. Por isso falo que é mais complicado do que parece.

DETALHE IMPORTANTE: Recentemente fiquei confuso ao tocar alguns dos meus videos. Eu tenho o melhor hardware, tanto pro servidor de Plex, com aceleração via hardware, quanto Android TV pra tocar que é meu NVIDIA Shield Pro, quando rede cabeada, etc. Mas alguns videos ficavam engasgando. E no final o culpado não era hardware, nem configuração, nem nada disso, era a maldita legenda:

Quem já precisou baixar legendas, já deve ter visto o formato mais comum, que é o .SRT (SubRip). Alguns que se aventuraram mais, já devem ter visto outros formatos, como SSA (SubStation Alpha), TTML (Timed Text Markup Language), VTT (Web Video Text Track), VOBSUB, etc.

Sim, existe MUITO mais que SRT. Em particular, se você fizer como eu e ripar UHDs e extrair as trilhas de legenda do próprio disco, aplicativos como o MakeMKV podem baixar em formato VOBSUB (que é ok) ou o maldito PGS (Presentation Graphic Stream Subtitle Format).

A maioria das trilhas de legenda foram feitas pra serem enviadas ao tocador em paralelo, e separado, da trilha de video. Assim como a trilha de áudio vai separado. O tocador recebe trilha de video, trilha de áudio, e toca os dois sincronizados. Mesma coisa com trilha de legenda, no caso de arquivos SRT ou SSA ou TTML da vida.

Mas PGS é diferente: ele tem capacidades gráficas! Estou chutando, mas se já viu legenda coloridas, animadas, que se mexem ou se posicionam em locais absolutos na tela (como pra ficar exatamente em cima de outdoor no video, por exemplo), daí precisa haver um passo antes de rasterizar e renderizar essa legenda gráfica EM CIMA do stream de video. Isso existe um passo mais pesado de encoding, ou seja, vai ser PESADO de tocar em tempo real.

A solução: use o Plex pra pesquisar uma nova legenda, em formato SRT, e ignore a legenda PGS. Só de fazer isso, parou de engasgar na hora de tocar.

Seerr (o antigo Overseerr)

Só com o Sonarr e Radarr, mais os indexers do Prowlarr, já é suficiente pra procurar e baixar tudo. Mas tem um outro app que facilita muito a parte de descobrir coisa nova pra baixar. Ele se chama Seerr, e é a evolução do que antes era o Overseerr. O projeto do Overseerr se juntou com o Jellyseerr, o fork que atendia Jellyfin, e os dois viraram um só: o Seerr, que agora serve Plex, Jellyfin e Emby no mesmo lugar. Se você ainda ouve falar em “Overseerr” por aí, é isso aqui.

Ele vai em bancos de dados online gratuitos (tipo os IMDB) da vida e fica de olho em tudo que sai de novo, tudo que está em “trending”. Se eu quero achar alguma coisa nova, é uma boa. Mesmo coisas que já sei o que quero, basta pesquisar no Seerr e clicar em “Request”:

Eu configuro a integração com o Sonarr e o Radarr nas configurações, assim ele sabe pra quem mandar a requisição. Funciona tudo integrado. Só preciso usar a interface do Seerr pra pedir as coisas e posso esquecer do Sonarr e do Radarr rodando em background.

Bazarr (legendas)

Eu não preciso, mas minha namorada às vezes prefere assistir com legendas em português. E é um saco isso porque nem sempre tem, ou o que tem é de baixa qualidade. Aliás, deixa eu já avisar que tanto legenda oficial quanto não-oficial, eu tô cansado de ver tradução errada. Minha diversão é ficar achando os erros na legenda. Se você depende de legenda, saiba que muitos significados importantes estão errados mesmo. Sempre prefira original.

Antigamente tinha que ir manualmente em sites como OpenSubtitles.org da vida, baixar o arquivo “.SRT”, renomear igual o nome do arquivo de video e ficar testando manualmente pra ver se tá sincronizado ou não.

Existem dois jeitos de resolver isso. Um é pelo próprio Plex, que tem a opção de pesquisar legendas em diversas línguas e ficar testando direto da interface do tocador. Facilita bastante porque pula o passo de ter que ficar no PC, manualmente baixando arquivos. Como expliquei na seção anterior, no meu caso, que a legenda dos backups de UHD foram extraídos no formato PGS, eu preciso buscar no formato SRT pra não engasgar na hora de tocar.

Outra forma é tentar baixar as legendas automaticamente antes. Isso não é perfeito porque existem diversas versões de legendas, algumas foram feitas pra DVD, outras pra BluRay, alguns até pra versões mais populares de “CAM” que são torrents de videos gravados direto no cinema com um smartphone, que é a versão mais porcaria de todas.

É muito importante renomear os arquivos de video no formato certo, com os metadados bem organizados, como explicado no fórum de Reddit que mencionei no começo do artigo. Isso ajuda o Bazarr a casar a legenda certa com o arquivo certo. E já avisando: Português do Brasil é uma das línguas que menos tem legenda. É mais fácil achar em Francês, Italiano ou Russo do que em Português.

Pra facilitar isso temos o serviço Bazarr:

Na configuração do Bazarr, vamos apontar pros nossos serviços locais de Sonarr e Radarr, assim ele fica sabendo toda vez que aparece episódio novo de série ou algum filme novo, e já agenda pra tentar procurar a legenda:

O principal é configurar os Providers, que são os sites de onde vêm as legendas. É aqui que mora a diferença entre “não acha nada” e “acha quase tudo”. Os cinco que me dão o melhor resultado são: opensubtitlescom, tvsubtitles, yifysubtitles (só filme), animetosho (pra anime, nem precisa de conta) e gestdown (um proxy do Addic7ed pra inglês, também sem conta). Uma pegadinha que me custou horas: o provider OpenSubtitles.com pede o seu nome de usuário, não o email. Se você botar o email, ele dá erro de “você não pode consumir este serviço”, e ainda te deixa de castigo por 12 horas mesmo depois de corrigir.

Pra subir o serviço, no docker compose, temos este trecho:

  bazarr:
    image: ghcr.io/linuxserver/bazarr:latest
    restart: unless-stopped
    environment:
      - TZ=America/Sao_Paulo
      - PUID=1000
      - PGID=1000
    volumes:
      - /mnt/terachad/Videos/radarr:/movies
      - /mnt/terachad/Videos/sonarr:/tv
      - /home/akitaonrails/bazarr/appdata/config:/config
    ports:
      - '6767:6767'

Aqui precisamos mapear as pastas do radarr e sonarr pra ele saber onde gravar as legendas. Um detalhe que trava muita gente: mapeie exatamente as mesmas subpastas que o Radarr e o Sonarr usam (no meu caso, /movies e /anime), senão o Bazarr fica reclamando que “não acha o arquivo de video pra analisar” na biblioteca inteira.

O último passo, e o que fez o Bazarr finalmente virar útil pra mim, é o perfil de idioma. Criei um perfil “Português do Brasil com inglês de reserva”: ele lista pb primeiro e en depois, com o corte (cutoff) no pb. Na prática, o Bazarr procura as duas, baixa a que aparecer primeiro, e considera o item resolvido assim que existe uma legenda em português. Se o pt-BR nunca aparecer, o inglês fica de backup.

E o pulo do gato, que me custou caro: todo item precisa ter um perfil de idioma atribuído. O Bazarr ignora, calado, qualquer filme ou série sem perfil. Quando fui conferir, tinha 140 séries e 201 filmes sem perfil nenhum, sendo ignorados em silêncio desde que entraram na biblioteca. Marcar o perfil como padrão só cobre o que você adiciona dali pra frente; pra biblioteca que já existe, tem que atribuir o perfil em massa, de uma vez, pra tudo que já está lá.

Tem ainda um problema irmão desse, só que do lado do áudio. De vez em quando o Sonarr ou o Radarr baixam um release cujo único áudio é uma dublagem estrangeira: um italiano, um francês, um russo. E nenhuma legenda salva áudio errado. Pra isso eu uso um Custom Format nos dois, o “foreign-language-only”, que reconhece marcadores de dublagem estrangeira (ITALIAN, FRENCH, RUS, GERMAN e por aí vai) e dá uma pontuação de -500, o que faz o release ser recusado já na busca. Um detalhe que aprendi na marra: um release russo veio com o título todo em cirílico, sem nenhum “RUS” em letra latina, e passou batido. Então o filtro também precisa pegar qualquer caractere cirílico.

Depois que arrumei os providers, passei a biblioteca inteira pra esse perfil e liguei esse filtro de áudio, o Bazarr deixou de ser o serviço mais inútil da minha stack e virou um que resolve a maioria dos casos sozinho. Quando ainda falta, aí sim eu caço na mão pelo Plex, mas hoje é exceção. Só lembrando o que já falei: legenda em português do Brasil é das mais escassas que existem, então mesmo com tudo certo, às vezes não tem mesmo.

Lidarr (Música)

Eu não sou muito de música. Tenho uns MP3 que baixei décadas atrás e, no dia a dia, toco a playlist de Top 50 do Spotify e tá bom. Mas a mesma lógica do Sonarr e do Radarr vale pra música, então acabei montando também: o serviço se chama Lidarr.

Ele cataloga seus artistas, cruza com bancos de dados de discografia e vai atrás dos álbuns que faltam, marcando cada artista como “Monitored” pra buscar lançamentos novos sozinho, do mesmo jeito que o Sonarr faz com episódio de série. No print acima dá pra ver minha biblioteca com tudo em “Lossless”, que é o perfil de qualidade que eu configurei.

No docker compose é o mesmo padrão dos outros:

  lidarr:
    image: ghcr.io/linuxserver/lidarr:latest
    restart: unless-stopped
    depends_on:
      - qbittorrent
    environment:
      - TZ=America/Sao_Paulo
      - PUID=1000
      - PGID=1000
    volumes:
      - /home/akitaonrails/lidarr/appdata/config:/config
      - /mnt/terachad/Music:/music
      - /mnt/terachad/Downloads/torrents:/downloads
    ports:
      - '8686:8686'

A configuração é idêntica em espírito à do Radarr e Sonarr. Em Settings e Download Clients eu registro o mesmo QBitTorrent, mas usando uma categoria própria chamada lidarr, pra ele não misturar os downloads de música com os de filme e série. A pasta raiz da biblioteca aponta pra /music, e o perfil de qualidade dá pra deixar aberto (o “Any”, que pega o que aparecer) ou travar em “Lossless” quando você só quer FLAC, que é o meu caso.

E o melhor: os indexers eu não configuro na mão. O Prowlarr, que eu expliquei lá em cima, também cadastra o Lidarr como aplicação e sincroniza sozinho os indexers que têm categoria de música. É o mesmo “Sync App Indexers” que ele faz pro Sonarr e Radarr, agora pra música também.

Pra ouvir, o próprio Plex já toca música: basta criar uma biblioteca do tipo Music apontando pra essa pasta, e no celular o app Plexamp é ótimo só pra isso. E, do mesmo jeito que tenho o Kavita como “Plex pra mangá”, pra música ainda dá pra usar o Navidrome, um servidor de streaming open source tipo um Spotify particular, que indexa a mesma pasta /music (só leitura) e tem vários apps de celular compatíveis. O Lidarr baixa e organiza, o Navidrome ou o Plex servem.

Outros Serviços

No meu repositório tem outros arquivos de Docker Compose pra minha infra local. Não vou explicar em detalhes, mas só a saber:

Pra bloquear banner, ad, rastreador e até site de malware na rede toda, eu uso DNS filtrado. Durante muito tempo rodei um Pi-Hole local pra isso, que é um servidor de DNS caseiro com bloqueio embutido. Funciona muito bem, mas dá manutenção. Hoje eu troquei por um serviço hospedado, o NextDNS, que faz o mesmo bloqueio de ads, rastreadores e malware, só que sem eu precisar manter servidor nenhum, e já vem com DNS criptografado de fábrica.

E por que DNS criptografado importa? Query de DNS, por padrão, é um protocolo de texto aberto. Seu provedor sabe exatamente tudo que você navega. Eu prefiro não dar esse dado de graça pra eles. Com o NextDNS as consultas saem encriptadas e ainda passam pela lista de bloqueio que eu escolho. Não substitui um anti-virus, mas dificulta bastante que terceiros montem uma impressão digital dos meus hábitos de navegação, e dá bem menos trabalho que o Pi-Hole que eu mantinha antes.

Agora, no arquivo kaizoku-docker-compose.yml tem outro serviço tipo Sonarr pra TV, Radarr pra filmes, que é o Kaizoku pra mangá. Se você lê mangá online, já deve ter visto muitos sites sendo fechados por causa de copyright, direitos autorais e tudo mais. Eventualmente, os mangás online que você leu, vão desaparecer. Com o Kaizoku podemos preservar eles localmente também.

O Kaizoku é só pra baixar. Pra ler, precisamos de um leitor, da mesma forma que temos Plex pra video, temos Kavita Reader pra ler os mangás baixados. Assim como Plex, basta na primeira configuração apontar pra pasta onde o Kaizoku baixa tudo, daí o Kavita vai se virar pra organizar a biblioteca, baixar capas e outros metadados. É literalmente o Plex pra Mangá.

Ainda não explorei muito esse serviço. Ou ainda tem coisas pra refinar nele, ou eu que não sei configurar direito, mas nem tudo baixa capas direito. Vejam como não está bonito. Se tiverem dicas sobre Kavita e Kaizoku, não deixem de compartilhar abaixo.

Pra ler em si, é bem parecido com um Kindle Web ou outros sites online de mangá. Dá pra ler página a página, ou “scrollar” o capítulo inteiro, ele vai lembrar onde você parou e coisas básicas assim. Pode ser um bom projeto pra contribuir, se tem vontade de treinar com código aberto.

Conclusão

Fico muito contente com o estado atual dos serviços de compartilhamento de arquivos. Não percam muito tempo pensando demais. Só instalem e se divirtam. O código de tudo é aberto, se você é programador, vá lá fuçar o código e aprender algo novo, e quem sabe, até contribuir.

Eu não sou adepto de teorias apocalípticas, teorias da conspiração, nem nada assim. Eu só considero que, o que eu não tenho controle físico, eu não tenho. Se o que “é meu” está no controle de um terceiro, então “não é meu”. Esse é o princípio. Eu quero tudo que é meu sob meu único e exclusivo controle e pronto. Não importa se é menos conveniente, não importa se é mais caro. É uma questão de princípios: meu é meu e ponto final.

Além disso, nas plataformas de streaming, não existe tudo. Muita coisa de décadas passadas simplesmente foram apagadas da memória. Muitos nem lembram mais, especialmente quem não viu na época. Eu tenho nostalgia por programas de TV, filmes, que não existe online. Muitos sequer existem em mídia física. Tem filmes que depois de VHS nem chegaram a sair em DVD. Tem DVD que nunca saiu como Blu-Ray. Tem coisa em disco físico que nunca vai sair em streaming. Tem coisa em streaming que vai ser apagado em breve, e muitos nem vão notar.

O que é meu, é meu. Podem apagar o quanto quiserem. O que é meu, ninguém apaga. Se você tem apreço pelo que é seu, comece a explorar estas opções. Não precisa ser um setup gigante como o meu. Qualquer HD externo sobrando já dá pra começar. Comece pequeno, vá aumentando aos poucos. Eu coleciono essas coisas faz décadas! Não comecei hoje.

Não podia terminar o ano com pendências, então eis a parte final da Saga da Rinha de Backend. Neste video vou aproveitar os temas da rinha pra demonstrar em mais detalhes como configurar um Docker Compose de verdade, como funciona testes de carga com Gatling, como usar esses dados pra configurar coisas como o Postgres melhor. Também vamos ver como avaliar exatamente quanto pesa rodar SQL num Postgres, como determinar coisas com tamanho de pool de conexões e muito mais!

Hoje é dia de aprender ferramentas que todo programador deveria mesmo saber no dia a dia de projetos de verdade.

Capítulos

• 00:00:00 - Intro
• 00:01:03 - CAP 01 - Minhas Pendências da Rinha - Como Começar?
• 00:03:28 - CAP 02 - Entendendo Docker Compose - PHP do Lauro
• 00:07:38 - CAP 03 - Aprendendo a Lidar com Poucos Recursos - Configurando NGINX
• 00:15:33 - CAP 04 - Gargalos de Docker - Network Mode: Host
• 00:21:41 - CAP 05 - Prefira Docker em Linux - Problemas em Mac e Windows?
• 00:26:51 - CAP 06 - Algumas Dicas de Docker Compose - Node do Lucas Weis
• 00:30:21 - CAP 07 - Básico de Testes de Carga - Gatling
• 00:44:26 - CAP 08 - Comparando com Network Mode HOST - Faz diferença??
• 00:52:53 - CAP 09 - Entendendo PostgreSQL - Banco era Gargalo??
• 01:01:12 - CAP 10 - Full Text Search no PostgreSQL - Faz diferença??
• 01:07:35 - CAP 11 - Estratégia de SQL com EXPLAIN ANALYZE - SQL por baixo dos panos
• 01:16:11 - CAP 12 - Quantas Conexões Configuro no Banco? - Medindo com pgAdmin
• 01:23:34 - CAP 13 - Discutindo sobre Linguagens - Kotlin e Crystal
• 01:31:05 - CAP 15 - Como Linguagens afetam Recursos do Banco? - Só a saber, sobre threads vs fibers
• 01:35:00 - Bloopers

Links

• Repositório Oficial da Rinha
• GitHub Versão Node.js do Lucas Poole
• GitHub Versão PHP do Lauro Appelt
• GitHub - akitaonrails/rinhabackend-rails-api
• Docker Network Mode Host
• Gatling
• Vegeta
• HAProxy - The Reliable, High Perf. TCP/HTTP Load Balancer
• Envoy proxy - home
• Reverse proxy quick-start — Caddy Documentation (caddyserver.com)
• GitHub - jesseduffield/lazydocker: The lazier way to manage everything docker
• How to Insert Bulk Data in PostgreSQL - CommandPrompt Inc.
• pgAdmin - PostgreSQL Tools
• Spring Initializer
• Kotlin Programming Language (kotlinlang.org)
• The Crystal Programming Language (crystal-lang.org)
• Lucky - Web framework for Crystal (luckyframework.org)
• O que é a pilha ELK? | Explicação sobre a pilha Elasticsearch, Logstash, Kibana | AWS (amazon.com)
• O que é Elasticsearch – Explicação sobre o mecanismo Elasticsearch – AWS (amazon.com)
• Redis and Memcached-Compatible Cache – Amazon ElastiCache – Amazon Web Services
• Apache Kafka totalmente gerenciado | Amazon MSK | Amazon Web Services
• Working with read replicas for Amazon RDS for PostgreSQL - Amazon Relational Database Service
• Improve database performance with connection pooling - Stack Overflow
• How Postgres Makes Transactions Atomic (brandur.org)

SCRIPT

Olá pessoal, Fabio Akita

Antes de ir pro assunto de hoje, só confirmando que sim, o último video foi um experimento de fazer um episódio totalmente gerado por IA. Maioria sacou, mas muitos demoraram bastante ou nem se tocaram. Mas não se preocupem, foi só uma vez pra ver como fica. Não é nem um pouco prático fazer videos via ferramentas de IA como o HeyGen. Eu expliquei o processo na descrição do video, que vocês sempre pulam. Então leiam lá.

Assunto de hoje, finalmente, vai ser a prometida Parte 2 da Rinha de Backend. Sim, o video das 16 Linguagens em 16 dias foi lançado em Setembro e eu prometi uma parte 2. Estamos em dezembro, quase virando o ano e só agora estou soltando. Mas é assim que este canal funciona: me deu vontade de falar de outras coisas antes.

Objetivo deste video é complementar algumas dicas e informações que podem auxiliar nos seus estudos. Em particular algumas das técnicas que diferenciam projetinho de tutorial de projeto de verdade. Então, vamos lá …

(…)

Um dos motivos de porque demorei tanto pra fazer esse episódio é por causa destes dois itens que eu tinha colocado pra falar neste episódio: Resolvendo a Rinha em 5 minutos e O que é um framework web? Esses dois itens seriam um video inteiro de 2 horas e sinceramente, não estou com paciência pra esse tema porque já tem documentação suficiente online. Abra o site de qualquer framework web, seria o primeiro tutorial de como usa. Eu só estaria repetindo o que já existe online. Em vez disso vou só resumir alguns pontos principais.

Resolvendo a Rinha em 5 minutos. Sim, eu poderia fazer um speed run e editar um video demonstrando passo a passo como fazer uma versão das APIs. Eu acho inútil. Speed run de código só pra mostrar que sei fazer, realmente não me motiva. É óbvio que eu sei fazer. Flex desnecessário. Aliás, o video de 16 linguagens em 16 dias já foi flex o suficiente.

Se você é iniciante e tem dificuldade de resolver esse exercício, obviamente ainda falta estudar mais e treinar mais. O que eu sempre repito? Não existe uma única forma de resolver um problema de código. Não existe um único passo a passo de tutorial ou curso que consiga cobrir todas as permutações. O que vocês tem que fazer? Abrir o GitHub do evento e ir no diretório de participantes. Por isso achei este evento interessante: pela quantidade de versões diferentes que os participantes publicaram pra resolver o mesmo problema.

Vou dar um exemplo. Fiz clone do repositório principal da rinha na minha máquina. Peguem o link na descrição abaixo. Indo no diretório de participantes, temos 94 versões. Eu analisei a maioria delas no outro video, depois assistam lá. Mas digamos que esteja estudando PHP e queira ver como se resolve esse problema em PHP. A partir do diretório de participantes, só abrir um terminal e digitar grep "php" */README.* e olha só, aparecem 4 sub-diretórios, dois do Lauro Appelt e dois de um tal de Predator. No video anterior eu expliquei uma das versões do Lauro, que é feito em Hyperf com Swoole.

Vamos abrir o README de um dos diretórios e olha só, temos o link do repositório com o código em PHP do Lauro. Podemos clonar em qualquer outro lugar e fuçar pra ver como foi que ele implementou a versão dele. A parte mais interessante desse evento, é que um dos requerimentos foi pra todo participante criar Dockerfiles e Docker Compose pra tudo. Então é super fácil de executar, sem precisar adivinhar como configurar o ambiente pra cada projeto.

Hoje em dia eu considero de boa educação, boa etiqueta, que todo projeto, não importa quão pequeno ou quão grande, sempre deve ter um Dockerfile e um docker-compose. O Dockerfile demonstra como fazer pra rodar sua aplicação e o docker compose demonstra como subir as dependências desse projeto, como banco de dados. Vamos olhar o Dockerfile do projeto do Lauro.

Primeiro, ele inicia baixando uma imagem preparada pelo pessoal do framework Hyperf, que já trás tudo que você vai precisar. Em seguida, faz algumas configurações de timezone. Maioria das imagens boota com tempo UTC de Greenwich, timezone zero, como padrão. Pra ter os horários corretos da sua região geográfica, precisa colocar algo como “America/Sao_Paulo”, sempre. Ninguém vai adivinhar.

FROM hyperf/hyperf:8.2-alpine-v3.18-swoole

ARG timezone

ENV TIMEZONE=${timezone:-"America/Sao_Paulo"} \
    APP_ENV=prod \
    SCAN_CACHEABLE=(true)

Esse trecho seguinte grandão aqui é opcional e eu não testei o suficiente pra saber se era ou não necessário pra melhorar os tempos do benchmark. Tudo que ele está fazendo é criando um arquivo de variáveis de configuração, pra mexer em configurações como tamanho máximo de upload, que é desnecessário neste projeto, ou limite de memória, que talvez possa ser útil ou não, não medi pra saber.

RUN set -ex \

    && php -v \
    && php -m \
    && php --ri swoole \

    && cd /etc/php* \

    && { \
        echo "upload_max_filesize=128M"; \
        echo "post_max_size=128M"; \
        echo "memory_limit=1G"; \
        echo "date.timezone=${TIMEZONE}"; \
    } | tee conf.d/99_overrides.ini \

    && ln -sf /usr/share/zoneinfo/${TIMEZONE} /etc/localtime \
    && echo "${TIMEZONE}" > /etc/timezone \

    && rm -rf /var/cache/apk/* /tmp/* /usr/share/man \
    && echo -e "\033[42;37m Build Completed :).\033[0m\n"

Não saia copiando e colando achando que vai automaticamente melhorar alguma coisa. Vá na documentação e entenda item a item daqui. Daí rode uma versão sem isso, e outra versão com isso, rodando o mesmo benchmark, daí compare se faz alguma diferença. O fato de coisas que não importam pra este desafio, como tamanho máximo de upload, me diz que o Lauro copiou o Dockerfile de exemplo no site da imagem desse Hyperf, e colou aqui.

Finalizando, adicionamos drivers de postgres pra PHP, mudamos o diretório de trabalho pra /app, que é pra onde vamos copiar os arquivos do projeto na sequência. O que eu achei estranho é que não tem um último comando de ENTRYPOINT indicando como rodar a aplicação, também senti falta de rodar “composer install” pra baixar as bibliotecas. Isso é uma peculiaridade desta versão do Lauro, guardem isso que já já explico porque tá faltando.

RUN set -ex \
    && apk --no-cache add \
    && apk add php82-pdo_pgsql

WORKDIR /app

COPY . /app

Agora vamos ver o docker-compose.yaml. Docker compose é a descrição de uma mini-infraestrutura. Do que instalar, configurar e subir Redis, Postgres, Nginx, tudo na mão, podemos automatizar tudo num único comando. É muito mais fácil pra um novo desenvolvedor que entra no seu projeto, aprender como as coisas funcionam, se tiver um docker compose já pronto. Funciona com uma documentação viva da infra do projeto. É de bom tom, todo projeto de verdade, ter docker compose configurado que funciona.

Nunca fez um docker compose na vida? Como faz? Simples, começa pegando qualquer um dos 90 e tantos exemplos que tem neste evento como base. Vamos abrir o do Lauro e ir de baixo pra cima. Olha só, já sabemos que esse projeto depende de Redis estar de pé. Esse nome “redis” na primeira linha é qualquer nome que quiser. Por convenção colocamos o nome do que vamos rodar, mas poderia ser “cache_server” ou algo assim.

    redis:
        container_name: rinha-backend-redis
        image: redis:latest
        command: redis-server --save "" --appendonly no --maxclients 20000
        network_mode: host
        deploy:
            resources:
                limits:
                    cpus: '0.1'
                    memory: '0.2GB'

A única linha obrigatória mesmo é o nome da imagem. Docker, por padrão, vai baixar tudo de dockerio.com. Se quiser baixar de outro lugar, tem que colocar a URL inteira, senão só o nome e a versão da imagem é suficiente. Aqui está “latest”, que é a versão mais recente. Não gosto de usar latest porque se amanhã mudar a versão, e sua app não foi adaptada e teve mudanças que quebram compatibilidade, seus desenvolvedores vão começar a ter problemas. Se forem muito júniors, não vão associar que foi porque mudou a versão do redis e por isso as coisas quebraram do nada. É melhor colocar a versão fixa, como 7.2.3-alpine3.19, que significa Redis versão 7.2.3 rodando em cima da distro Alpine versão 3.19.

As outras opções são específicas da Rinha, em particular os limites de recursos na seção de deploy. Esse foi um dos critérios, que achei inteligente. Tínhamos no máximo 1.5 CPUs e 3 Gigabytes de RAM pra usar. À primeira vista, parece muito pouco. Não é fácil de imaginar como esses recursos encaixam em cada componente. Se você é um iniciante e tem uma máquina fraca, já aprendeu a ter que lidar com isso: como faz pra tirar o máximo proveito do seu Dual Core com 2 gigabytes de RAM? Todo programador que ficou bom, começou tendo que fazer rodar programas pesados em máquinas fracas.

Se você é um iniciante e já começou com oportunidade de usar máquinas novas e parrudas pra trabalhar, qualquer coisa acima de um quad core, acima de 8 gigabytes de RAM, tipo um Macbook da vida, e não teve que lidar com máquinas fracas, cuidado. Você vai pode acabar ficando complacente, preguiçoso. Vai achar que o mundo é igual sua bolha: que tem CPU sobrando, que tem RAM sobrando, e nunca vai entender o valor de otimizar as coisas. Pra que otimizar? Se tá tudo sobrando? Na hora que ficar difícil, você vai ser o tipo que desiste fácil.

Por isso eu repito que na minha teoria de Aprendendo a Aprender, tem que ter a Dor de Aprender. Não importa se você cai, importa como se levanta. Não importa quantas vezes cai, importa que toda vez se levanta mais rápido. Quem nunca sentiu dor, nunca aprendeu nada. E nesta rinha, a versão disso é essa limitação de recursos, senão, claro, o participante com uma máquina como a minha, com 64 giga de RAM, Ryzen 9 de 32 threads, facilmente conseguiria gerar resultados com números muito melhores que todo mundo. Mas com esse limite, o participante com um quad core de 4 giga de RAM poderia ultrapassar minha máquina, se soubesse administrar melhor os recursos limitados.

E isso de limitar recursos no Docker, não foi feito pra concursos. Foi feito pro caso de alguém realmente precisar rodar dois processos numa mesma máquina, e caso um deles seja fominha demais e consuma recursos demais, não deixar o outro processo morrendo de fome. Se o servidor tem 4 giga de RAM, eu subo dois programas, cada um no seu container de docker. Digamos que o primeiro resolva alocar toda a memória disponível, mesmo que não vá usar. Daí quando o segundo container tentar rodar, vai crashear, por falta de recursos.

Existem processos que alocam mais memória do que deveriam? Sim, por exemplo, um Node.js tem recurso de cluster, que eu mencionei no episódio anterior. O que muita gente faz? Vai no Google pesquisar e só copia um trecho parecido com esse de algum stackoverflow da vida. Esse script roda “os.cpus.length” e vê que sua máquina tem 4 cores, ou seja, 4 cpus, então faz 4 forks da aplicação. Cada fork pode ocupar, digamos, meio gigabyte. Então 4 forks daria 2 gigabytes. Como sua máquina tem 8 gigabytes, você nem se preocupa. Funciona tudo direitinho.

const numForks = require('os').cpus().length || 4;

if(cluster.isPrimary && process.env.CLUSTER === 'true'){
    logger.info(`index.js: Primary ${process.pid} is running`);

    for (let i = 0; i < numForks; i++) {
      cluster.fork();
    }

Aí você aloca um servidor num cloud qualquer, com 8 giga de RAM. Mas resolve pegar um CPU potente, de 16 cores. Seu script de cluster vai ver 16 cpus e subir 16 forks. Cada fork ocupando meio giga de RAM. Ou seja, vai ocupar todos os 8 giga de uma só vez. E você não tem 8 giga sobrando, seu sistema operacional e outros serviços ocupam RAM. Alguns desses forks vão crashear logo no boot.

O certo é consertar esse script e trocar a chamada de os.cpus e usar uma variável de ambiente no lugar. Assim podemos declarar essa variável, como CLUSTER_WORKERS, no yaml do docker compose, e ter controle sobre quantos processos realmente vai subir. Como desenvolvedor você sempre precisa ter controle sobre o que exatamente vai rodar, quantos recursos vai usar. Um bom jeito de se exercitar é acertando script de docker compose.

const numForks = Number(process.env.CLUSTER_WORKERS) || 4;

Continuando, depois do redis tempos nginx. Esse foi outro pré-requisito nas instruções da rinha: ter um proxy reverso pra servir de balanceador de carga entre, no mínimo, duas instâncias da sua aplicação. Quando um estudante segue um tutorial de web qualquer, ele só entende que tem um único processo, o servidor da aplicação. Sobe numa porta como 4000 e no navegador coloca localhost:4000 e pronto, acabou.

    nginx:
        container_name: rinha-backend-nginx
        image: nginx:alpine
        volumes:
            - ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf
        network_mode: host
        depends_on:
            - api-01
            - api-02
        deploy:
            resources:
                limits:
                    cpus: '0.1'

Esse é o nível zero no aprendizado. O nível logo acima desse hiper básico, tem que aprender que em projetos de verdade, subimos múltiplos processos em paralelo, seja na mesma máquina, seja em múltiplas máquinas. Se for na mesma máquina, um sobe na porta 3000, outro na porta 3001, outro na 3002. Em qualquer dos casos, sempre colocamos um balanceador de cargas na frente, na forma de um proxy reverso. Explico isso no episódio “Tornando sua Web App Mais Rápida”.

Alguns mais experientes poderiam criticar a escolha de NGINX, sendo que existem ou programas mais especializados pra isso como HAProxy ou mais modernos como o Envoy ou Caddy. Mas de jeito nenhum é uma escolha ruim, especialmente porque é um dos que tem mais documentação, é simples de usar, e pra esta rinha, está mais que bom. Nesta seção de docker compose temos duas coisas importantes, a primeira é a imagem. No caso estamos usando a versão de Alpine, que é uma das mais leves. Mais importante é o mapeamento de volume.

Precisamos mapear o arquivo de configuração que fica no nosso projeto do lado de fora, para que o container tenha acesso quando bootar. Lembrem-se, um container é só uma forma de mentir pro processo que roda dentro, pra ele achar que está sozinho, numa máquina vazia. Ele não enxerga nenhum arquivo de fora se nós não declararmos pra dentro, da seguinte forma.

volumes:
	- ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf

O que tem nesse arquivo de configuração? Vamos dar uma olhada. Se nunca viu, parece complicado, mas vamos por partes. Esta primeira parte do topo tem a ver com a escalabilidade do serviço. Nginx funciona numa arquitetura de master e workers. Esse “worker_processes” como “auto” de automático quer dizer que ele vai avaliar quantas cpus sua máquina tem e subir 1.5 vezes. Então, se tiver 4 cpus, ele vai subir 6 workers.

worker_processes auto;

Por que não 1 worker por 1 cpu? Primeiro, uma cpu não é exclusiva de 1 processo. Quem controla qual processo vai rodar em qual cpu durante um período x de tempo, é o scheduler da kernel. Se seu processo é leve e precisa de pouco tempo pra fazer o que precisa, não tem porque bloquear uma cpu inteira só pra ele. Dá pra dividir com outros processos. Depois assista meus episódios sobre concorrência e paralelismo pra entender como schedulers funcionam.

Em seguida temos worker_connections como 4096. Isso indica quantas conexões simultâneas cada worker vai tentar aguentar. Não confunda conexões simultâneas com processamento paralelo. Se realmente vier 4096 requisições web, exatamente no mesmo instante, esse parâmetro só significa que o worker vai aceitar as 4096 conexões, mas uma boa parte vai ficar esperando numa fila, até ser atendido. Se demorar mais do que certo tempo, que podemos configurar, ele pode rejeitar e devolver erro de timeout. Como o nome diz, erro de tempo expirado.

events {
    worker_connections 4096;
}

No primeiro episódio que fiz da rinha eu expliquei como muitos ficaram tentando mexer nesse número meio que no chute. Só o Leandro, que fez a versão em Ruby, entendeu que o truque não era aumentar esse número e sim diminuir. Eu explico o raciocínio no outro video, então não deixem de assistir depois.

O Nginx é só o tirador de pedidos, lembram da analogia do caixa de restaurante fast food? Ele tira os pedidos, mas quem realmente executa, os cozinheiros, são estes servidores declarados nesta seção upstream. No caso apontando pra localhost, portas 9501 e 9502. Se já mexeu com docker compose antes, isso poderia parecer um pouco estranho.

http {
    access_log off;
    error_log /dev/null emerg;

    upstream api {
        server localhost:9501;
        server localhost:9502;
        keepalive 400;
    }

Normalmente, pra subir um nginx via docker compose, eu teria uma configuração mais ou menos assim: declararia dois serviços web, as instâncias da minha aplicação, como app1 e app2. Ambos carregando na porta 8080. Daí, na configuração do nginx, essa seção upstream estaria apontando pra app1 porta 8080 e app2 também porta 8080.

Mas como que dá pra ter dois serviços subindo na mesma porta? Não tem conflito? E não tem, porque na prática é como se cada container representasse um servidor externo separado. E sua aplicação está carreagando num servidor fora, só que virtual. Daí, cada servidor tem uma porta 8080 livre. Cada instância pode se pendurar na porta 8080 do seu respectivo “servidor virtual”. Acontece que o nginx e esses servidores virtuais se comunicam na mesma rede, também virtual, daí o nginx consegue fazer o balanceamento entre esses dois serviços.

No episódio anterior eu expliquei a descoberta que alguns de nós fizemos durante nossos experimentos, o Vinicius Ferraz fez a descoberta de que se usarmos o modo de rede de ponte virtual, que é o padrão, isso introduzia um gargalo pesado e os resultados dos benchmarks ficavam bem errados. Mas se colocarmos o modo de rede pra host, ou seja, sem virtualizar a rede, aí os tempos finalmente ficam corretos.

Não sei se notaram, mas na configuração do redis que mostrei antes, ou nesse de nginx, note que ambos já tem a opção network_mode igual a host, indicando que é pra pendurar o container nas portas da rede de verdade do sistema operacional nativo. Nesse modo não podemos pensar que temos “servidores virtuais separados” mas sim que estamos subindo realmente tudo na mesma máquina, na rede de verdade. Portanto, precisamos nos preocupar com conflitos de portas. Por isso no upstream do nginx, apontando pra dois servidores em localhost, cada um deles precisa estar numa porta diferente, 9501 e 9502.

É muito importante entender o que é modo de rede ponte e a diferença com modo de rede host. Estudem se não sabiam disso. Mas já que falamos do servidor de aplicação. Note que na configuração do nginx, tem esse seção de depends_on. Ele quer dizer: só suba o serviço nginx quando detectar que os serviços api-01 e api-02 estejam de pé. Então vamos pular pro começo do arquivo do docker compose, pra ver como essa aplicação está configurada.

services:

    #api1
    api-01:
        container_name: rinha-backend-api-01
        build:
            context: .
            dockerfile: Dockerfile
        environment:
            HTTP_PORT: 9501
            APP_NAME: skeleton
            APP_ENV: dev
            DB_DRIVER: pgsql
            DB_HOST: localhost
            DB_PORT: 5432
            DB_DATABASE: rinha-backend-db
            DB_USERNAME: rinha
            DB_PASSWORD: postgres
            REDIS_HOST: localhost
            REDIS_PORT: 6379
        volumes:
            - ./:/app
        depends_on:
            - db
            - redis
        command: bash -c "php bin/hyperf.php start"
        network_mode: host
        deploy:
            resources:
                limits:
                    cpus: '0.4'
                    memory: '0.3GB'

Precisamos dar um jeito de configurar a mesma aplicação duas vezes, como api-01 e depois como api-02 e, como estamos usando modo de rede host, precisamos declarar portas direrentes pra cada uma, que normalmente fazemos via variáveis de ambiente, como esse HTTP_PORT logo no começo. O jeito mais fácil é configurando esse bloco de configuração do serviço api-01 e depois fazendo um copy e paste embaixo pra ser o api-02, só mudando o HTTP_PORT pra 9502.

Existem outras formas de fazer isso. Como exemplo, que pegar o docker compose do projeto de Node.js do Lucas Poole, porque ele ainda está usando o modo de rede padrão, via ponte virtual, daí não precisou se preocupar em configurar portas diferentes, só precisou fazer hostnames diferentes. Vamos dar uma olhada.

services:
  app1: &app
    # image: lukas8219/rinha-be-2023-q3:latest
    build: .
    hostname: app1
    environment:
      DB_URL: "postgres://postgres:12345678@postgres:5432/postgres"
      DB_POOL: 35
      PINO_LOG_LEVEL: "debug"
      REQ_TIMEOUT: "2000"
      NODE_ENV: production
      CLUSTER: true
      CLUSTER_WORKERS: 5
    expose:
      - "8080"
    depends_on:
      - postgres
    ulimits:
      nproc: 1000000
      nofile:
        soft: 1000000
        hard: 1000000
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: '0.6GB'
  app2:
    <<: *app
    hostname: app2

Ele declarou o serviço de nome “app1” e em seguida anexou uma etiqueta com esse & comercial, chamando de “app”. Descendo pro próximo serviço no mesmo arquivo, observem, temos app2. E na linha seguinte é como se fosse um “include” ou “import”, dizendo pra copiar tudo que tinha no app1. A única coisa que muda é o nome do hostname. Entenderam? É assim que podemos reusar as mesmas configurações entre diferentes serviços. Isso é uma características de arquivos de configuração em formato YAML, não é coisa do docker compose. Qualquer outro programa que use YAML, dá pra fazer a mesma coisa.

Como falei antes, o projeto do Lucas não está usando o modo de rede host e sim o de ponte, por isso na configuração do app2, ele mantém o mesmo número de porta. Se fosse no modo host, precisaria declarar pelo menos um número de porta diferente, pra não conflitar no localhost. Se nunca viu isso antes, sei que pode ser confuso, mas se lembre dessa diferença entre ponte de rede virtual e rede host nativa.

A parte mais importante na configuração da nossa aplicação de API é este parâmetro “build”. Aqui está mais completo do que precisa. Bastaria ter escrito o valor “.”, mas o Lucas preferiu declarar o contexto como “ponto” e o arquivo como sendo “Dockerfile” mesmo, que é o padrão.

É aqui que ele vai usar o arquivo de Dockerfile que já vimos antes, pra construir a imagem pra este container. Todos os outros serviços, nós apontamos pra imagens já prontas no serviço do site Docker Hub. Aquelas imagens foram todas feitas com algum Dockerfile também. A diferença é que nossa aplicação não foi publicada no Docker Hub, estamos construindo ela aqui, então apontamos direto pro Dockerfile. No futuro, quando a aplicação estiver terminada, podemos dar upload da última imagem gerada e passar a apontar pra ela via parâmetro image em vez de build. No arquivo do Lucas, tem até comentado essa opção, porque pra participar da rinha, precisava ter publicado a imagem de verdade.

O Dockerfile do Lauro, que mostrei antes, usa de base a imagem do repositório do Hyperf e também incluímos coisas como o PDO de Postgres. Todos esses elementos podem ser configurados via variáveis de ambiente, que é o que estamos declarando na seção “environment”, como o HTTP_PORT, que indica em qual porta o servidor de Hyperf vai subir, ou DB_HOST ou REDIS_HOST que declara o nome do servidor que vai ter o banco de dados e o cache. Neste caso, em modo de rede host, vai ser tudo localhost.

No projeto do Lauro, quando fizemos as otimizações de performance que expliquei no outro episódio, ele fez alguns ajustes depois e preferiu não deixar tudo 100% automatizado. Lembram que falei que no Dockerfile dele estava faltando o comando ENTRYPOINT, que define que executável iniciar no container? Pra saber o que fazer, tem que ler o README dele. Ao subir o Docker Compose, os containers vão estar de pé, mas internamente quem vai rodar é este comando de “sleep infinity”, que é um truque só pro container ficar de pé e não morrer.

A razão disso foi porque ele não adicionou os próximos passos no Dockerfile, não sei por que, mas o README pede pra rodar manualmente, via “docker exec” o comando de “composer install” pra instalar as dependências. Como ele mapeia o diretório inteiro como “/app” pra dentro do container, se não me engano, “composer install” vai baixar e gravar as dependências no sub-diretório “/app/vendor”. Por isso tanto faz rodar em qualquer um dos dois containers, o outro vai enxergar automaticamente, já que compartilham do mesmo volume no disco.

Só depois de fazer isso que, via docker exec de novo, podemos rodar o hyperf em cada container, e vai subir direitinho. Durante desenvolvimento, dependências como bibliotecas de node, ou neste caso, do composer, não queremos deixar dentro da imagem, porque ocupam muito espaço e mudam o tempo todo. Seria trabalhoso toda vez reconstruir a imagem. O melhor é mapear um volume pra dentro do container e mandar instalar nesse volume. Só quando for gerar a imagem final pra publicar, aí sim, era bom mudar pra gravar as dependências dentro da imagem. Senão quem for baixar depois, vai precisar fazer isso manualmente, o que não é ideal.

Feito tudo isso, do terminal, basta subir tudo com “docker compose up”. Isso vai baixar as imagens que ainda não tem, construir essa da aplicação e subir tudo certinho, na ordem certa, graças aos depends_on que todos os serviços declaram. Olhem só, da primeira vez demora um pouquinho pra subir. Vou acelerar aqui um pouquinho e … pronto. Como expliquei antes, só pra esse projeto do Lauro, temos que rodar o composer install manualmente, aceleramos mais um pouco e … pronto. Finalmente, podemos subir o Hyperf em cada um dos containers.

Pra testar que tudo deu certo, podemos consultar o endpoint da API de contagem de pessoas, que é usado pelo script de benchmark pra mostrar quantas pessoas foram inseridas no teste de carga. Basta chamar do próprio terminal com “curl http://localhost:9999/contagem-pessoas”. E.. deu pau. O que aconteceu?

Se estiver rodando em alguma distro Linux, ia retornar bonitinho. Mas se estiver rodando em Mac ou Windows, como neste meu caso, via WSL 2, aquela configuração de network mode host não vai funcionar. Por que?

Se não entendem como um container funciona por baixo, não deixe de assistir o episódio sobre containers. Em resumo, Docker precisa da kernel Linux pra funcionar. Docker não é uma máquina virtual, é uma infraestrutura que pede pra kernel mentir pros processos, fazendo eles acreditarem que estão rodando sozinhos na máquina.

No caso de Mac, o problema é que Macs não rodam kernel de Linux. Apesar de rodarem programas que parecem de Linux, na realidade são todos recompilados pra serem compatíveis com a versão Darwin do BSD UNIX. Macs são UNIX e não Linux. Eu já contei essa história no episódio sobre as diferenças de Mac, Windows e Linux. Programas de Linux não rodam nativamente em Macs, todos precisam ser no mínimo recompilados. Mac e Linux são binariamente incompatíveis.

Windows, obviamente, também não é uma distro Linux. A kernel do Windows é fundamentalmente diferente de Linux e Macs. Mas hoje em dia existe o WSL 2, que é basicamente uma máquina virtual Linux super leve, rodando por cima do Windows usando a infraestrutura de hypervisor do Hyper-V. Essa é a única solução pra Macs e Windows: rodar Linux numa máquina virtual e, dentro dela, rodar Docker.

Tanto no caso de Mac, quanto Windows, uma das opções mais populares é baixar o pacote Docker Desktop, que vai instalar a máquina virtual pro Docker e uma interface gráfica, que é opcional, pra facilitar gerenciar os diversos elementos de Docker, como redes virtuais, imagens e containers. E aqui está o problema de porque não funciona localhost:9999 em modo de rede host. Segundo a própria documentação: o driver de rede modo host só funciona em Linux, rodando na VM do Docker Desktop, o container não vai receber nenhum endereço IP e a publicação de portas vai ser ignorada, tornando o container inacessível.

Quer dizer que Docker Desktop de Windows e Mac são uma droga, então? Recapitulando, porque estávamos usando modo de rede host? Porque no cenário de teste de carga, o modo padrão gera gargalo, então mudamos pro modo host. Isso é só pra situação de teste de carga. Pro dia a dia, enquanto você está programando, em situações normais, não vai sentir diferença nenhuma. Nesse caso, não precisa usar esse modo host e deixar tudo no padrão. No modo ponte virtual, Docker de Mac e Windows vai funcionar direitinho.

No caso do WSL 2, você pode instalar o Docker ou Podman dentro do WSL em vez de usar uma VM separada, como o Docker Desktop faz.

Falando de Docker Desktop, uma pequena tangente, se você quiser muito uma interface gráfica pra gerenciar imagens, containers e tudo mais, experimente outra opção: o Portainer, que por si só é uma aplicação que roda em container Docker, então é trivial de instalar, e te dá uma interface web de administração muito mais avançada do que Docker Desktop. Mas também é legal aprender a ficar na linha de comando e experimentar coisas como Lazy Docker. Dá pra fazer tudo só com o comando “docker”, mas às vezes não lembramos como fazer coisas que não se usa todo dia, tipo, “como era mesmo, pra apagar imagens que não estão sendo usadas?”, daí tanto Portainer como Lazy Docker podem ajudar. Dêem uma fuçada.

Na verdade, é muito mais fácil usar o NAT de portas, que é a opção padrão. Vamos pegar o arquivo de nginx do projeto do Lucas, que não optou pelo modo de rede host. Olha a declaração de servidores de upstream. Em vez de estar localhost com duas portas diferentes, tempos aqui dois hostnames diferentes usando as mesmas portas. É como se estivéssemos declarando dois servidores separados, cada um com uma cópia da aplicação na porta 8080.

    upstream api {
        server app1:8080;
        server app2:8080;
        keepalive 500;
    }

No docker compose, podemos declarar o app1, expor a porta 8080, etiquetar com & comercial “app” e lá embaixo declarar o app2 usando a mesma configuração, só sobrescrevendo o hostname. Todo o resto fica igual. Não precisamos nos preocupar em conflito de portas, porque é como se fossem servidores em máquinas diferentes. Essa é a vantagem do NAT de portas e por isso ele é o modo padrão. É muito mais intuitivo. Se não ficou claro isso, assista de novo meu episódio sobre containers e a série de redes.

A versão em PHP do Lauro é uma das mais complicadinhas pra subir, por causa daqueles passos extras no README, que ele preferiu não automatizar. Pra prosseguir a explicação, vamos usar o projeto de Node do Lucas daqui pra frente. O dele é mais simples, basta executar “docker compose up”, esperar tudo baixar e pronto. Mesmo em Docker de Windows ou Mac não deve ter problemas porque a versão dele usa NAT de portas padrão, então tudo deveria funcionar plug and play, que é o ideal de um docker compose.

Antes que eu me esqueça, se não está acostumado a usar docker compose, sempre se lembre que se não iniciar o comando “up” com a opção “-d” de daemon, ele vai ficar prendendo seu terminal. Com control-c dá pra derrubar todo mundo. E garanta que os containers desligaram executando “docker compose down”. Se modificar seu código e subir depois com “up” mas sentir que não apareceram suas modificações, dá pra forçar o build da imagem da aplicação com “docker compose up –build” ou “docker compose up –force-build”.

De outro terminal, dá pra ver os containers que estão de pé fazendo “docker ps”. Olha só como aparece bonitinho, daí dá pra abrir o shell em qualquer um deles usando “docker exec -it”. Enquanto estiver trabalhando num projeto, pode só ficar derrubando com o comando “down” e subindo com o comando “up”. Mas quando terminar o projeto e não for mais mexer nele, vale derrubar uma última vez com “docker compose down –rmi all”. Essa opção vai apagar os containers e as imagens. Imagens de docker usam muito espaço em disco e se ficar esquecendo de limpar de projetos que não vai mais usar, vai estar desperdiçando espaço. Depois pesquise sobre como limpar containers e imagens que não está mais usando.

Voltando, chegou a hora de entender um pouco esse negócio de teste de carga. Entenda, foda-se que linguagem você escolheu, que framework usa, as toneladas de javascript que enfiou no front-end. Svelte, Tailwind, nada disso importa. A única coisa que interessa é que entre seu navegador favorito e sua aplicação, trafegam mensagens em formato texto, obedecendo o protocolo HTTP. Mensagens divididas em cabeçalhos e corpo de texto.

O teste que sugeri antes, curl http://localhost:9999/contagem-pessoas é um exemplo disso. O Curl ou Wget são navegadores de linha de comando. Navegadores simples, que não tem front-end e por isso não precisam interpretar nem html, nem css, nem javascript. Eles só listam o que recebem. Fiquei pensando se perdia tempo explicando curl, como mandar e receber mensagens HTTP. Mas isso seria uma tangente desnecessária. Todo desenvolvedor web, tem que saber como enviar e receber mensagens HTTP manualmente, seja via curl na linha de comando, seja via web developer tools em qualquer navegador. Sem saber isso, sinto muito, você nem começou a entender web ainda. Volte vários passos, estude mais, só depois retorne.

Estou sendo bem cuzão quanto a isso porque é sério: HTTP é simples, os cabeçalhos principais dá pra saber de cabeça, os encodings de mensagem, como URL encode, são simples. E se não entender como funciona essa troca de mensagens, tudo daqui pra frente não vai fazer nenhum sentido. Sem saber isso você não entende nem o que é uma API. Sem saber isso não tem nem como começar a falar de problemas de segurança triviais como request forgery, nem otimizações de performance como conditional get requests. 80% da parte mais interessante e mais importante, você nunca vai ter acesso. Então pare aqui e vá estudar antes.

Isso tudo dito, vamos pular direto pro Gatling, que é a ferramenta de stress test, ou teste de carga, que a rinha escolheu. Eles até deram uma pequena patrocinada, acho que com alguns prêmios pros ganhadores. É uma ferramenta que aceita scripts feitos em Scala ou Kotlin. Primeiro de tudo é ter Java instalado na sua máquina. Cuidado, saiu não faz muito tempo o Java 21, e dependendo da sua distro, com um Arch, que instala tudo que tem de novo, vai ter problemas. Escolha manualmente o OpenJDK 17 ou versões mais antigas como versão 11.

Como eu sei que estou com o java correto? Porra, abre o terminal e digita ‘java -version’. Se tiver mais de uma jdk instalada, no caso de um Arch, tem o script ‘archlinux-java set java-17-openjdk’ pra forçar usar a versão 17, por exemplo. Consulte a documentação do pacote de JDK da sua distro. Se for Windows ou Mac, baixe direto o instalador da versão 17 e já era.

Depois disso precisa baixar o Gatling propriamente dito. Só ir no site e baixar o zip. Depois deszipe onde quiser. Eu pessoalmente prefiro deszipar no diretório “/opt/gatling” mas você pode deszipar na sua home. Enfim, o importante é entrar no repositório da rinha, no diretório chamado “stress-test”. Lá vai achar o script principal, “run-test.sh”. Tem versão de Powershell também, mas honestamente, não perdi meu tempo com isso.

Edite esse script e garanta que a variável GATLING_BIN_DIR está apontando pro diretório bin que veio dentro do zip que baixou. Olhe a linha de baixo, é como ele executa o gatling, passando o script da simulação que é esse RinhaBackendSimulation, que já vamos ver. Em seguida declara os diretórios principais de trabalho. Fica tudo dentro de “stress-test/user-files”. Em resources temos planilhas com dados de teste. Vamos dar uma olhada.

O arquivo “pessoas-payloads.tsv” tem os dados de pessoas falsas que ele vai enviar pra API de cadastrar pessoas. Como podem ver, cada linha é um JSON, e os dados são super aleatórios mesmo. Você acha que todo mundo envia dados bonitinhos pra sua aplicação? Pelo contrário, com o tanto de bots que tem por aí, sua aplicação está recebendo dados parecidos com esse o tempo todo. Nunca assuma que sua aplicação vai ser usada só por pessoas inteligentes que sabem ler e escrever direito.

Pelo contrário, assuma que a maior parte do uso vai vir de bots zoados ou pessoas zoadas que male male sabem escrever o próprio nome e vão preencher tudo errado. Sua aplicação precisa estar preparada para os piores inputs, sempre. Esse é um bom exemplo de ataque pra ver se coisas inválidas acabam conseguindo burlar suas validações, ou o mais comum, você esqueceu de implementar algumas validações.

O segundo arquivo é o “termos-busca.tsv” que vai ser usado na API de procura por termos. É outra lista de bobagens aleatórias. Mesma coisa, é pra estressar suas APIs e ver como se comportam. Precisa ter validações conforme explicado nas instruções da rinha. Pra um projeto de verdade, é bom ter teste de carga com dados completamente aleatórios como esses, mas também é bom ter dados um pouco mais próximos do que pessoas medianas mandariam, pra ficar mais fácil de analisar depois. Criar dados de teste é, em si, uma arte também.

Testes com inputs aleatórios como esse são chamados de Fuzz Test. Fuzz é tipo barulho, bagunça, que é um jeito de dizer aleatório. Se você só fizer testes com dados que parecem de verdade, está perdendo a oportunidade de ver os limites das validações.

Finalmente, temos o script do teste de carga propriamente dito, neste arquivo RinhaBackendSimulation.scala. Mesmo se você nunca escreveu Scala antes, pra fazer scripts simples com esse não é difícil. Qualquer bom programador deve ser capaz de no mínimo ler e entender sem grandes dificuldades. Vamos lá, por partes.

Gatling tem o conceito de Simulation e nossa classe herda dela. Em seguida começamos definindo pra onde mandar nossa carga. No caso a URL base é localhost porta 9999, onde configuramos o NGINX no Docker Compose, lembram? Como nossa aplicação não tem tratamento pra nenhum cabeçalho, só isso já basta. Só de brincadeira, colocaram um user agent fake aqui.

class RinhaBackendSimulation
  extends Simulation {

  val httpProtocol = http
    .baseUrl("http://localhost:9999")
    .userAgentHeader("Agente do Caos - 2023")