Docker Compose em um laboratório doméstico: organização, perfis e melhores práticas

Informatec Digital » Recursos » Docker Compose em um laboratório doméstico: organização, perfis e melhores práticas

Configurar um laboratório doméstico moderno com contêineres tornou-se um hobby favorito para muitos entusiastas de tecnologia. O Docker Compose está quase sempre no centro dessa configuração : defina seus serviços em YAML, versione-os com Git e inicie todo o seu ambiente com um único comando.

No entanto, quando você começa a crescer, as coisas mudam: você passa de dois ou três contêineres para dezenas de serviços, redes internas, proxies reversos, bancos de dados e executores de CI . É aí que surge a grande questão: uma única instância gigante do Docker Compose ou muitos arquivos pequenos? Como organizar perfis, redes, backups, segurança e, além disso, facilitar a migração?

Abordagens práticas para configurar o Docker Compose em um laboratório doméstico.

Na prática, quem usa o Homelabs há algum tempo geralmente trabalha com três modelos organizacionais diferentes do Compose, cada um com suas próprias vantagens e desvantagens. Escolher a abordagem certa evita muitos problemas na hora de expandir ou migrar para uma nova máquina.

Por um lado, há aqueles que começaram com comandos Docker Run independentes, depois migraram para o Portainer e, finalmente, deram o salto para o Docker Compose . É um cenário típico: o Portainer oferece ótima visibilidade, uma interface amigável, modelos, etc., mas, no fim das contas, editar parâmetros complexos ou migrar configurações se torna um transtorno se você não tiver nada arquivado.

No extremo oposto está aquele que consolidou tudo em um único "mega" docker-compose.yml capaz de executar absolutamente todos os serviços de laboratório doméstico: proxy reverso, mídia, utilitários, monitoramento, LLMs, bancos de dados... Tudo em uma única pilha.

Entretanto, muitos usuários optam por uma abordagem mista: vários arquivos docker-compose.yml pequenos, agrupados por contexto (por exemplo, mídia, infraestrutura, produtividade, monitoramento), todos no mesmo repositório e geralmente compartilhando variáveis ​​de ambiente globais.

Uma solução bastante elegante combina os dois mundos: um arquivo docker-compose "raiz" que inclui outros arquivos (cada um em uma subpasta de aplicativos ou serviços). Dessa forma, você mantém uma visão global do laboratório doméstico, mas sem ter que lidar com um arquivo YAML de mil linhas, impossível de ler.

Perfis, agrupamento por função e grandes laboratórios domésticos.

Quando seu laboratório doméstico começa a se aproximar de 30, 40 ou 50 serviços (incluindo serviços de backup como bancos de dados, caches ou indexadores), é vital organizá-los. É aqui que entram em jogo o agrupamento por função e o uso de perfis do Docker Compose.

Um padrão muito comum é agrupar tudo em um único "projeto" do Compose, mas dividido logicamente por perfis. Por exemplo:

• Perfil principal: homelab core, com Traefik como proxy reverso e um provedor de identidade (por exemplo, OAuth ou Authentik) para autenticar todos os aplicativos no mesmo domínio com HTTPS.
• Perfil de mídiaServiços como Plex, Sonarr, Radarr, Ombi, SABnzbd ou qBittorrent são responsáveis ​​por selecionar, baixar e distribuir conteúdo multimídia.
• Perfil de Serviços PúblicosFerramentas como Portainer, Watchtower (se utilizado), Diun, DockCheck ou similares para gerenciar e monitorar contêineres e atualizações.
• Perfil de infraestrutura/monitoramentoTraefik, cAdvisor, Prometheus, Grafana, Uptime Kuma, Dozzle e tudo relacionado a monitoramento e registro de logs.
• Perfis experimentais ou LLM: conjuntos de aplicativos específicos para LLMs ou aplicativos curiosos (ChatGPT Next Web local, LibreOffice Online, etc.) que geralmente estão desativados por padrão.

A grande vantagem dos perfis é que você pode implantar apenas a parte da infraestrutura conforme a necessidade. Por exemplo, você pode executar apenas o perfil de núcleo + infraestrutura em um mini PC de baixo consumo e implantar apenas o perfil de mídia em um servidor grande com mais discos e GPUs.

