Este documento explica como utilizar o qBitTorrent via docker/podman no NixOS utilizando o seguinte módulo, então tenha o bom senso de acompanhar o código enquanto faz leitura dessa wiki.

---

Visão Geral

O qBittorrent é um cliente BitTorrent leve e poderoso. Rodá-lo em container traz vantagens como:

• Isolamento do sistema host
• Atualizações mais rápidas (imagens mantidas pela comunidade)
• Configuração simplificada via variáveis de ambiente
• Fácil backup e restauração (volumes dedicados)

---

Options

Criei uma Options no services.homelab.qbittorrent para facilitar a reusabilidade do container em qualquer host, veja as opções:

user = mkOption {
  type = types.str;
  default = "admin";
  description = "The username that will own the config and downloads.";
};
    
storagePath = mkOption {
  type = types.str;
  description = "The path where downloads will be saved (must be an absolute path string).";
  example = "/mnt/storage/downloads";
};

As descrições são boas o suficiente para eu ter que explicar.

Essa parte garante que os diretórios a serem usados pelo container existam e com as permissões corretas:

systemd.tmpfiles.rules =
  (map (subDir: "d /var/lib/containers/qbittorrent${subDir} 0755 ${cfg.user} users -") [
    ""
    "/config"
  ])
  ++ [
    "d ${cfg.storagePath} 0775 ${cfg.user} users -"
  ];

---

Configuração Básica do Container

Imagem

A imagem usada é a do LinuxServer: lscr.io/linuxserver/qbittorrent:latest

---

Volumes

• /config → guarda arquivos de configuração do qBittorrent
• /downloads → diretório onde os torrents serão salvos

Exemplo:

volumes:
  - /var/lib/containers/qbittorrent/config:/config
  - /mnt/storage/downloads:/downloads

No nosso módulo, utilizamos a configuração:

volumes = [
  "/var/lib/containers/qbittorrent/config:/config"
  "${cfg.storagePath}:${cfg.storagePath}"
];

Note que eu não defini /downloads e só espelhei o storagePath que é passado pelo mkOption, isso nós obriga a mudar o caminho padrão para downloads de /downloads pelo que foi passado no storagePath por meio da WebUI, assim evitando erros. Tools > Options > Downloads > Default Save Path

Mas aí você me pergunta: "Por que espelhar no lugar de usar ${cfg.storagePath}:/Downloads?".

R: Porque se você utilizar também serviços como Sonnar, Radarr, Bazarr... não precisa ficar criando Remote Path Mappings pra cada um, só faz uma alteração via WebUI no qBitTorrent e pronto.

---

Portas

Por padrão, o container do qBitTorrent abre as portas:

• TCP:
  • 8080 para WebUI;
  • 6881 para Torrenting.
• UDP:
  • 6881 para Torrenting.

No nosso módulo, eu decidi optar pela porta 50322 no lugar de 6881 para Torrenting, pois alguns trackers bloqueiam a porta 6881 e me impedem de fazer alguns downloads, então a troca foi necessária.

Após subir o container, é necessário entrar na WebUI e mudar manualmente a porta em Options > Connection > Port used for incoming connections para 50322, caso contrário o qBittorrent continuará tentando usar a 6881 internamente.

Aqui eu libero essas portas no Firewall:

networking.firewall.allowedTCPPorts = [ 8080 50322 ];
networking.firewall.allowedUDPPorts = [ 50322 ];

Definimos "--network=host" no extraOptions para que o qBitTorrent possa ouvir todas as portas que precisar por meio do host:

extraOptions = [ "--network=host" ];

Estar no modo host torna inútil definir a seção ports do container, então ignorei.

---

Conclusão

A doc desse módulo é só isso, eu só quis deixar algumas coisas claras pra não esquecer no futuro, principalmente a parte sobre alguns trackers simplesmente odiarem a porta 6881. O restante do módulo é bastante simples e pode ser facilmente compreendido só olhando.