Docker: Iniciar um contêiner com `docker run`

Última atualização: 2026-08-26

docker run é o comando Docker mais usado — ele cria e inicia um contêiner. Dominar seus parâmetros significa dominar os fundamentos da execução de contêineres.

1. O Que Você Vai Aprender

• Parâmetros principais do docker run
• Modos de Operação em Primeiro Plano vs. Segundo Plano
• Mecanismo de mapeamento de portas
• Nomeação de Contêineres e Limpeza Automática
• Limitações de recursos (CPU/memória)

2. Uma História Real de uma Pessoa Desenvolvedora Backend

(1) Ponto de Dor: Conflitos Entre Múltiplas Versões de Banco de Dados

Alice precisa executar três versões do PostgreSQL — v15, v14 e v13 — simultaneamente em sua máquina local para testar compatibilidade. Com o método de instalação tradicional, ela só pode instalar uma versão por vez, e alternar entre versões exige desinstalar e reinstalar, o que leva 30 minutos a cada vez. Para piorar, os arquivos de configuração e diretórios de dados de versões diferentes podem entrar em conflito entre si.

(2) Soluções para Execução Paralela de Vários Contêineres Docker

Usando Docker, ela iniciou três instâncias do PostgreSQL com um único conjunto de comandos, cada uma mapeada para uma porta diferente.

# Executar três versões do PostgreSQL lado a lado
docker run -d --name pg15 -e POSTGRES_PASSWORD=secret -p 5432:5432 postgres:15
docker run -d --name pg14 -e POSTGRES_PASSWORD=secret -p 5433:5432 postgres:14
docker run -d --name pg13 -e POSTGRES_PASSWORD=secret -p 5434:5432 postgres:13

(3) Benefícios: Múltiplas versões rodando em paralelo com zero conflitos

Com três instâncias do PostgreSQL rodando em paralelo sem interferir umas nas outras, Alice concluiu o teste de compatibilidade entre versões em 5 minutos — uma tarefa que levaria 2 horas usando o método tradicional.

3. Sintaxe e Parâmetros Principais do docker run

(1) Sintaxe Básica

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

(2) Tabela de Referência Rápida para Parâmetros Comuns

4. Execução em Primeiro Plano vs. Segundo Plano

Os contêineres têm dois modos de execução: primeiro plano e segundo plano, controlados por -it e -d.

(1) Comparação dos Modos de Operação

▶ Exemplo: Iniciando o serviço Nginx em segundo plano (Dificuldade: ⭐)

# Executar Nginx no modo detached
docker run -d -p 8080:80 --name web nginx:latest

# Visualizar logs do contêiner em segundo plano
docker logs web

a1b2c3d4e5f6... (ID do contêiner)
/docker-entrypoint.sh: Launching nginx...

▶ Exemplo: Iniciando um Contêiner Ubuntu Interativo (Dificuldade: ⭐⭐)

# Executar Ubuntu com terminal interativo
docker run -it ubuntu:22.04 bash

# Dentro do contêiner: verificar informações do SO
cat /etc/os-release

# Sair do contêiner
exit

root@a1b2c3d4e5f6:/# cat /etc/os-release
NAME="Ubuntu"
VERSION="22.04.3 LTS (Jammy Jellyfish)"
...
root@a1b2c3d4e5f6:/# exit

5. Mapeamento de Portas

Por padrão, as portas de serviço dentro de um contêiner não são acessíveis do lado de fora; o mapeamento de portas expõe as portas do contêiner para o host.

graph LR
    A["Host<br/>Porta 8080"] -->|"-p 8080:80"| B["Contêiner<br/>Porta 80"]
    C["Host<br/>Porta 5432"] -->|"-p 5432:5432"| D["Contêiner<br/>Porta 5432"]

graph LR
    A["Host<br/>Porta 8080"] -->|"-p 8080:80"| B["Contêiner<br/>Porta 80"]
    C["Host<br/>Porta 5432"] -->|"-p 5432:5432"| D["Contêiner<br/>Porta 5432"]

(1) Política de Mapeamento de Portas

▶ Exemplo: Mapeamento de Múltiplas Portas para PostgreSQL (Dificuldade: ⭐⭐)