Em repositórios bem projetados, geralmente existe um arquivo "mestre" docker-compose.yml na raiz que usa o comando `include` para enviar arquivos individuais para uma pasta `apps/` ou `services/` . Além disso, quase todos os serviços são configurados por meio de um único arquivo `.env` global, e alguns segredos são armazenados em um diretório `secrets/` , o que simplifica bastante a configuração inicial.

Seguindo esse padrão, o gerenciamento do laboratório doméstico se resume basicamente a editar o arquivo .env e os segredos, habilitar ou desabilitar perfis e decidir quais serviços iniciar em cada host . Isso é ideal se você pretende implantar o mesmo conjunto de aplicativos em várias máquinas.

Um único arquivo docker-compose gigante versus vários arquivos pequenos.

Este é o eterno debate: um único arquivo docker-compose.yml contendo tudo, ou múltiplos arquivos por serviço/stack? A resposta real geralmente é "depende do que você quer priorizar: simplicidade da migração ou clareza por serviço".

Aqueles que defendem um único arquivo mestre geralmente destacam diversas vantagens:

• Migrar hosts é super fácilVocê clona o repositório, copia o arquivo .env e os segredos, monta os volumes e executa `docker compose up -d`. Não é necessário acessar diretório por diretório.
• Infraestrutura como código da verdadeToda a topologia do laboratório doméstico (serviços, redes, volumes, dependências) está em um só lugar.
• Atualizações centralizadasVocê altera a versão de uma imagem, uma política de reinicialização ou alguns registros, e sabe exatamente onde mexer.

Mas também apresenta desvantagens claras: um arquivo YAML enorme é mais difícil de manter, os conflitos de mesclagem aumentam e, ao depurar um problema específico, você se vê navegando por um monstro de centenas de linhas. Não é incomum sentir um pouco de arrependimento quando tudo fica grande demais.

Outra abordagem é ter um arquivo docker-compose.yml por aplicativo ou por pilha lógica , dentro de uma estrutura como esta:

docker/
├── bookstack/
│   └── docker-compose.yml
├── dashy/
│   └── docker-compose.yml
└── traefik/
    └── docker-compose.yml

Dessa forma, cada contêiner recebe um nome como bookstack-app-1 ou traefik-reverse-proxy-1 , o que ajuda a localizar problemas rapidamente: se o contêiner bookstack-app-1 falhar, você saberá exatamente em qual pasta procurar.

Visualmente, é muito mais organizado e permite gerenciar cada serviço de forma independente (iniciando, parando ou atualizando-o sem afetar os outros). Além disso, aplicativos como o Dozzle se beneficiam da separação de stacks para melhor organizar os logs.

A desvantagem é que, se você separar tudo demais, a coordenação entre serviços comuns (como o Traefik ou redes compartilhadas) exige um pouco mais de cuidado : você precisa declarar redes externas, rótulos específicos do Traefik e lembrar a nomenclatura das redes criadas por outros docker-compose.

Melhores práticas com .env, sobrescritas e controle de versão.

Um dos truques mais subestimados é centralizar a configuração em arquivos .env . Em vez de encher seu docker-compose.yml com variáveis ​​de ambiente, você define algo como isto:

DB_USERNAME=myuser
DB_PASSWORD=secretpassword

E então, no YAML, elas são referenciadas como ${DB_USERNAME} ou ${DB_PASSWORD} . Isso torna o Compose legível à primeira vista, permite compartilhar variáveis ​​entre vários serviços e, o mais importante, armazena senhas em um arquivo separado (que você pode excluir do Git).

Para diferentes ambientes (produção, teste, desenvolvimento), é muito útil utilizar o arquivo docker-compose.override.yml . A ideia é ter um arquivo docker-compose.yml base e, no arquivo de sobrescrita, alterar apenas o que for necessário: portas, caminhos, flags de depuração, etc.

