Docker para iniciantes: rodar serviços no servidor doméstico

O que é um contêiner (e o que ele não é)

Instalar um programa de servidor "na mão" significa adicionar pacotes, bibliotecas, arquivos de configuração e usuários ao sistema. Dois programas podem precisar de versões diferentes da mesma biblioteca; desinstalar um deixa restos; atualizar o sistema pode quebrar outro. Um contêiner resolve isso empacotando o programa com tudo de que ele precisa em uma caixa isolada, que roda sobre o mesmo Linux do servidor sem misturar nada com ele. Apagar o contêiner apaga a caixa inteira; o sistema continua como estava.

A comparação clássica é com a máquina virtual (VM): uma VM é um computador inteiro simulado, com seu próprio sistema operacional, que consome memória e disco como um computador de verdade. Um contêiner não simula hardware nem carrega um sistema completo; ele compartilha o núcleo do Linux do servidor e isola apenas o que o programa enxerga (arquivos, processos, rede). Resultado: um contêiner inicia em segundos e consome pouco; uma máquina modesta roda dez deles sem esforço. A VM continua sendo a escolha certa quando você precisa de outro sistema operacional (um Windows dentro do Linux, por exemplo) ou de isolamento forte; para rodar serviços Linux em um servidor Linux, o contêiner é mais leve e mais simples.

O vocabulário mínimo:

• Imagem: o pacote pronto, publicado pelo desenvolvedor do serviço, baixado de um registro como o Docker Hub. É como um instalador.
• Contêiner: uma imagem em execução. Você pode ter vários contêineres da mesma imagem.
• Volume: uma pasta do servidor conectada ao contêiner, onde os dados persistem. Sem volume, o que o serviço grava some quando o contêiner é recriado.
• Porta: o "número de portão" pelo qual o serviço atende na rede. O contêiner tem suas portas internas, e você decide quais expor no servidor.

Instalar o Docker no Ubuntu Server

O Ubuntu tem um pacote chamado docker.io nos repositórios normais, e há também o Docker em formato snap. Evite os dois: costumam estar atrasados e o snap tem limitações de permissões que geram erros difíceis de entender. O caminho recomendado pelo projeto é adicionar o repositório oficial do Docker ao apt, o que garante versões atuais e atualizações junto com o resto do sistema. O procedimento completo e sempre atualizado está em docs.docker.com/engine/install/ubuntu; em resumo, ele tem quatro movimentos:

1. Instalar os pré-requisitossudo apt update && sudo apt install ca-certificates curl. São as ferramentas para baixar e validar a chave do repositório.
2. Adicionar a chave de assinatura do DockerA documentação fornece os comandos que baixam a chave pública do Docker para /etc/apt/keyrings/docker.asc. É ela que permite ao apt confirmar que os pacotes vêm do Docker e não foram alterados.
3. Adicionar o repositórioUm comando cria o arquivo /etc/apt/sources.list.d/docker.list apontando para o repositório do Docker correspondente à sua versão do Ubuntu. Depois, sudo apt update.
4. Instalar os pacotes
   Terminal

   sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

   O docker-ce é o motor; o docker-compose-plugin adiciona o comando docker compose, usado no resto deste guia.

