# Docker Compose: guia passo a passo para configurar

> Docker Compose é uma ferramenta para definir e executar aplicações multi-container Docker. O guia passo a passo demonstra instalação, criação do arquivo docker-compose.yml e inicialização dos serviços. Docker Compose permite gerenciar dependências entre containers, volumes e redes de forma declarativa, simplificando o fluxo de trabalho de desenvolvimento e implantação de aplicações complexas.

*Pingobox · Apps e Software · 23 de julho de 2026 · Paula Andrenni*

Docker Compose simplifica a execução de aplicações multi-container. Este guia passo a passo mostra como instalar, criar um arquivo docker-compose.yml e iniciar os serviços.

Docker Compose é uma ferramenta para definir e executar aplicações multi-container no Docker. Com um arquivo YAML, você configura serviços, redes e volumes, e sobe tudo com um único comando: docker compose up.

Antes de começar, você precisa do Docker Engine instalado. O Docker Compose já vem incluso em versões recentes do Docker Desktop (Windows e Mac) e, no Linux, pode ser instalado separadamente. Verifique com docker compose version.

## Passo 1: criar o arquivo docker-compose.yml

Crie um diretório para o projeto e, dentro dele, um arquivo chamado docker-compose.yml. A versão mais recente da especificação é a 3, mas você pode omitir a linha version, o Docker Compose detecta automaticamente. Defina os serviços no bloco services. Por exemplo, para um app web com banco de dados:

services: web: image: nginx:latest ports:

- "80:80"

db: image: postgres:13 environment: POSTGRES_PASSWORD: exemplo

**Dica:** Use imagens oficiais sempre que possível. Elas são mantidas e auditadas, reduzindo riscos de segurança.

**Erro comum:** Esquecer de mapear portas. Sem ports, o serviço fica acessível apenas dentro da rede interna do Docker.

## Passo 2: subir os serviços

No terminal, dentro do diretório do projeto, execute:

docker compose up -d

A flag -d (detached) roda os containers em segundo plano. O Docker Compose baixa as imagens (se não estiverem em cache), cria as redes e inicia os containers na ordem correta.

**Dica:** Para acompanhar os logs em tempo real, use docker compose logs -f.

**Erro comum:** Rodar docker compose up sem a flag -d prende o terminal. Prefira -d em produção.

## Passo 3: verificar o funcionamento

Liste os containers ativos:

docker compose ps

Você verá os serviços web e db com status "Up". Acesse http://localhost no navegador para ver o Nginx rodando.

**Dica:** Se algo não funcionar, revise a indentação do YAML. Espaços são obrigatórios, tabulações causam erro.

## Checklist do que foi feito

- [ ] Docker Compose instalado e funcional
- [ ] Arquivo docker-compose.yml criado com ao menos dois serviços
- [ ] Containers iniciados com docker compose up -d
- [ ] Verificação com docker compose ps

## Perguntas frequentes sobre Docker Compose

### O que é Docker Compose?

É uma ferramenta do Docker para definir e executar aplicações multi-container. Você escreve um arquivo YAML com os serviços, redes e volumes, e um único comando sobe tudo.

### Docker Compose é igual a Docker Swarm?

Não. Docker Compose é para desenvolvimento e testes locais, rodando em um único host. Docker Swarm é um orquestrador para clusters de produção.

### Preciso instalar Docker Compose separadamente?

No Docker Desktop (Windows/Mac) ele já vem incluso. No Linux, instale com sudo apt install docker-compose-plugin ou baixe o binário manualmente.

### Como parar os serviços?

Use docker compose down no diretório do projeto. Isso para e remove os containers, mas mantém volumes e imagens.

### Posso usar variáveis de ambiente no arquivo YAML?

Sim. Crie um arquivo .env no mesmo diretório e use ${VARIAVEL} no docker-compose.yml. O Docker Compose lê automaticamente o arquivo.

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

docker-compose (com hífen) é a versão legada em Python. docker compose (espaço) é o plugin atual, integrado ao Docker CLI. Prefira o plugin.

---

Fonte (canonical): https://www.pingobox.com.br/apps-e-software/docker-compose-guia-passo-a-passo-para-configurar/