# Executar PostgreSQL com mapeamento de porta e variáveis de ambiente
docker run -d \
  --name pg15 \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=myapp \
  -p 5432:5432 \
  postgres:15

# Conectar ao PostgreSQL
docker exec -it pg15 psql -U postgres -d myapp

myapp=# \l
                                  List of databases
   Name    |  Owner   | Encoding |  Collate   |   Ctype    
-----------+----------+----------+------------+------------
 myapp     | postgres | UTF8     | en_US.utf8 | en_US.utf8
 postgres  | postgres | UTF8     | en_US.utf8 | en_US.utf8

6. Limpeza Automática e Políticas de Reinicialização

(1) Contêiner Temporário --rm

--rm Exclui automaticamente o contêiner após sua saída; adequado para tarefas únicas.

▶ Exemplo: Executando uma tarefa temporária com --rm (Dificuldade: ⭐)

# Executar um comando único, o contêiner é removido automaticamente após a saída
docker run --rm alpine:latest echo "Hello from Alpine!"

# Verificar: o contêiner desapareceu
docker ps -a

Hello from Alpine!

(2) Política de Reinicialização

A política de reinicialização determina se um contêiner é reiniciado automaticamente após sua saída.

▶ Exemplo: Configurando Reinicialização Automática (Dificuldade: ⭐⭐)

# Executar Nginx com política de reinicialização
docker run -d --name web --restart=always -p 8080:80 nginx:latest

# Simular falha: matar o processo do contêiner
docker kill web

# Aguardar alguns segundos, verificar: reiniciou automaticamente
docker ps

CONTAINER ID   IMAGE          STATUS                     PORTS                  NAMES
b2c3d4e5f6a7   nginx:latest   Up 3 seconds (healthy)     0.0.0.0:8080->80/tcp   web

7. Limitações de Recursos

O Docker pode limitar a quantidade de CPU e memória usada pelos contêineres, evitando que um único contêiner esgote os recursos do host.

(1) Parâmetros de Limite de Recursos

▶ Exemplo: Limitar a memória do contêiner a 256MB (Dificuldade: ⭐⭐)

# Executar um contêiner com limite de memória de 256 MB
docker run -d --name limited-app --memory=256m nginx:latest

# Verificar o limite de memória
docker inspect limited-app --format='{{.HostConfig.Memory}}'

268435456

8. Ciclo de Vida do Contêiner e Transições de Estado

stateDiagram-v2
    [*] --> Created : docker create / docker run
    Created --> Running : docker start / docker run
    Running --> Paused : docker pause
    Paused --> Running : docker unpause
    Running --> Stopped : docker stop / docker kill
    Stopped --> Running : docker start
    Running --> Restarting : crash + política de reinicialização
    Restarting --> Running : reinicialização bem-sucedida
    Stopped --> Deleted : docker rm
    Running --> Deleted : docker rm -f
    Deleted --> [*]

stateDiagram-v2
    [*] --> Created : docker create / docker run
    Created --> Running : docker start / docker run
    Running --> Paused : docker pause
    Paused --> Running : docker unpause
    Running --> Stopped : docker stop / docker kill
    Stopped --> Running : docker start
    Running --> Restarting : crash + política de reinicialização
    Restarting --> Running : reinicialização bem-sucedida
    Stopped --> Deleted : docker rm
    Running --> Deleted : docker rm -f
    Deleted --> [*]

9. Exemplo Completo: Iniciando um Contêiner PostgreSQL com Variáveis de Ambiente

# ============================================
# Passo a passo completo: Executar PostgreSQL com Docker
# Abrange: -d, -e, -p, --name, --restart, --memory
# ============================================

# 1. Executar PostgreSQL 15 com configuração completa
docker run -d \
  --name pg15 \
  -e POSTGRES_USER=appuser \
  -e POSTGRES_PASSWORD=secret123 \
  -e POSTGRES_DB=appdb \
  -p 5432:5432 \
  --restart=unless-stopped \
  --memory=512m \
  postgres:15

# 2. Verificar se o contêiner está em execução
docker ps

# 3. Conectar via cliente psql dentro do contêiner
docker exec -it pg15 psql -U appuser -d appdb

