Como configurar Docker e Docker Compose em VPS

Tempo estimado: 25-35 minutos

Neste guia você vai preparar uma VPS Ubuntu para rodar containers com Docker Engine e Docker Compose. A ideia é deixar a base pronta para aplicações em produção, com instalação via repositório oficial, serviço ativo no boot, usuário sem necessidade de sudo, firewall básico, logs com limite e um stack de teste usando Nginx. Se você ainda está planejando a infraestrutura, veja também o guia sobre VPS para Docker em produção para entender requisitos de CPU, memória e armazenamento antes de hospedar cargas reais.

Os comandos foram pensados para Ubuntu 22.04 LTS ou 24.04 LTS. Em Debian, a lógica é parecida, mas o codename do repositório muda. Em distribuições baseadas em RHEL, como AlmaLinux ou Rocky Linux, os comandos de pacote e firewall são diferentes.

O que você vai aprender

Ao final do guia, você vai ter uma VPS pronta para executar containers de forma organizada, com verificações em cada etapa. Você vai aprender a:

• Confirmar versão do sistema, arquitetura, usuário atual e conectividade antes de instalar qualquer pacote.
• Remover pacotes antigos que podem conflitar com a instalação oficial do Docker.
• Adicionar a chave GPG e o repositório oficial do Docker no Ubuntu.
• Instalar Docker Engine, Docker CLI, containerd e o plugin moderno do Docker Compose.
• Habilitar o Docker no boot e permitir que seu usuário execute comandos sem sudo.
• Configurar uma política simples de firewall, sem derrubar sua sessão SSH.
• Criar um docker-compose.yml real, subir um container Nginx e testar acesso HTTP.
• Ajustar rotação de logs para evitar que containers ocupem todo o disco.
• Diagnosticar erros comuns, como permissão negada, porta ocupada e serviço que não inicia.

O foco aqui não é comparar provedores, e sim preparar o ambiente. Se você desenvolve e faz deploy com frequência, o material sobre VPS para desenvolvedores complementa este guia com critérios de ambiente, automação e fluxo de trabalho.

Pré-requisitos

Você precisa de uma VPS Ubuntu 22.04 LTS ou 24.04 LTS, acesso SSH com um usuário que possa usar sudo, conexão de rede funcional e pelo menos 1 GB de RAM. Para produção, 2 GB ou mais costuma ser uma base mais confortável, principalmente se você pretende rodar banco de dados, cache, workers ou várias aplicações no mesmo servidor. Se a aplicação grava muitos arquivos ou imagens, armazenamento rápido ajuda bastante. Nesse caso, leia também sobre VPS com NVMe para cargas com I/O intenso.

Antes de mexer no servidor, faça backup dos dados importantes. Este guia não usa comandos destrutivos como apagar volumes ou remover diretórios de aplicação, mas a instalação altera pacotes, repositórios e regras de firewall. Se a VPS já hospeda algo em produção, crie um snapshot no painel do provedor ou copie arquivos críticos para outro local.

Conecte na VPS por SSH. Troque 203.0.113.10 pelo IP real da sua máquina e use o usuário administrativo configurado no servidor:

ssh [email protected]

Você deve ver algo parecido com:

Welcome to Ubuntu 24.04 LTS
Last login: Mon Jul 27 10:12:44 2026 from 198.51.100.20
deploy@vps-docker:~$

Durante o guia, execute os comandos exatamente como aparecem. Quando houver risco de bloquear acesso, você vai validar primeiro e aplicar depois.

Passo 1: Atualizar a VPS e validar o sistema

Comece verificando se a VPS usa uma versão compatível do Ubuntu e se você tem privilégios administrativos. Isso evita perder tempo com erro de repositório, arquitetura incompatível ou usuário sem permissão. Execute:

lsb_release -a
whoami
sudo -v
uname -m

A saída esperada deve ser parecida com esta:

Distributor ID: Ubuntu
Description:    Ubuntu 24.04 LTS
Release:        24.04
Codename:       noble
deploy
x86_64