Existe um atalho: o script get.docker.com, mantido pelo próprio Docker, que faz esses quatro passos sozinho (curl -fsSL https://get.docker.com -o get-docker.sh e depois sudo sh get-docker.sh). Ele é conveniente, mas tem o mesmo problema de qualquer "baixe e execute como administrador": você está confiando cegamente no conteúdo. O próprio Docker o recomenda apenas para testes e ambientes de desenvolvimento. Para o servidor, vale os cinco minutos a mais do método do repositório.

Confirme que tudo funcionou e descubra as versões instaladas:

sudo docker version
sudo docker compose version
sudo docker run --rm hello-world

O último comando baixa uma imagem minúscula de teste, roda um contêiner que imprime uma mensagem de boas-vindas e o remove (--rm). Se a mensagem apareceu, o Docker está operacional.

Docker Compose: o serviço descrito em um arquivo

É possível subir contêineres com comandos longos do tipo docker run -d -p ... -v ... imagem, mas ninguém lembra desses comandos uma semana depois. O Docker Compose troca o comando por um arquivo de texto, o compose.yaml, que descreve o serviço: qual imagem, quais volumes, quais portas, se deve reiniciar sozinho. O arquivo fica guardado, pode ser lido, copiado para outro servidor e corrigido. Toda a operação passa a ser docker compose seguido de um verbo, rodado na pasta onde o arquivo está.

Repare no nome: docker compose, com espaço, é o plugin atual, instalado acima. O antigo docker-compose, com hífen, era um programa separado em Python; tutoriais antigos o usam e ele pode nem estar instalado na sua máquina. Se um comando com hífen falhar, troque pelo espaço.

Organize uma pasta por serviço. Uma estrutura que funciona bem é ~/servicos/nome-do-servico/, com o compose.yaml e as pastas de dados dentro. Assim, fazer backup dos serviços é fazer backup de ~/servicos, e os guias de ferramentas de backup se aplicam diretamente.

O primeiro serviço, do arquivo ao navegador

O exemplo é o Uptime Kuma, um monitor de disponibilidade com interface web: você cadastra o roteador, o NAS, o site da família, e ele avisa quando algo sai do ar. É um serviço real, útil em qualquer casa, com imagem oficial, um único volume e uma única porta: o exemplo perfeito para entender a receita.

1. Criar a pasta e o arquivo
   Terminal

   mkdir -p ~/servicos/uptime-kuma
   cd ~/servicos/uptime-kuma
   nano compose.yaml

2. Descrever o serviçoCole o conteúdo abaixo no editor. A indentação com dois espaços faz parte da sintaxe: respeite-a.
   Arquivo compose.yaml

   services:
     uptime-kuma:
       image: louislam/uptime-kuma:1
       container_name: uptime-kuma
       restart: unless-stopped
       ports:
         - "3001:3001"
       volumes:
         - ./data:/app/data

   Linha a linha: image é a imagem oficial do projeto, fixada na linha de versão 1 (sem isso, o Docker usaria latest, que pode mudar de versão principal sem aviso). restart: unless-stopped faz o contêiner voltar sozinho após um reinício do servidor, a menos que você o tenha parado de propósito. ports liga a porta 3001 do servidor à porta 3001 interna do contêiner; o número da esquerda é o que você usa no navegador. volumes conecta a pasta data, ao lado do arquivo, à pasta /app/data dentro do contêiner, onde o programa guarda seu banco de dados; é isso que faz os dados sobreviverem.
3. Subir o serviço
   Terminal

   docker compose up -d

   O Docker baixa a imagem (só na primeira vez) e inicia o contêiner. O -d ("detached") devolve o terminal em vez de prender a tela com os registros.
4. Abrir no navegadorEm qualquer computador da casa, acesse http://192.168.0.25:3001 (com o IP do seu servidor). A tela de criação da conta de administrador do Uptime Kuma aparece. Pronto: seu primeiro serviço está no ar.

A receita é a mesma para qualquer outro serviço. Um servidor de mídia Jellyfin, por exemplo, usa a imagem jellyfin/jellyfin, a porta 8096, um volume para a configuração e outro, somente leitura, apontando para a pasta onde estão os vídeos (/mnt/dados/videos:/media:ro). A página de cada projeto no Docker Hub ou na documentação oficial informa a imagem, as portas e as pastas internas; o seu trabalho é só traduzir isso para o compose.yaml.

Operar no dia a dia: logs, atualização, limpeza

Todos os comandos abaixo são executados dentro da pasta do serviço (onde está o compose.yaml).

Atualizar é o par pull e up -d: o Docker baixa a imagem nova e, ao recriar o contêiner, mantém o volume, de modo que os dados ficam. Como você fixou a linha de versão na imagem (:1), as atualizações ficam dentro de uma faixa compatível; para mudar de versão principal, leia as notas do projeto e troque a tag de propósito. Cada atualização deixa a imagem antiga no disco, e é por isso que o docker image prune entra na rotina de manutenção.

Segurança: portas, usuário e o que não fazer

Contêineres isolam, mas não blindam. Três cuidados fazem a diferença entre um servidor caseiro tranquilo e um problema:

• Portas publicadas ficam abertas na rede local. O "3001:3001" do exemplo atende qualquer aparelho conectado ao seu roteador. Isso é o desejado dentro de casa, mas pense em quem está na rede: visitas com a senha do Wi-Fi, uma TV com aplicativos duvidosos. Serviços que só o próprio servidor precisa acessar (um banco de dados usado por outro contêiner, por exemplo) devem ser publicados em "127.0.0.1:5432:5432", ou nem publicados; contêineres do mesmo arquivo se enxergam pelo nome sem precisar de portas.
• Não rode como root quando a imagem permitir. Dentro do contêiner, muitos programas rodam como administrador por padrão. Imagens bem mantidas aceitam a opção user: "1000:1000" (o número do seu usuário no servidor, obtido com id -u) ou variáveis como PUID e PGID. Isso faz os arquivos nos volumes pertencerem ao seu usuário e limita o estrago se o serviço tiver uma falha.
• Escolha imagens com critério. Prefira a imagem oficial do projeto ou a de mantenedores conhecidos, verifique quando foi atualizada pela última vez e desconfie de imagens sem documentação. A imagem roda com acesso às pastas que você monta nela.

Erros comuns

Marcar este guia como lido (salvo apenas neste navegador)