# 4. Dentro do psql: criar uma tabela de teste
# CREATE TABLE users (id SERIAL PRIMARY KEY, name VARCHAR(100));
# INSERT INTO users (name) VALUES ('Alice'), ('Bob');
# SELECT * FROM users;

# 5. Verificar uso de recursos do contêiner
docker stats pg15 --no-stream

# 6. Visualizar configuração do contêiner
docker inspect pg15 --format='Memory: {{.HostConfig.Memory}}, RestartPolicy: {{.HostConfig.RestartPolicy.Name}}'

# docker ps
CONTAINER ID   IMAGE         STATUS         PORTS                    NAMES
a1b2c3d4e5f6   postgres:15   Up 30 seconds  0.0.0.0:5432->5432/tcp   pg15

# docker stats --no-stream
CONTAINER ID   NAME   CPU %   MEM USAGE / LIMIT   MEM %
a1b2c3d4e5f6   pg15   0.02%   38.5MiB / 512MiB    7.52%

# docker inspect --format
Memory: 536870912, RestartPolicy: unless-stopped

❓ Perguntas Frequentes

P: -d e -it podem ser usados juntos? R: Não. -d executa em segundo plano, enquanto -it é um terminal interativo; os dois são mutuamente exclusivos. Se você precisar executar o contêiner em segundo plano e acessá-lo ocasionalmente, inicie-o com -d e depois use docker exec -it para entrar no contêiner.

P: Os dados serão perdidos quando o contêiner sair? R: Se você não usou -v para montar um volume, os dados serão perdidos quando o contêiner for excluído. Os dados permanecem após o contêiner ser parado (stop), mas desaparecem após serem excluídos (rm). Para persistir dados, você deve usar um volume ou uma montagem bind.

P: --rm Quando deve ser usado? R: Tarefas únicas: executar testes, executar scripts, verificar versões de ferramentas. Não adequado para serviços que exigem dados persistentes. --rm deve ser adicionado a quase todas as etapas em pipelines CI/CD para evitar acúmulo de contêineres nos nós de build.

P: -p 8080:80 Qual dos dois números de porta é qual? R: A porta à esquerda (8080) é a porta do host, e a da direita (80) é a porta do contêiner. Mnemônico: "Esquerda é o host, direita é o contêiner." Acessar IP do host:8080 levará você ao serviço rodando na porta 80 dentro do contêiner.

P: Quanto espaço em disco um contêiner ocupa? R: A camada gravável (a porção modificável) de cada contêiner normalmente ocupa apenas alguns KB a algumas dezenas de MB. Os contêineres não replicam a imagem; em vez disso, compartilham a camada somente leitura da imagem. Uso total = tamanho da imagem + camada gravável do contêiner. Use docker system df para ver o uso detalhado.

P: Como visualizar todos os parâmetros do docker run? R: docker run --help lista todos os parâmetros. Os 15 ou mais usados com mais frequência (abordados nesta aula) estão listados lá; consulte o restante conforme necessário.

📖 Resumo

• docker run = Criar e iniciar um contêiner; este é o comando Docker mais essencial
• -d Executa como serviço em segundo plano; -it Depuração interativa; os dois são mutuamente exclusivos
• Mapeamento de Portas -p host:contêiner Expõe Serviços do Contêiner para o Host
• --rm é usado para limpeza automática de tarefas temporárias; --restart é usado para recuperação automática de serviço
• --memory / --cpus Limitam recursos para evitar que um único contêiner use todos os recursos do host
• Os contêineres têm um ciclo de vida de estado completo: Created → Running → Paused → Stopped → Deleted

📝 Exercícios

1. Exercício Básico (Dificuldade: ⭐): Inicie um contêiner Nginx mapeado para a porta 8080 em sua máquina local, depois acesse-o via navegador para verificar se a página é exibida corretamente.
2. Problema Avançado (Dificuldade: ⭐⭐): Inicie um contêiner Ubuntu interativo, execute apt update && apt install -y curl dentro do contêiner e, em seguida, use curl para acessar uma página da web.
3. Desafio (Dificuldade: ⭐⭐⭐): Com a memória do contêiner limitada a 256MB, execute uma ferramenta de teste de estresse (como progrium/stress) e observe se o contêiner é encerrado por um erro OOM (Out of Memory) quando a memória é excedida (Dica: docker events --filter event=oom).

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós