Docker init: como inicializar um projeto com Docker (guia passo a passo)

Por algum motivo, configurar um projeto novo com Docker sempre leva mais tempo do que deveria.

Você procura um template no Google, cola no projeto, muda algumas linhas e torce para dar certo. A build falha, então você ajusta e repete o ciclo até funcionar. Todo projeto novo começa igual — com um arquivo em branco e uma lembrança vaga do que funcionou da última vez. O problema é claro: a configuração inicial. E a culpa não é do Docker.

A boa notícia é que o docker init resolve isso. É um comando de CLI que detecta o tipo do seu projeto e gera um Dockerfile, um .dockerignore e um arquivo do Compose.

Neste artigo, vou te mostrar como o docker init funciona, como usá-lo passo a passo em um projeto real em Python e quando ele é a ferramenta certa para o trabalho.

Está começando do zero com Docker e conteinerização? Entenda por que isso é essencial no kit de ferramentas de qualquer profissional de dados fazendo nosso curso Introduction to Docker.

O que é o Docker init

docker init é uma ferramenta de CLI que configura o Docker para o seu projeto. Ela gera os arquivos de que você precisa para conteinerizar sua aplicação. Com isso, você não depende mais de templates nem de copiar e colar.

Ela produz três arquivos:

• Dockerfile — define como a imagem do seu container é construída
• .dockerignore — informa ao Docker quais arquivos devem ficar fora do contexto de build
• compose.yml — opcional, mas muito útil em configurações com vários serviços

A parte inteligente é a detecção automática do projeto. O docker init analisa a estrutura do seu projeto e identifica qual stack você está usando — Python, Node.js, Go e outras. Em seguida, gera os arquivos de acordo com essa stack, em vez de criar um template genérico.

Ele não é uma ferramenta de deploy e não vai gerenciar seus containers em produção. Ele só dá o pontapé inicial na configuração para você focar no que importa: o desenvolvimento.

Como o Docker init funciona

docker init segue um fluxo de quatro etapas toda vez que você roda o comando.

Primeiro, você executa docker init dentro da pasta do projeto. O Docker vasculha o diretório, detecta o tipo do projeto e escolhe o template de configuração adequado. Depois, guia você por um curto questionário interativo — coisas como qual porta sua aplicação usa e qual comando a inicia. Assim que você responde, ele gera os arquivos.

Tudo isso leva menos de um minuto.

As perguntas são fáceis de responder e quase nunca precisam de explicação extra. Você pode aceitar os padrões sugeridos pressionando Enter ou digitar seus próprios valores se os padrões não servirem. 

Veja o que aparece quando você roda o comando pela primeira vez:

Tela de configuração do Docker init

Agora vou te mostrar esse processo em mais detalhes.

Como usar o Docker init passo a passo

Um panorama de como sair de uma pasta de projeto para um container em execução.

Passo 1: vá até o diretório do seu projeto

Abra o terminal e navegue até a raiz do seu projeto — a pasta que contém o código da aplicação.

cd /path/to/your/project

O docker init gera arquivos relativos ao diretório onde você o executa, então garanta que está na pasta certa antes de continuar.

Passo 2: execute o Docker init

Rode o comando abaixo:

docker init

O Docker vai analisar a pasta do projeto, detectar sua stack e abrir o assistente interativo.

Passo 3: responda ao assistente

O docker init fará algumas perguntas:

• Plataforma da aplicação — a linguagem ou framework do seu projeto (Python, Node.js, Go etc.)
• Porta — a porta na qual sua aplicação escuta
• Comando de inicialização — o comando que o Docker deve executar para iniciar sua aplicação

Você pode aceitar os padrões sugeridos pressionando Enter, ou informar seus próprios valores. Se o docker init detectar sua stack, os padrões geralmente são suficientes para começar.

Passo 4: revise os arquivos gerados

Depois de responder, o docker init escreve três arquivos na pasta do projeto:

.
├── Dockerfile
├── .dockerignore
└── compose.yaml

Abra cada arquivo e leia com atenção. Os arquivos gerados incluem comentários explicando cada linha. Vale a pena gastar alguns minutos para entender o que foi criado antes de construir qualquer coisa.

Passo 5: faça a build e rode seu container

Crie e inicie seu container com o Docker Compose:

docker compose up --build

A flag --build diz ao Docker para construir a imagem a partir do seu Dockerfile antes de iniciar o container. Quando estiver rodando, sua aplicação deve estar acessível na porta que você informou no passo 3.

Tipos de projeto compatíveis com o Docker init