Por exemplo, em desenvolvimento, você pode carregar uma configuração alternativa que expõe uma porta diferente, habilita a depuração e monta o código-fonte local . Você não altera o arquivo YAML principal, mas adapta a pilha ao ambiente em que está sendo executada.

Obviamente, controlar as versões de tudo com Git é obrigatório se você quiser que seu laboratório doméstico seja minimamente profissional . Normalmente, você terá algo assim:

homelab-docker/
├── docker-compose.yml
├── .env.example
├── services/
│   ├── media/
│   ├── infra/
│   └── ...
└── scripts/

A partir daí, você inicializa o repositório, confirma as alterações na infraestrutura e, se algo der errado, pode reverter para uma versão anterior do seu Compose em segundos . Para laboratórios domésticos ambiciosos, isso não é apenas uma opção; é a única maneira de evitar a loucura.

Redes, Traefik e exposição de serviços seguros

Em praticamente todos os laboratórios domésticos com nível de desenvolvimento moderado, a mesma combinação aparece: Traefik como proxy reverso e um provedor de identidade centralizado (Auth ou Authentik) . Isso permite expor vários aplicativos em subdomínios com HTTPS e SSO.

Uma abordagem clássica é configurar uma rede Docker dedicada, como um proxy reverso ou similar, onde o Traefik e todos os serviços web que você disponibilizará externamente estejam conectados. Os demais contêineres (bancos de dados, caches, etc.) permanecem em redes internas isoladas.

Se você usa o Traefik e separa seus serviços em diferentes instâncias do Docker Compose, precisa definir uma rede externa compartilhada . Algo como isto:

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack
    networks:
      - traefik-net
    labels:
      - "traefik.docker.network=traefik_default"

networks:
  traefik-net:
    name: traefik_default
    external: true

Aqui, a rede `traefik_default` é criada pelo Traefik Stack, e os outros serviços são adicionados a ela por meio de uma rede externa chamada `traefik-net`. Os rótulos informam ao Traefik qual rede usar para rotear o tráfego.

Quando uma única pilha inclui serviços de backend (por exemplo, um contêiner web e seu banco de dados), você pode conectá-los a uma rede padrão compartilhada e conceder acesso à rede Traefik somente ao contêiner web . O banco de dados terá um rótulo definido como `traefik.enable=false` para que o Traefik o ignore.

Esse tipo de configuração oferece duas vantagens principais: isolamento entre serviços e exposição controlada . Somente os contêineres que você etiqueta com rótulos do Traefik e que estão na rede proxy se tornam acessíveis externamente.

Persistência de dados, volumes e estrutura de disco

Um laboratório doméstico sem dados persistentes não é muito útil: bancos de dados, configurações, arquivos de mídia, documentos… tudo precisa sobreviver a um Docker Compose Down. Volumes e bind mounts são sua tábua de salvação.

Muitas pessoas organizam seus pertences de armazenamento usando uma estrutura como esta:

/mnt/storage/
├── downloads/
│   ├── movies/
│   └── tv/
├── media/
│   ├── movies/
│   ├── tv/
│   └── music/
└── srv/
    └── 

A ideia é que os programas de download (qBittorrent, SABnzbd, etc.) vejam apenas a pasta de downloads , os gerenciadores como Radarr/Sonarr tenham acesso tanto aos downloads quanto à mídia (para mover/criar links físicos), e os servidores como Plex ou Jellyfin vejam apenas a pasta de mídia.

Dessa forma, aplica-se o princípio do menor privilégio : cada contêiner acessa apenas o que realmente precisa. E essa separação clara também facilita a decisão sobre quais volumes ou caminhos devem ser copiados para a nuvem ou para discos externos.

O diretório srv é normalmente usado para armazenar configurações de aplicativos (por exemplo, /srv/jellyfin/config, /srv/traefik, /srv/paperless, etc.). Geralmente, ele é parcialmente versionado (templates, Caddyfile, etc.), omitindo tudo o que for crítico ou que consuma muitos recursos.

Em alguns casos, é útil usar links físicos na cadeia de downloads: serviços como Radarr ou Sonarr podem encadear arquivos baixados para manter o compartilhamento sem duplicar espaço em disco. A estrutura de diretórios proposta por guias como o TRaSHGuides é baseada justamente nesse princípio.

Automatizando implantações com GitHub Actions e executores locais

Se você quiser ir além, pode automatizar as atualizações do seu laboratório doméstico com CI/CD . Vários usuários substituíram o Jenkins e ferramentas similares por um fluxo de trabalho usando o GitHub Actions e um executor hospedado no próprio laboratório doméstico.

O mecanismo é simples: sempre que você envia alterações para a branch principal do seu repositório doméstico, um fluxo de trabalho do GitHub Actions é iniciado, executando testes, verificações de código e, se tudo correr bem, implantando as alterações no servidor.

Um fluxo de trabalho típico inclui etapas como:

• Scanner secreto do tipo Gitleaks: caso você tenha enviado senhas ou tokens para o repositório por engano.
• Fiapos de YAML ou código de infraestrutura, para manter um formato legível e consistente.
• Atualizando o repositório dentro do próprio laboratório doméstico.: execute o comando git pull no servidor de destino.
• Recreação controlada de contêineresPare os antigos, inicie os novos e verifique o status.

Vantagens: maior segurança (você controla vazamentos de segredos), melhor qualidade de código e implantações repetíveis com um único push . E como você usa um executor local, as imagens e os volumes não saem da sua rede; você simplesmente utiliza a interface do GitHub para visualizar os pipelines.

Por que o Docker Compose facilita tanto a vida em um laboratório doméstico?

Muitas pessoas passaram anos confiando no Docker Run e no Portainer até que, após um incidente ou uma migração, foram forçadas a reavaliar sua abordagem. Quando você perde um host ou precisa mover serviços para outra máquina, depender exclusivamente de comandos ou configurações isoladas dentro do Portainer é uma armadilha.

A grande diferença ao usar o Compose é que toda a definição do serviço se torna texto : volumes, portas, redes, rótulos, variáveis… Tudo em um arquivo YAML que você pode copiar, compartilhar, versionar e reutilizar.

Editar um serviço não se resume mais a "reconstruir um contêiner manualmente"; agora, basta modificar uma linha em um arquivo, salvar e executar `docker compose up -d` . Você não precisa se lembrar do comando original nem clicar em várias telas do Portainer.

Além disso, se você trabalha com vários servidores (mini PCs, NAS, desktops), é extremamente conveniente poder copiar o mesmo arquivo Compose para outra máquina, ajustar quatro caminhos e executar a mesma pilha em hardware diferente . De fato, muitas pessoas reconhecem que, após um susto envolvendo perda de dados ou migrações caóticas, o Compose lhes economizou muito tempo em eventos subsequentes.

Como vantagem adicional, criar novos serviços a partir dos antigos torna-se trivial: por exemplo, clonar a configuração do Plex para configurar o Jellyfin reutilizando os mesmos caminhos de mídia e dispositivos de transcodificação leva apenas alguns minutos se você fizer isso copiando blocos YAML.

Otimização: contexto de compilação, compilações em várias etapas e recursos.

Embora muitos contêineres do Homelab sejam provenientes de imagens públicas, em alguns casos você precisará compilá-los. Nessas situações, é importante gerenciar o contexto de compilação : não envie o repositório inteiro sem filtros, mas sim limite-se à pasta do seu projeto (usando uma diretiva `.dockerignore` robusta) para garantir compilações rápidas e leves.

Outra técnica muito útil é usar builds em múltiplas etapas nos seus Dockerfiles: na primeira etapa, você instala as dependências e compila, e na segunda etapa, você copia apenas os artefatos necessários para uma imagem base pequena. O resultado: imagens finais muito menores e mais seguras , porque não carregam toolchains ou bibliotecas desnecessárias.

No lado do Compose, você tem a opção de definir limites de CPU e RAM (especialmente em ambientes Swarm ou quando o Docker respeita esses parâmetros) para evitar que aplicativos que consomem muitos recursos os monopolizem. Em laboratórios domésticos, isso ajuda a evitar que um serviço mal configurado prejudique o restante do sistema.