Se sudo -v pedir senha e não retornar erro, seu usuário pode executar comandos administrativos. Se aparecer deploy is not in the sudoers file, pare aqui e entre com um usuário que tenha permissão, ou ajuste o grupo sudo pelo console do provedor.

Agora atualize o índice de pacotes e aplique atualizações disponíveis. Isso reduz conflitos com bibliotecas antigas e garante que dependências de HTTPS e certificados estejam atuais:

sudo apt update
sudo apt upgrade -y

Você deve ver uma saída semelhante:

Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease
Reading package lists... Done
Building dependency tree... Done
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

Instale utilitários usados na instalação oficial do Docker:

sudo apt install -y ca-certificates curl gnupg lsb-release ufw

Saída esperada:

ca-certificates is already the newest version
curl is already the newest version
ufw is already the newest version
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

Por fim, verifique espaço em disco. Docker baixa imagens e cria camadas locais, então uma VPS quase cheia vai falhar logo nos primeiros testes:

df -h /

Resultado saudável:

Filesystem      Size  Used Avail Use% Mounted on
/dev/vda1        49G  6.2G   41G  14% /

Se o uso estiver acima de 85%, limpe logs antigos ou aumente o disco antes de continuar.

Passo 2: Instalar o Docker pelo repositório oficial

O Ubuntu oferece pacotes relacionados a Docker nos repositórios padrão, mas para produção prefira o repositório oficial. Ele entrega versões mais recentes do Docker Engine, CLI, containerd e plugins mantidos pelo projeto Docker. Primeiro, remova pacotes antigos que podem causar conflito. O comando abaixo não apaga imagens nem volumes, mas remove instalações antigas se existirem:

sudo apt remove -y docker docker-engine docker.io containerd runc

Uma saída comum em servidores novos é:

Package 'docker' is not installed, so not removed
Package 'docker-engine' is not installed, so not removed
Package 'docker.io' is not installed, so not removed
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

Agora crie o diretório de chaves e adicione a chave GPG oficial do Docker:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Verifique se o arquivo foi criado:

ls -l /etc/apt/keyrings/docker.gpg

Saída esperada:

-rw-r--r-- 1 root root 2760 Jul 27 10:25 /etc/apt/keyrings/docker.gpg

Adicione o repositório usando a arquitetura e o codename detectados pelo sistema:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update

Você deve ver o repositório do Docker na atualização:

Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease
Get:2 https://download.docker.com/linux/ubuntu noble InRelease [48.8 kB]
Get:3 https://download.docker.com/linux/ubuntu noble/stable amd64 Packages [22.1 kB]
Reading package lists... Done

Instale os componentes principais:

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

Ao terminar, confira a versão instalada:

docker --version
docker compose version

Saída esperada:

Docker version 27.5.1, build 9f9e405
Docker Compose version v2.32.4

As versões exatas podem mudar. O ponto principal é que docker compose responda sem erro.

Passo 3: Habilitar o serviço e ajustar permissões

Depois da instalação, confirme se o serviço Docker está ativo. Em uma VPS de produção, ele também precisa iniciar automaticamente após reboot. Execute:

sudo systemctl status docker --no-pager

Você deve ver active (running):

● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled)
     Active: active (running) since Mon 2026-07-27 10:30:12 UTC

Se o serviço não estiver habilitado, configure o boot automático e inicie manualmente:

sudo systemctl enable docker
sudo systemctl start docker

Verifique novamente:

systemctl is-enabled docker
systemctl is-active docker

Saída esperada:

enabled
active

Por padrão, comandos Docker exigem sudo, porque o socket /var/run/docker.sock pertence ao grupo docker. Para trabalhar com deploys e Compose sem digitar sudo o tempo todo, adicione seu usuário ao grupo. Atenção: quem pertence ao grupo docker pode controlar containers com privilégios elevados no host. Use apenas para usuários confiáveis.

sudo usermod -aG docker $USER
newgrp docker

Teste a permissão:

docker ps

Saída esperada:

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Se ainda aparecer permission denied, encerre a sessão SSH e conecte novamente. Em seguida, rode groups:

groups