docker init oferece suporte, de forma nativa, às stacks de aplicação mais comuns. Aqui vão algumas:

• Python
• Node.js
• Go
• Java
• .NET

A detecção da stack é automática. Ao executar o docker init, ele analisa a pasta do projeto em busca de arquivos específicos da linguagem — como requirements.txt no Python ou package.json no Node.js — e escolhe o template adequado com base no que encontrar.

Cada template é ajustado para a stack. Um projeto em Python recebe uma imagem base, comandos de instalação e comando de inicialização diferentes de um projeto em Go. Não é um Dockerfile genérico com uma variável de linguagem trocada. A própria estrutura muda conforme o que você está construindo.

Se o docker init não conseguir detectar sua stack, ele vai pedir que você selecione manualmente a opção correta na lista.

Arquivos gerados pelo Docker init

docker init gera três arquivos, e cada um cumpre um papel específico na sua configuração.

Dockerfile

O Dockerfile define como o Docker constrói a imagem do seu container. Ele informa qual imagem base usar, como instalar dependências e qual comando executar quando o container iniciar.

Veja um exemplo de Dockerfile em Python gerado:

FROM python:3.14-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

Antes de construir, vale revisar o arquivo. O que é gerado é um ótimo ponto de partida, mas talvez você precise ajustar algo — por exemplo, adicionar variáveis de ambiente ou fixar a versão da imagem base.

.dockerignore

O .dockerignore diz ao Docker quais arquivos excluir do contexto de build — o conjunto de arquivos que o Docker envia para o mecanismo de build ao criar sua imagem.

Sem ele, o Docker copiaria tudo da pasta do projeto para a imagem, incluindo .git, node_modules e configs locais que não são necessárias em produção. Isso aumenta o tamanho da imagem e pode expor arquivos que você não queria incluir.

Um .dockerignore típico se parece com isto:

.git
.env
__pycache__
*.pyc
node_modules

Arquivo Docker Compose

O compose.yaml serve para executar configurações com vários containers. Ele define serviços, portas, volumes e como os containers se conectam entre si.

Para uma aplicação simples de um único container, talvez você não precise dele. Mas, se o seu projeto inclui banco de dados, cache ou qualquer outro serviço rodando junto com a app, é no Compose que você configura tudo em um só lugar.

Exemplo: usando o Docker init em um projeto Python

Vamos rodar o docker init em um projeto real. Vou usar uma app FastAPI mínima com uma única rota.

Esta é a estrutura do projeto antes de executar o docker init:

my-fastapi-app/
├── app.py
└── requirements.txt

app.py tem uma rota Hello World:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

E o requirements.txt traz estas duas dependências:

fastapi
uvicorn

Executando o docker init

Para começar, vá até a pasta do projeto e rode:

docker init

Projeto detectado pelo Docker init

docker init detecta Python a partir do requirements.txt e faz algumas perguntas. Veja como são os prompts e o que responder:

Prompts do Docker init para um projeto em Python

O que é gerado

Após responder, sua pasta do projeto fica assim:

Nova estrutura de pastas do projeto

São três novos arquivos. Vamos ver cada um.

O Dockerfile

# syntax=docker/dockerfile:1

ARG PYTHON_VERSION=3.14
FROM python:${PYTHON_VERSION}-slim as base

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

WORKDIR /app

ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser

RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=bind,source=requirements.txt,target=requirements.txt \
    python -m pip install -r requirements.txt

USER appuser

COPY . .

EXPOSE 8000

CMD uvicorn 'app:app' --host=0.0.0.0 --port=8000

Alguns pontos chamam a atenção. PYTHONDONTWRITEBYTECODE=1 impede o Python de escrever arquivos .pyc em disco e PYTHONUNBUFFERED=1 garante que os logs apareçam em tempo real, sem buffer — dois padrões ótimos para apps conteinerizadas.

O bloco adduser cria um usuário sem privilégios chamado appuser para rodar a aplicação. Por padrão, containers Docker rodam como root, o que é um risco de segurança. Executar como usuário não root limita o que um invasor consegue fazer se conseguir explorar sua app.

A flag --mount=type=cache no passo de pip install diz ao Docker para cachear os pacotes baixados entre builds. Assim, as builds seguintes não precisam baixar as dependências do zero, acelerando o processo.

O .dockerignore

**/.DS_Store
**/__pycache__
**/.venv
**/.env
**/.git
**/.gitignore
**/node_modules
**/Dockerfile*
**/compose.y*ml
README.md

