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

Construir um laboratório doméstico moderno com contêineres marítimos tornou-se um hobby favorito para muitos entusiastas da tecnologia. O Docker Compose está quase sempre no centro dessa configuração.Defina seus serviços em YAML, versione-os com Git e você poderá iniciar todo o seu ambiente com um único comando.

Agora, quando você começa a cultivar, as coisas acontecem: você passa de ter dois ou três recipientes para Dezenas de serviços, redes internas, proxies reversos, bancos de dados e executores de CI.É aí que surge a grande questão: um único arquivo Docker Compose gigante ou vários 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 já usa o Homelabs há algum tempo geralmente opera dentro de três modelos organizacionais do Compose, cada um com suas próprias vantagens e desvantagens. Escolher a abordagem correta evita muitos problemas na hora de expandir ou migrar máquinas..

De um lado está aquele que começou com O Docker Run começou de forma desorganizada, depois migrou para o Portainer e, finalmente, deu o salto para o Docker Compose.É 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 salvo em arquivos.

No extremo oposto estão aqueles que consolidou tudo em um único arquivo “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 plataforma.

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

Uma solução bastante elegante combina os dois mundos: um 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 organizar tudo isso. É aqui que ambos os agrupamento por função como 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 beleza dos perfis é que Você pode lançar apenas uma parte da infraestrutura. Dependendo das suas necessidades. Por exemplo, você pode executar apenas o perfil principal + infraestrutura em um mini PC de baixo consumo e apenas o perfil de mídia em um servidor grande com mais discos e GPUs.

Em repositórios bem projetados, geralmente existe um docker-compose.yml “master” que inclui arquivos individuais em 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 em um diretório secrets/, o que simplifica bastante a configuração inicial.

Seguindo esse padrão, o gerenciamento de um laboratório doméstico se resume basicamente a Edite o arquivo .env e os segredos, habilite ou desabilite perfis e decida quais serviços iniciar em cada host.Ideal se você for implantar o mesmo conjunto de aplicativos em vários computadores.

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

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

Quem defende o arquivo mestre único Geralmente destaca 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 Ao tentar depurar um problema específico, você se depara com um monstro de centenas de linhas de código. Não é incomum sentir um pouco de arrependimento quando tudo fica muito grande.

A outra abordagem é ter Um arquivo docker-compose.yml por aplicativo ou por pilha lógica., dentro de uma estrutura como:

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

Com isso, cada contêiner passa a ser chamado de algo como aplicativo-pilha-de-livros-1 o traefik-reverse-proxy-1O que ajuda você a localizar problemas rapidamente: se o contêiner bookstack-app-1 falhar, você saberá exatamente em qual pasta procurar.

Visualmente, é muito mais limpo e Isso permite que você gerencie cada serviço de forma independente. (iniciar, parar ou atualizar sem afetar o restante). Além disso, existem aplicativos como o Dozzle que aproveitam a separação de pilhas para melhor organizar os logs.

A troca é que Se você separar tudo demais, a coordenação entre serviços comuns (como o Traefik ou redes compartilhadas) exigirá um pouco mais de cuidado.É necessário declarar redes externas, usar rótulos específicos do Traefik e lembrar a nomenclatura das redes criadas por outros comandos docker-compose.

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

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

DB_USERNAME=myuser
DB_PASSWORD=secretpassword

E então, no YAML, eles são referenciados como ${DB_USERNAME} o ${DB_PASSWORD}Isso torna a composição legível à primeira vista, permitindo que você compartilhar variáveis ​​entre vários serviços E, acima de tudo, armazene as senhas em um arquivo separado (que você pode excluir do Git).

É muito útil para diferentes ambientes (produção, teste, desenvolvimento). Aproveite o docker-compose.override.ymlA ideia é ter um arquivo docker-compose.yml base e, na seção de sobrescrita, substituir apenas o que for alterado: portas, caminhos, flags de depuração…

Por exemplo, em desenvolvimento, você pode carregar uma substituição onde Você expõe uma porta diferente, ativa o modo DEBUG e monta o código-fonte local.Você não altera o arquivo YAML principal, mas adapta a pilha ao ambiente em que ela será executada.

Obviamente, Controlar as versões de tudo com Git é obrigatório se você quiser que seu laboratório doméstico seja minimamente profissional.Geralmente você tem algo como:

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

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

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

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

Um padrão clássico é configurar uma rede Docker dedicada, por exemplo. proxy_reverso ou similar, onde o Traefik e todos os serviços web que você irá disponibilizar externamente estejam conectados. O restante dos contêineres (bancos de dados, caches, etc.) permanece em redes internas isoladas.

Se você usa o Traefik e separa seus serviços em diferentes arquivos docker-compose, você precisa definir uma rede externa compartilhadaAlgo assim:

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`. As tags informam ao Traefik... Qual rede deve ser usada 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 Conecte-os a uma rede padrão compartilhada e conceda acesso à rede Traefik somente ao contêiner web.O banco de dados terá um rótulo 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 controladaSomente os contêineres que você marcar com etiquetas Traefik e que estiverem na rede proxy ficarão 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 comando docker compose down. Volumes e encadernações são o seu seguro de vida..

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.) só visualizam a pasta de downloads.Gerenciadores como o Radarr/Sonarr têm acesso tanto aos downloads quanto à mídia (para mover/criar links físicos), enquanto servidores como o Plex ou o Jellyfin só visualizam a pasta de mídia.

Dessa forma, você aplica o princípio de Ultimo privilégioCada contêiner acessa apenas o que realmente precisa. Essa separação clara também facilita a decisão sobre quais volumes ou caminhos devem ser copiados para a nuvem ou para unidades externas.

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, é interessante 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. O design de diretórios proposto por guias como o TRaSHGuides é baseado precisamente nisso.

Automatizando implantações com GitHub Actions e executores locais

Se você gosta de levar as coisas para o próximo nível, pode ir um passo além e Automatize as atualizações do seu laboratório doméstico usando CI/CD.Diversos usuários substituíram o Jenkins e ferramentas similares por um fluxo de trabalho que utiliza o GitHub Actions e um executor auto-hospedado em seu próprio laboratório doméstico.

O mecanismo é simples: sempre que você enviar alterações para a branch principal do seu repositório Homelab, É iniciado um fluxo de trabalho do GitHub Actions que executa testes, verificações de código e, se tudo correr bem, implementa 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: segurança adicional (você controla vazamentos de segredos), melhor qualidade de código e implantações repetíveis com um único comandoE como você está usando um executor local, as imagens e os volumes não saem da sua rede; você está simplesmente usando 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 dependendo de Docker Run e Portainer até que, em decorrência de um incidente ou migração, seja forçada a reavaliar sua abordagem. Quando você perde um host ou precisa migrar serviços para outra máquina, Confiar apenas em comandos ou configurações isoladas no Portainer é uma armadilha..

A grande diferença ao mudar para o Compose é que A definição completa do serviço se transforma em 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 trata mais de "reconstruir um contêiner manualmente" e se torna Modifique uma linha em um arquivo, salve e execute `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... Copie o mesmo arquivo de composição para outra máquina, ajuste quatro caminhos e execute a mesma pilha com hardware diferente.Na verdade, muitas pessoas reconhecem que, após um susto envolvendo perda de dados ou migrações caóticas, o Compose lhes poupou muito tempo em eventos subsequentes.

Como vantagem adicional, criar novos serviços a partir dos antigos torna-se trivial: por exemplo, Clone a configuração do Plex para montar o Jellyfin. Reutilizar 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á compilar suas próprias imagens. Nesses casos, é importante ter cuidado. contexto de construçãoNão envie o repositório inteiro sem filtros, mas limite-se à pasta do projeto (com um bom arquivo .dockerignore) para que as compilações sejam rápidas e leves.

Outra técnica muito útil é recorrer a construções de vários estágios Nos seus Dockerfiles: na primeira fase, você instala as dependências e compila, e na segunda fase, você copia apenas os artefatos necessários para uma pequena imagem base. Resultado: imagens finais. muito menor e mais seguroPorque não incluem cadeias de ferramentas ou bibliotecas adicionais.

Na seção Compor, 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 um aplicativo que consome muitos recursos monopolize-os. Em laboratórios domésticos, isso ajuda a impedir que um serviço mal configurado prejudique o restante do sistema.

Não se esqueça do políticas de reinicialização (reiniciar: sempre, a menos que seja interrompido, em caso de falha): com essas opções, 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, é uma boa ideia agendar tarefas de limpeza regulares usando comandos como poda de imagem do Docker, poda de contêiner do Docker e poda de volume do Docker Eliminar resquícios de versões antigas, contêineres interrompidos ou volumes órfãos e, assim, recuperar espaço em disco.

Serviços de saúde, registro e monitoramento

Para garantir que seu laboratório doméstico não seja uma caixa preta, é importante trabalhar em três aspectos principais: verificações de saúde, registro controlado e monitoramentoO 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 é considerado íntegro.

Com isso você pode fazer com que Apenas contêineres "saudáveis" recebem tráfego. (por exemplo, através do Traefik) e que, se pararem de responder, reiniciam de acordo com a política configurada. Isso aumenta significativamente a resiliência com o mínimo esforço.

Em relação aos registros, ajuste o arquivo JSON do driver com os seguintes limites: tamanho máximo e arquivo máximo Isso impede que seu disco fique cheio de gigabytes de logs esquecidos. Ferramentas online 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.

Em relação a métricas e monitoramento contínuo, a combinação clássica é cAdvisor + Prometheus + GrafanaO 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 haja algum pico.

Um laboratório doméstico bem configurado geralmente também inclui Tempo de atividade do Kuma para verificações de disponibilidade (HTTP, ICMP, TCP…) 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 improvisada que seja a montagem, a segurança não é opcional. Muitas pessoas optam por... Não exponha diretamente seu NAS ou seus serviços ao mundo exterior.Limitar o acesso remoto por meio de uma VPN (WireGuard é uma opção muito popular devido ao seu desempenho e simplicidade).

Neste 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 são expostos à internet sem esse filtro prévio.

Aqueles que preferem não gerenciar sua própria VPN às vezes recorrem a Túnel Cloudflare ou Tailscale Para acessar o laboratório doméstico sem abrir portas. Essas são alternativas convenientes, embora, se sua prioridade absoluta for a privacidade, você precise considerar quais metadados esses terceiros podem coletar.

Outra boa prática é Criptografe os discos do servidor e do NAS.Aplique patches regularmente e limite 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 Homelab 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 Sim, é aconselhável estabelecer padrões mínimos 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.