Docker Compose: como usar na VPS, passo a passo

Veja como usar o Docker Compose na VPS: o arquivo compose.yaml, um exemplo com docker compose up -d, os comandos do dia a dia, o arquivo .env e os cuidados com volumes.

Por Redação Eleven Host · @robson.direitodigital · 28 de outubro de 2026 · 8 min de leitura

O Docker Compose sobe vários contêineres a partir de um arquivo compose.yaml, com um só comando: docker compose up -d. Você descreve os serviços uma vez, no arquivo, e o Compose cria e inicia tudo.

Este guia explica o que é o Compose, como conferir o plugin na VPS, como escrever o arquivo, como subir um exemplo simples, quais comandos usar no dia a dia e como guardar variáveis no .env. Ele segue a documentação oficial do Docker. Os nomes seudominio.com.br e 203.0.113.10 são exemplos. Troque pelos seus.

O que é o Docker Compose

Segundo a documentação do Docker, o Docker Compose é uma ferramenta para definir e executar aplicações com vários contêineres. Ele gerencia serviços, redes e volumes em um único arquivo YAML e, com um único comando, você cria e inicia os serviços.

Em palavras simples: sem o Compose, você digitaria um comando longo de docker run para cada contêiner, com portas, pastas e variáveis. Com o Compose, tudo isso fica escrito num arquivo que você guarda, lê e repete. Um site com banco de dados, por exemplo, vira dois serviços no mesmo arquivo.

Um detalhe de nome importa. A documentação explica que o Compose v1, o comando docker-compose com hífen, foi substituído pelo Compose v2, que é o docker compose com espaço, um plugin do Docker. A documentação diz que o v1 não tem mais manutenção e que os usuários devem migrar para o v2. Por isso, este guia usa a forma com espaço.

Antes de começar

Você precisa de um servidor Ubuntu, de um usuário com sudo e do Docker instalado. Se ainda não instalou, siga o guia Instalar Docker na VPS Ubuntu: passo a passo seguro.

Confira se o plugin do Compose está presente:

docker compose version

Se o comando mostrar a versão, o plugin está instalado. Se der erro de comando não encontrado, instale o plugin. A documentação do Docker indica, para Ubuntu e Debian, estes comandos, com o Docker instalado pelo repositório oficial:

sudo apt-get update

sudo apt-get install docker-compose-plugin

Rode docker compose version de novo para conferir. Se o seu usuário não estiver no grupo do Docker, coloque sudo antes dos comandos docker deste guia.

O arquivo compose.yaml

O nome padrão do arquivo é compose.yaml. A documentação diz que o caminho padrão é compose.yaml (preferido) ou compose.yml, e que docker-compose.yaml e docker-compose.yml ainda funcionam por compatibilidade. O arquivo é escrito em YAML, em que o recuo com espaços indica o que pertence a quê. Use espaços, não a tecla Tab.

Tudo começa pela chave services, onde cada serviço vira um contêiner. Estas são as chaves usadas neste guia:

• image é a imagem do serviço, no formato [registry/][projeto/]imagem[:tag]. Exemplos da documentação: redis e redis:5.
• ports publica portas no formato [HOST:]CONTAINER[/PROTOCOLO], como "8000:8000" ou "127.0.0.1:8001:8001". Sem o IP do host, a porta fica aberta nas interfaces de rede do servidor (0.0.0.0). Quando o serviço ficar atrás de um Nginx na mesma VPS, prefira o formato com 127.0.0.1.
• volumes liga pastas e volumes ao contêiner, no formato VOLUME:CAMINHO_NO_CONTAINER ou com o modo de acesso no fim. Os modos são rw (leitura e escrita, o padrão) e ro (somente leitura).
• environment define variáveis de ambiente, em formato de mapa (RACK_ENV: development) ou de lista (- RACK_ENV=development). Valores como true devem ir entre aspas para o YAML não convertê-los.
• restart diz quando reiniciar o contêiner: no (o padrão, não reinicia), always (reinicia até o contêiner ser removido), on-failure (só quando sai com erro) e unless-stopped (reinicia, exceto depois de você parar ou remover o serviço).

Quer um servidor para os seus projetos? O Plano Bronze da VPS sai a partir de R$ 17,00/mês; confira na loja o que cada plano inclui. Ver planos de VPS

Passo a passo: um exemplo simples

Vamos subir um servidor web Nginx dentro de um contêiner, servindo uma página sua. Siga a ordem, porque cada passo usa o que o anterior criou.

1. Crie a pasta do projeto e entre nela:

mkdir meu-app

cd meu-app

2. Crie a pasta da página e um arquivo de teste. Faça isso antes de subir o contêiner, porque o Compose vai ligar essa pasta a ele:

mkdir site

echo "<h1>Olá do Compose</h1>" > site/index.html

3. Crie o arquivo compose.yaml com um editor, por exemplo nano compose.yaml, e cole:

services:

web:

image: nginx:stable

ports:

- "8080:80"

volumes:

- ./site:/usr/share/nginx/html:ro

restart: unless-stopped

O serviço se chama web. A porta 8080 da VPS leva ao 80 do contêiner. A pasta local ./site vira a pasta de páginas do contêiner, em modo somente leitura. Esse caminho dentro do contêiner é o da imagem oficial do Nginx; confira na página da imagem se você usar outra. O restart: unless-stopped reinicia o contêiner, exceto depois que você parar o serviço.

4. Suba o serviço em segundo plano:

docker compose up -d

A documentação explica que o -d roda os contêineres em segundo plano e que o up cria, inicia e conecta os contêineres. Na primeira vez, o Docker baixa a imagem.

5. Confira se subiu:

docker compose ps

O comando lista os serviços e o estado de cada um. Depois abra http://203.0.113.10:8080 no navegador, trocando pelo IP da sua VPS. Deve aparecer "Olá do Compose". Se não abrir, veja se o firewall do servidor permite a porta 8080.

Comandos do dia a dia

Rode estes comandos dentro da pasta onde está o compose.yaml:

• docker compose ps lista os serviços e o estado.
• docker compose logs mostra a saída dos contêineres. Com -f você acompanha ao vivo, e com --tail 50 vê só as últimas 50 linhas.
• docker compose pull baixa as imagens mais novas, mas não inicia contêineres.
• docker compose up -d também aplica mudanças: se a configuração ou a imagem mudou, o Compose para e recria os contêineres e mantém os volumes.
• docker compose down para e remove os contêineres e as redes do arquivo.

Para atualizar a imagem de um serviço, uma sequência comum é baixar e subir de novo:

docker compose pull

docker compose up -d

O segundo comando recria o que mudou. Faça um backup dos dados antes de atualizar serviços com banco de dados.

Variáveis no arquivo .env

Em vez de escrever valores direto no compose.yaml, você pode guardá-los num arquivo .env. A documentação diz que o .env deve ficar na raiz do projeto, ao lado do compose.yaml. Exemplo: no .env você escreve a linha TAG=stable e, no compose.yaml, troca a linha da imagem por:

image: "nginx:${TAG}"

O Compose troca ${TAG} pelo valor do arquivo e a imagem vira nginx:stable. Segundo a documentação, as variáveis do shell têm prioridade sobre as do arquivo. Para ver o arquivo já com os valores no lugar, use:

docker compose config

Para passar um arquivo de variáveis para dentro do contêiner, o Compose tem a chave env_file. Quando a mesma variável aparece nas duas formas, o valor de environment tem prioridade sobre o de env_file.

Cuidados

Alguns pontos merecem atenção antes de usar o Compose em algo que importa:

• Volumes e o down -v: o docker compose down comum remove só os contêineres e as redes. O -v (ou --volumes) remove também os volumes nomeados declarados no arquivo e os volumes anônimos ligados aos contêineres.
• Senhas fora do repositório: não coloque o .env com senhas num repositório público do git, e restrinja a permissão do arquivo, por exemplo com chmod 600 .env.
• Portas abertas: uma porta publicada sem o IP do host fica aberta nas interfaces de rede do servidor. Use 127.0.0.1 quando só o Nginx da mesma VPS precisa falar com o serviço.
• Reinício automático: o restart reinicia o contêiner conforme a regra, mas não substitui acompanhar os logs e o estado do serviço.

Próximos passos

Com o básico funcionando, o passo seguinte é rodar algo de verdade. O n8n é um bom caso para o Compose: veja o guia Instalar n8n na VPS: passo a passo com Docker e, para juntar o n8n a um banco, o guia n8n com PostgreSQL: como configurar no Docker Compose. Para manter o n8n em dia depois, siga o Atualizar n8n no Docker: passo a passo com backup.

Vai publicar o projeto com um endereço próprio? Registre o domínio do seu site. Registrar domínio

Perguntas frequentes

Qual a diferença entre docker compose e docker-compose?

O docker compose, com espaço, é o Compose v2, um plugin do Docker. O docker-compose, com hífen, é o Compose v1, que segundo a documentação foi substituído e não tem mais manutenção.

O campo version no topo do arquivo é necessário?

Não. O Compose v2 ignora o campo version: no topo do arquivo, então você pode começar direto por services:.

Como ver os logs de um serviço no Compose?

Use docker compose logs. Com -f você acompanha ao vivo e com --tail escolhe quantas linhas do fim mostrar.

O docker compose down apaga meus dados?

O down comum remove contêineres e redes. Os volumes só são removidos com -v ou --volumes, e é isso que apaga bancos de dados e uploads guardados neles.