O .dockerignore exclui arquivos que não pertencem à imagem. Arquivos locais de ambiente como .env, pastas de versionamento como .git e caches do Python como __pycache__ são ignorados. O próprio Dockerfile e o compose.yaml também ficam de fora — o Docker não precisa deles dentro da imagem que está construindo.

O compose.yaml

services:
  server:
    build:
      context: .
    ports:
      - 8000:8000

O Compose define sua app como um serviço chamado server, constrói a partir do Dockerfile no diretório atual e mapeia a porta 8000 do host para a porta 8000 no container.

Os três arquivos gerados incluem comentários que omiti aqui para manter o foco.

Execute docker compose up --build e sua app FastAPI estará no ar em http://localhost:8000.

Aplicação FastAPI rodando em um container

Docker init vs configuração manual do Dockerfile

Ambas as abordagens geram um Dockerfile funcional. A diferença está em quanto controle você precisa e com que rapidez quer chegar lá.

Docker init

docker init é a opção mais rápida. Você responde a algumas perguntas e recebe uma configuração funcional e razoavelmente segura em menos de um minuto. Os arquivos seguem as boas práticas do próprio Docker — usuário não root, cache de build, padrões adequados de .dockerignore — então você não começa do zero.

É uma boa quando você está iniciando um projeto, integrando alguém ao time ou só quer uma base sólida sem perder tempo com boilerplate.

Mas há a questão da flexibilidade. Os templates cobrem bem os casos comuns, porém ainda são templates. Se o seu projeto tem uma estrutura incomum ou requisitos específicos de build, você vai esbarrar nos limites do que o docker init consegue gerar.

Configuração manual

Escrever seu Dockerfile à mão dá controle total sobre cada layer, cada instrução e cada decisão de build. Você pode implementar builds multi-stage para reduzir a imagem, usar imagens base personalizadas ou ajustar o comportamento de cache de formas que o docker init não prevê.

Por outro lado, é preciso saber o que está fazendo. Um Dockerfile mal escrito pode gerar imagens grandes demais, abrir brechas de segurança ou falhar de maneiras difíceis de depurar — especialmente se você ainda não tem tanta experiência.

Qual usar

Uma forma simples de decidir:

Comparação entre Docker init e configuração manual

Uma boa estratégia é começar com o docker init e editar manualmente os arquivos gerados conforme as necessidades forem crescendo.

Quando usar o Docker init

docker init não é a ferramenta certa para toda situação. Veja quando faz sentido — e quando não faz.

Use o docker init quando:

• Você está começando um projeto novo: ele coloca sua configuração Docker de pé em menos de um minuto, para você focar no código em vez da conteinerização

• Você está aprendendo Docker: os arquivos gerados são bem comentados e seguem boas práticas. São um ponto de partida melhor do que um snippet aleatório do Stack Overflow

• Você está prototipando: quando você precisa de um ambiente conteinerizado rápido e não se importa em ajustar a build depois, o docker init te entrega algo funcional

• Você quer padronizar no time: em vez de cada dev criar seu próprio Dockerfile, o docker init dá a todos um ponto de partida consistente, com a mesma estrutura e padrões

Por outro lado, evite o docker init quando:

• Você precisa de builds multi-stage: se você otimiza o tamanho da imagem dividindo a build em estágios — compilação em um, execução em outro — terá que escrever isso manualmente. O Dockerfile gerado é de estágio único

• Você tem requisitos complexos de produção: imagens base customizadas, estratégias avançadas de cache, layouts de projeto não padrão — nada disso o docker init consegue prever. Você gastará mais tempo contornando os arquivos gerados do que escrevendo os seus

Em resumo, o docker init é um ponto de partida. Use para ganhar velocidade e depois edite os arquivos gerados conforme as necessidades evoluírem.

Limitações do Docker init

Conforme o projeto cresce, algumas limitações podem aparecer. Aqui estão algumas.

Os arquivos gerados são baseados em templates. Eles cobrem os casos mais comuns de cada stack compatível, o que significa que funcionam muito bem para projetos típicos e menos bem para o que fugir desse escopo. Se seu projeto tem estrutura incomum, talvez os arquivos gerados não contemplem isso.

Outra limitação comum é que ajustes manuais quase sempre serão necessários. Os padrões são bons, mas ainda assim são padrões. Você provavelmente vai precisar ajustar a versão da imagem base, mexer em variáveis de ambiente ou alterar o comando de inicialização até a configuração ficar redonda para seu projeto. Pense nos arquivos gerados como um primeiro rascunho — nada além disso.

docker init também não cobre padrões avançados de build. Builds multi-stage, argumentos de build customizados, lógica condicional e outras técnicas usadas por times experientes para imagens de produção ficam fora do escopo do que a ferramenta gera. E, se você precisa disso, provavelmente já vai escrever o Dockerfile na mão mesmo.