Você deve ver docker na lista:

deploy sudo docker

Para fechar o passo, execute o container oficial de teste:

docker run --rm hello-world

A saída esperada inclui:

Hello from Docker!
This message shows that your installation appears to be working correctly.

Esse teste baixa uma imagem pequena, cria um container temporário, imprime a mensagem e remove o container automaticamente por causa de --rm.

Passo 4: Instalar e validar o Docker Compose

Nas versões atuais, o Docker Compose é instalado como plugin e usado com espaço, ou seja, docker compose. A forma antiga, docker-compose com hífen, ainda existe em muitos tutoriais, mas não é a recomendada para novas instalações. Como você instalou docker-compose-plugin no passo anterior, valide o caminho do plugin:

docker compose version
ls -l /usr/libexec/docker/cli-plugins/docker-compose 2>/dev/null || ls -l /usr/lib/docker/cli-plugins/docker-compose 2>/dev/null

A saída deve mostrar a versão e um binário do plugin:

Docker Compose version v2.32.4
-rwxr-xr-x 1 root root 62398464 Jul 10 12:00 /usr/libexec/docker/cli-plugins/docker-compose

Agora crie um diretório para aplicações. Usar /opt é uma escolha comum para stacks de serviços, porque separa arquivos de aplicação dos arquivos pessoais do usuário. Você pode escolher outro caminho, mas mantenha consistência:

sudo mkdir -p /opt/containers/nginx-test
sudo chown -R $USER:$USER /opt/containers
cd /opt/containers/nginx-test

Verifique permissões:

pwd
ls -ld /opt/containers /opt/containers/nginx-test

Saída esperada:

/opt/containers/nginx-test
drwxr-xr-x 3 deploy deploy 4096 Jul 27 10:37 /opt/containers
drwxr-xr-x 2 deploy deploy 4096 Jul 27 10:37 /opt/containers/nginx-test

Crie um arquivo simples de página inicial. Ele será montado no container Nginx como volume somente leitura:

cat > index.html <<'EOF'
<!doctype html>
<html lang="pt-BR">
  <head><meta charset="utf-8"><title>Docker na VPS</title></head>
  <body><h1>Docker Compose funcionando na VPS</h1></body>
</html>
EOF

Confira o conteúdo:

cat index.html

Saída esperada:

<!doctype html>
<html lang="pt-BR">
  <head><meta charset="utf-8"><title>Docker na VPS</title></head>
  <body><h1>Docker Compose funcionando na VPS</h1></body>
</html>

Esse diretório vai servir como base para o próximo passo, onde você cria o arquivo docker-compose.yml e sobe o primeiro stack.

Passo 5: Preparar firewall, diretórios e limites de logs

Antes de expor um container para a internet, configure o firewall com cuidado. O maior risco aqui é bloquear a porta SSH e perder acesso. Primeiro, descubra a porta usada pelo SSH:

sudo ss -tlnp | grep ssh

Normalmente a porta é 22:

LISTEN 0 4096 0.0.0.0:22 0.0.0.0:* users:(("sshd",pid=721,fd=3))

Permita SSH antes de ativar o UFW:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status verbose

A saída antes da ativação pode aparecer assim:

Status: inactive

Ative o firewall apenas depois de liberar SSH. Confirme quando o UFW pedir:

sudo ufw enable

Saída esperada:

Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

Verifique regras:

sudo ufw status numbered

Resultado esperado:

Status: active

[ 1] OpenSSH                    ALLOW IN    Anywhere
[ 2] 80/tcp                     ALLOW IN    Anywhere
[ 3] 443/tcp                    ALLOW IN    Anywhere

Agora configure limite de logs do Docker. Sem esse ajuste, containers verbosos podem preencher o disco com arquivos JSON em /var/lib/docker/containers. Faça backup do arquivo caso ele já exista:

if [ -f /etc/docker/daemon.json ]; then sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak.$(date +%F-%H%M); fi

Crie a configuração:

sudo mkdir -p /etc/docker
cat <<'EOF' | sudo tee /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

Valide o JSON antes de reiniciar:

python3 -m json.tool /etc/docker/daemon.json

Saída esperada:

{
    "log-driver": "json-file",
    "log-opts": {
        "max-size": "10m",
        "max-file": "3"
    }
}

Reinicie o Docker. Isso pode interromper containers em execução, então faça em janela de manutenção se a VPS já roda serviços:

sudo systemctl restart docker
systemctl is-active docker

Saída esperada:

active

Passo 6: Subir um stack de teste com Docker Compose

Agora crie um stack real com Nginx. Ele vai publicar a porta 8080 no host e montar o index.html criado antes. Usar 8080 evita conflito com serviços já presentes na porta 80, como Apache, Nginx instalado no host ou outro proxy reverso.

Dentro de /opt/containers/nginx-test, crie o arquivo:

cd /opt/containers/nginx-test
cat > docker-compose.yml <<'EOF'
services:
  web:
    image: nginx:1.27-alpine
    container_name: nginx-test
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./index.html:/usr/share/nginx/html/index.html:ro
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1/"]
      interval: 30s
      timeout: 5s
      retries: 3
EOF

Valide a configuração antes de subir:

docker compose config

Você deve ver o Compose normalizado, parecido com:

name: nginx-test
services:
  web:
    container_name: nginx-test
    image: nginx:1.27-alpine
    ports:
      - mode: ingress
        target: 80
        published: "8080"
        protocol: tcp

Suba o serviço em segundo plano:

docker compose up -d

Saída esperada:

[+] Running 2/2
 ✔ Network nginx-test_default  Created
 ✔ Container nginx-test        Started

Confira containers e logs:

docker compose ps
docker logs --tail=20 nginx-test

Saída esperada:

NAME         IMAGE             COMMAND                  SERVICE   STATUS          PORTS
nginx-test   nginx:1.27-alpine  "/docker-entrypoint.…"   web       Up 10 seconds   0.0.0.0:8080->80/tcp

Teste localmente na própria VPS:

curl -I http://127.0.0.1:8080
curl http://127.0.0.1:8080 | grep "Docker Compose"

Resultado esperado:

HTTP/1.1 200 OK
Docker Compose funcionando na VPS

Se você quiser expor esse teste pela internet, libere a porta 8080 no firewall. Para produção, prefira publicar aplicações atrás de um proxy reverso em 80 e 443, mas o teste direto ajuda no diagnóstico:

sudo ufw allow 8080/tcp
sudo ufw status numbered

Depois acesse http://203.0.113.10:8080 no navegador, usando o IP real da VPS.

Verificação e testes

Faça uma bateria rápida de validação para confirmar que o ambiente está pronto. Comece pelo serviço Docker:

systemctl is-active docker
systemctl is-enabled docker
docker info --format 'Server: {{.ServerVersion}} | Driver: {{.Driver}} | Cgroup: {{.CgroupDriver}}'

Saída saudável:

active
enabled
Server: 27.5.1 | Driver: overlay2 | Cgroup: systemd

Verifique o Compose, containers e uso de disco:

docker compose version
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'
docker system df

Saída esperada:

Docker Compose version v2.32.4
NAMES        IMAGE              STATUS                    PORTS
nginx-test   nginx:1.27-alpine   Up 2 minutes (healthy)    0.0.0.0:8080->80/tcp
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          2         1         55MB      15MB
Containers      1         1         2B        0B

Teste a porta publicada no host:

ss -tlnp | grep 8080
curl -s http://127.0.0.1:8080 | head

Você deve ver o Docker proxy ou processo associado e o HTML criado:

LISTEN 0 4096 0.0.0.0:8080 0.0.0.0:* users:(("docker-proxy",pid=2345,fd=4))
<!doctype html>
<html lang="pt-BR">

Se a aplicação responder localmente, mas não pelo navegador externo, o problema geralmente está no firewall do sistema, firewall do provedor ou porta não publicada no Compose. Confirme o IP público com:

curl -4 ifconfig.me

Saída esperada:

203.0.113.10

Para encerrar o teste sem remover arquivos, pare o stack:

cd /opt/containers/nginx-test
docker compose down

Saída esperada:

[+] Running 2/2
 ✔ Container nginx-test        Removed
 ✔ Network nginx-test_default  Removed

Esse comando remove o container e a rede do stack, mas mantém docker-compose.yml, index.html e a imagem baixada.

Troubleshooting

Problema 1: permission denied while trying to connect to the Docker daemon socket

Esse erro aparece quando seu usuário ainda não tem acesso ao grupo docker, ou quando a sessão SSH não recarregou os grupos. Verifique:

groups
ls -l /var/run/docker.sock

Saída esperada:

deploy sudo docker
srw-rw---- 1 root docker 0 Jul 27 10:40 /var/run/docker.sock

Se docker não aparecer em groups, execute novamente:

sudo usermod -aG docker $USER

Depois saia do SSH e conecte de novo. Evite usar chmod 777 /var/run/docker.sock, porque isso expõe controle total do Docker para qualquer usuário local.

Problema 2: docker compose up -d falha com porta em uso

Se a porta 8080 já estiver ocupada, o Docker não consegue publicar o container. Confira quem está usando a porta:

sudo ss -tlnp | grep ':8080'

Exemplo de saída:

LISTEN 0 511 0.0.0.0:8080 0.0.0.0:* users:(("node",pid=1880,fd=22))

Altere o Compose para outra porta, como 8081:80, e suba novamente:

sed -i 's/8080:80/8081:80/' docker-compose.yml
docker compose up -d
curl -I http://127.0.0.1:8081

Não pare processos desconhecidos em produção sem confirmar o que eles fazem.

Problema 3: Docker não inicia após editar daemon.json

Um JSON inválido impede o serviço de subir. Veja o erro:

sudo systemctl status docker --no-pager
sudo journalctl -u docker -n 50 --no-pager

Se a mensagem indicar erro de parsing, valide o arquivo:

python3 -m json.tool /etc/docker/daemon.json

Corrija vírgulas, aspas e chaves. Se precisar voltar ao estado anterior, use o backup criado antes:

ls -1 /etc/docker/daemon.json.bak.*
sudo cp /etc/docker/daemon.json.bak.2026-07-27-1040 /etc/docker/daemon.json
sudo systemctl restart docker

Troque o nome do backup pelo arquivo real listado no seu servidor.

Problema 4: Container responde localmente, mas não pela internet

Confirme se a porta está publicada, se o UFW permite tráfego e se o provedor não bloqueia a porta:

docker ps
sudo ufw status numbered
curl -I http://127.0.0.1:8080

Se local funciona, libere a porta no UFW:

sudo ufw allow 8080/tcp

Depois teste de outra rede. Alguns painéis de cloud têm firewall externo separado do UFW. Nesse caso, crie regra de entrada TCP para 8080 ou use 80 e 443 com proxy reverso.

Próximos passos

Com Docker e Docker Compose funcionando, você já pode preparar stacks reais. O caminho mais comum é criar um diretório por aplicação em /opt/containers, versionar o docker-compose.yml em Git e usar variáveis no arquivo .env. Nunca coloque senhas diretamente em repositórios públicos. Para aplicações web, configure um proxy reverso, como Nginx, Caddy ou Traefik, e emita certificados TLS com Let’s Encrypt.

Também vale criar uma rotina de backup para volumes e bancos de dados. Antes de atualizar imagens em produção, rode docker compose pull, confira changelogs e faça snapshot da VPS ou backup dos volumes. Depois aplique docker compose up -d e valide logs, healthchecks e endpoints HTTP.

Monitore disco, memória e CPU. Containers facilitam deploy, mas não impedem falta de recursos. Use docker stats, docker system df, métricas do provedor e alertas básicos. Se o servidor hospedar muitos containers, separe banco de dados, cache e aplicação em VPS diferentes ou use volumes bem planejados. Para limpar recursos não usados, prefira comandos seguros e revisáveis:

docker system df
docker image prune

O segundo comando remove imagens não utilizadas e pede confirmação. Não use limpezas agressivas em produção sem revisar o que será removido.