Não se esqueça das políticas de reinicialização (reiniciar: sempre, a menos que seja interrompido, em caso de falha): com elas, você garante que os serviços críticos (proxy reverso, VPN, bancos de dados de chaves) sejam reiniciados automaticamente após uma reinicialização ou uma falha pontual.

Por fim, é recomendável agendar tarefas de limpeza periódicas com comandos como `docker image prune`, `docker container prune` e `docker volume prune` para remover resquícios de builds antigos, contêineres parados ou volumes órfãos e, assim, recuperar espaço em disco.

Serviços de saúde, registro e monitoramento

Para evitar que seu laboratório doméstico se torne uma caixa preta, é importante trabalhar em três aspectos principais: verificações de integridade, registro controlado de logs e monitoramento . O Docker Compose permite que você declare verificações de integridade por serviço (usando comandos como `curl -f http://localhost` ou scripts específicos) que determinam se um contêiner está íntegro.

Isso permite garantir que apenas contêineres "saudáveis" recebam tráfego (por exemplo, via Traefik) e que, se pararem de responder, sejam reiniciados de acordo com a política configurada. Isso aumenta significativamente a resiliência com o mínimo esforço.

Em relação aos logs, ajustar o driver de arquivo JSON com limites de tamanho máximo e tamanho máximo de arquivo evita que o disco fique cheio de gigabytes de logs esquecidos. Ferramentas web como o Dozzle permitem navegar pelos logs de todos os contêineres a partir de um navegador, o que é muito conveniente para depurar serviços específicos.

Para métricas e monitoramento contínuo, a combinação clássica é cAdvisor + Prometheus + Grafana . O cAdvisor expõe estatísticas de uso de CPU, memória, disco e rede por contêiner; o Prometheus as coleta periodicamente e o Grafana as exibe em painéis atraentes, com alertas caso ocorra algum pico.

Um laboratório doméstico bem configurado normalmente inclui o Uptime Kuma para verificações de disponibilidade (HTTP, ICMP, TCP, etc.) e um sistema de backup automatizado como o Duplicati para copiar dados críticos para outros discos ou para a nuvem. Dessa forma, você sabe o que está acontecendo e, se algo der errado, não perde o que é importante.

Segurança e acesso remoto ao laboratório doméstico

Por mais que você mesmo configure o dispositivo, a segurança não é opcional. Muitas pessoas optam por não expor diretamente seu NAS ou seus serviços ao mundo externo , limitando o acesso remoto por meio de uma VPN (o WireGuard é uma opção muito popular devido ao seu desempenho e simplicidade).

Nesse modelo, o roteador atua como um gateway: apenas uma porta aleatória é aberta para o servidor VPN e, uma vez conectado, todas as solicitações para serviços internos passam por um túnel criptografado . Nem o Traefik nem os aplicativos ficam expostos à internet sem essa filtragem prévia.

Quem prefere não gerenciar sua própria VPN às vezes recorre ao Cloudflare Tunnel ou ao Tailscale para acessar seu laboratório doméstico sem abrir portas. Essas são alternativas convenientes, embora, se a privacidade for sua principal prioridade, você precise considerar quais metadados esses terceiros podem coletar.

Outra boa prática é criptografar os discos do servidor e do NAS , aplicar patches regularmente e limitar as atualizações automáticas (muitos evitam o Watchtower em favor de atualizações manuais controladas). É melhor estar um pouco atrasado, mas com controle, do que quebrar metade do seu laboratório doméstico por causa de uma atualização que você não verificou.

Como você pode ver, não é necessário atingir um nível "corporativo", mas é aconselhável estabelecer um nível mínimo de segurança e disciplina para que seu laboratório doméstico não seja uma peneira ou uma fonte constante de sustos.

Em última análise, configurar um laboratório doméstico robusto com Docker Compose é uma combinação de organização, bom senso e disposição para experimentar: se você agrupar os serviços, definir bem as redes, documentar tudo no Git e automatizar um pouco, você terá um ambiente que pode ser iniciado com um único comando, migrado facilmente para outra máquina e expandido aos poucos, sem se tornar uma selva incontrolável.