Nada disso torna o docker init uma ferramenta ruim. Só significa que é preciso ter a expectativa certa — ele elimina o problema da página em branco, mas não substitui a necessidade de entender o que há no seu Dockerfile.

Boas práticas após usar o Docker init

Os arquivos que o docker init gera são um começo. Veja os passos para deixá-los prontos para produção.

• Revise os arquivos gerados: leia o Dockerfile, o .dockerignore e o compose.yaml linha a linha. Eles são bem comentados, então não vai demorar. Entenda o que está ali antes de construir em cima

• Otimize o tamanho da imagem: a imagem base padrão é python:3.x-slim, já bem enxuta. Mas você pode ir além garantindo que o .dockerignore está excluindo tudo que deve e verificando se não está copiando para a imagem arquivos desnecessários

• Mova segredos e valores específicos de ambiente para variáveis de ambiente: não deixe chaves de API, URLs de banco ou flags de ambiente hardcoded no Dockerfile. Use variáveis de ambiente e gerencie-as via arquivo .env localmente ou pelo gerenciador de segredos da sua plataforma de deploy em produção

• Teste localmente antes de enviar para qualquer lugar: rode docker compose up --build e verifique se a app se comporta igual dentro e fora do container. Cheque os logs, acesse os endpoints e confirme o mapeamento de portas

• Refine os passos de build conforme o projeto crescer: o Dockerfile gerado instala dependências em uma única layer. À medida que o projeto amadurecer, pense na ordem das camadas. Em outras palavras, coloque antes os passos que mudam com menos frequência para o Docker poder cacheá-los. Se o tempo de build começar a aumentar, esse é o primeiro ponto a revisar

Problemas comuns e como resolver

Como sempre em tecnologia, algumas coisas podem dar errado. Veja o que observar e como corrigir.

Detecção incorreta do projeto

Se o docker init escolher a stack errada, vai gerar arquivos que não combinam com o seu projeto. Isso costuma acontecer quando a pasta tem arquivos de múltiplas linguagens ou quando falta o arquivo que o docker init procura — como requirements.txt no Python ou package.json no Node.js.

Quando o assistente perguntar pela plataforma da aplicação, selecione manualmente a correta em vez de aceitar o padrão detectado.

Conflitos de porta

Se o container inicia mas você não consegue acessar a app, ou o Docker acusa que a porta já está em uso, provavelmente outro processo na sua máquina está ocupando a mesma porta.

Encontre e pare o processo em conflito ou altere a porta do host no seu compose.yaml:

ports:
  - 8001:8000  # mapeia a porta 8001 do host para a 8000 do container

O lado esquerdo é a porta da sua máquina. O lado direito precisa bater com a porta em que a app escuta dentro do container.

Dependências ausentes

Se o container constrói mas cai ao iniciar, dependências faltando são uma causa comum. Confira se o seu requirements.txt (ou equivalente) está completo e atualizado. Se você adicionou um pacote localmente sem atualizar o arquivo, o container não vai ter esse pacote.

Rode docker compose logs para ver o erro:

docker compose logs

A mensagem geralmente indica exatamente qual pacote está faltando.

Container não inicia

Se o container nem chega a iniciar, o problema quase sempre está na linha CMD do seu Dockerfile. Verifique se o comando de inicialização bate com a forma como você roda a app.

No exemplo com FastAPI, deve ficar assim:

CMD uvicorn 'app:app' --host=0.0.0.0 --port=8000

Se o arquivo de entrada tiver outro nome ou o caminho do módulo estiver errado, o container vai encerrar. Corrija o CMD, reconstrua com docker compose up --build e confira os logs novamente.

Conclusão

docker init não substitui um entendimento profundo de Docker, mas elimina o bloqueio da página em branco.

Com um único comando, você recebe um Dockerfile, um .dockerignore e um compose.yml prontos — todos seguindo as boas práticas do Docker. É uma base excelente para qualquer projeto novo e muito melhor do que um template copiado do Stack Overflow ou do ChatGPT.

Só não pare por aí. Os arquivos gerados foram feitos para serem editados. Revise-os, ajuste os passos de build, fixe a versão da imagem base e adicione suas variáveis de ambiente. Quanto mais o projeto crescer, mais você vai se afastar dos padrões.

Se você já domina o básico de Docker, o próximo passo lógico é aprender sobre builds multi-stage, ferramentas de rede e Docker Compose — tudo isso está no nosso curso Intermediate Docker .