Docker ENTRYPOINT Explicado: Uso, sintaxe e práticas recomendadas

O Docker ENTRYPOINT é uma instrução do Dockerfile que define e controla o comando padrão executado sempre que o contêiner é iniciado. Dominar o ENTRYPOINT simplifica o desenvolvimento de contêineres previsíveis, reproduzíveis e passíveis de manutenção que se comportam conforme o esperado. 

Este guia tem o objetivo de ajudar engenheiros de DevOps intermediários, desenvolvedores de back-end e engenheiros de software a usar com confiança o site ENTRYPOINT e evitar armadilhas comuns.

Se você não conhece o Docker, consulte nosso tutorial de introdução ao Docker, pois este tutorial pressupõe algum nível de entendimento do Docker. Para você começar a trabalhar com o Docker, confira nosso curso Introdução ao Docker. 

O que é o Docker ENTRYPOINT?

ENTRYPOINT define o comando executado por padrão sempre que o contêiner do Docker é iniciado. Ao contrário do uso de CMD, a instrução ENTRYPOINT garante a consistência ao fornecer comandos que são executados sempre que o contêiner é iniciado.

Como funciona o Docker ENTRYPOINT?

ENTRYPOINT em um Dockerfile define o comando principal que sempre é executado quando você inicia um contêiner a partir de uma imagem. É como se você dissesse:  "Independentemente dos argumentos que o usuário passar ao executar esse contêiner, sempre comece com esse comando."

Você encontrará mais detalhes sobre os Dockerfiles em nosso tutorial Como colocar um aplicativo em contêiner usando o Docker. 

Por exemplo, em um Dockerfile:

ENTRYPOINT ["python", "app.py"]

Agora, quando você correr:

docker run myimage

Ele sempre será executado:

python app.py

Aqui está um diagrama de fluxo de como funciona o ENTRYPOINT:

+---------------------------+

|       Dockerfile          |

+---------------------------+

|                           |

|  ENTRYPOINT ["app"]       |

|  CMD ["--default-arg"]    |

+---------------------------+

             |

             v

+---------------------------+

|   Build Docker Image      |

+---------------------------+

             |

             v

+---------------------------+

|    Run Container          |

|   (docker run image)      |

+---------------------------+

             |

             v

+---------------------------+

| Executed Command:         |

|   app --default-arg       |

+---------------------------+

Override CMD at Runtime:

(docker run image --custom-arg)

             |

             v

+---------------------------+

| Executed Command:         |

|   app --custom-arg        |

+---------------------------+

Override ENTRYPOINT at Runtime:

(docker run --entrypoint /bin/bash image)

             |

             v

+---------------------------+

| Executed Command:         |

|   /bin/bash               |

+---------------------------+

Fundamentos do Docker ENTRYPOINT

Compreender os fundamentos aumentará significativamente sua confiança no uso eficaz do ENTRYPOINT.

Estrutura conceitual

ENTRYPOINT especifica o executável ou script que é executado automaticamente quando o contêiner é iniciado. É o processo principal do seu contêiner, que conduz o comportamento do contêiner de forma previsível.

Sintaxe básica

A sintaxe do Dockerfile para ENTRYPOINT é simples e geralmente é usada junto com CMD para fornecer argumentos ou parâmetros padrão. ENTRYPOINT define o executável, enquanto CMD especifica os argumentos padrão que ENTRYPOINT usa.

Compreender os conceitos do Docker, como o ENTRYPOINT, é fundamental para que você seja bem-sucedido em entrevistas sobre ciência de dados. Explore perguntas comuns de entrevistas em nossas 26 principais perguntas e respostas de entrevistas sobre o Docker para 2025. 

Formulários de sintaxe do ENTRYPOINT

O Docker ENTRYPOINT vem em duas formas distintas: shell e exec. Conhecer as diferenças entre essas formas pode ajudar você a escolher sabiamente.

Forma de concha

Exemplo de sintaxe: 

ENTRYPOINT /usr/bin/ping -c 3 localhost

O formato de shell garante a fácil integração dos recursos de shell (substituição de variáveis, manipulação de ambiente).

No entanto, isso pode levar a um tratamento de sinal ruim; ele é executado dentro do processo intermediário /bin/sh em vez de diretamente como PID 1, causando problemas com a interrupção e reinicialização de contêineres.

O PID 1 é o primeiro processo que é iniciado durante a inicialização do sistema. No Docker, o processo PID 1 gerencia todos os outros processos dentro do contêiner. 

Formulário de execução

Exemplo de sintaxe: 

ENTRYPOINT ["/usr/bin/ping", "-c", "3"]

O formulário Exec garante a execução direta do comando como PID 1, levando a um controle e manuseio confiáveis do sinal.

No entanto, ele não tem suporte direto ao shell nem expansão automática de variáveis de ambiente; requer scripts adicionais para um comportamento semelhante ao do shell.

ENTRYPOINT vs. CMD: Principais diferenças e casos de uso

A distinção entre ENTRYPOINT e CMD evita confusão e permite um comportamento previsível do contêiner.

Precedência de execução

ENTRYPOINT define o executável sempre em execução, enquanto CMD fornece argumentos padrão. Se ambos ENTRYPOINT e CMD estiverem definidos, ENTRYPOINT terá precedência e será executado usando os valores de CMDcomo argumentos, a menos que você os substitua explicitamente em tempo de execução.

Cenários de casos de uso

ENTRYPOINT deve ser usado quando você quiser uma execução consistente e imposta a cada inicialização, como contêineres de comando único ou scripts de wrapper em torno de aplicativos legados. Por outro lado, CMD é adequado para especificar argumentos padrão, permitindo mais flexibilidade com substituições em tempo de execução.

Nossos 18 principais comandos do Docker para criar, executar e gerenciar contêineres abrangem os comandos essenciais do Docker, desde os conceitos básicos de contêineres até volumes e redes, para que você possa gerenciar aplicativos em ambientes com confiança.

Exemplo prático

Uma combinação típica de ENTRYPOINT e CMD é ilustrada por este Dockerfile:

FROM ubuntu
ENTRYPOINT ["/usr/bin/ping", "-c", "3"]
CMD ["localhost"]

Esse contêiner do Docker sempre emite três pings por padrão contra o localhost. Os usuários podem substituir esse destino padrão em tempo de execução com outros hosts facilmente, mantendo o comportamento de execução previsível do ENTRYPOINT:

docker run ping-container google.com

Você pode saber mais sobre a implantação de aplicativos com o Docker em nosso curso Containerization and Virtualization with Docker and Kubernetes. 

Combinação de ENTRYPOINT com CMD

A combinação adequada de ENTRYPOINT com CMD oferece flexibilidade sem sacrificar a consistência.

CMD como argumentos padrão

A configuração de ENTRYPOINT define o comando principal de forma confiável; CMD fornece parâmetros padrão para substituições fáceis sem reconstruir imagens.

Substituições de argumentos em tempo de execução

Os argumentos especificados durante docker run substituem apenas os padrões definidos pelo CMD. ENTRYPOINT permanece consistente, simplificando assim a experiência dos usuários.

Substituição do ENTRYPOINT em tempo de execução

O Docker permite que você substitua o ENTRYPOINT diretamente no tempo de execução, possibilitando a depuração sem reconstruir a imagem do Dockerfile.

Uso do sinalizador de ponto de entrada

O Docker oferece um sinalizador simples --entrypoint que altera temporariamente o comportamento do contêiner.

docker run -it --entrypoint /bin/bash my-container

As substituições temporárias permitem a solução de problemas usando o shell, resolvendo problemas comuns de inicialização sem reconstruções de imagem ou atrasos substanciais.

Personalizando o comportamento do ENTRYPOINT

O Docker oferece flexibilidade quando o ENTRYPOINT exige uma personalização mais avançada.

Substituir o ENTRYPOINT em tempo de execução

Você pode substituir o comando ENTRYPOINT dinamicamente no tempo de execução usando docker run --entrypoint para depurar ou alterar contextos rapidamente sem modificar o Dockerfile repetidamente.

ENTRYPOINT com argumentos

Os argumentos passados para os contêineres tornam-se parâmetros ENTRYPOINT em tempo de execução; as práticas recomendadas sugerem que você tenha uma complexidade mínima ENTRYPOINT juntamente com CMD para obter o máximo de clareza e controle.

Scripts de wrapper

Os scripts do Bash introduzidos como comandos do ENTRYPOINT podem executar a lógica de inicialização condicional, aguardando serviços dependentes (como bancos de dados), lidando com tarefas de configuração e muito mais, mantendo a sintaxe limpa do Dockerfile.

Exemplos e padrões do mundo real

Os aplicativos práticos do ENTRYPOINT podem ilustrar usos típicos e realistas. Vamos dar uma olhada em alguns deles.

Contêineres de comando único 

Para a configuração de um aplicativo Flask:

FROM python:3.11-alpine
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
ENTRYPOINT ["python", "app.py"]
CMD ["--port", "8080"]

No Dockerfile acima:

• ENTRYPOINT ["python", "app.py"]  define o executável padrão. Isso é o que é executado quando o contêiner é iniciado.
• CMD ["--port", "8080"]  fornece argumentos padrão (--port 8080) para o comando ENTRYPOINT.

O comando padrão completo executado será:

python app.py --port 8080

 Se você substituir o CMD ao executar o contêiner (por exemplo, docker run myimage --port 9090), ele substituirá o --port 8080.

Script como ENTRYPOINT 

Isso é usado para configurar a lógica condicional de suporte: 

entrypoint.sh:

#!/bin/sh
until nc -z db_host 5432; do
  echo "Waiting for database to become available."
  sleep 2
done
exec python app.py "$@"

Dockerfile:

FROM python:3.11-alpine
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
COPY entrypoint.sh .
RUN chmod +x entrypoint.sh
ENTRYPOINT ["./entrypoint.sh"]
CMD ["--port", "8080"]

Nos arquivos acima:

• entrypoint.sh é usado para aguardar a conexão com o banco de dados.
• exec python app.py "$@"  substitui o processo atual do shell pelo Python app.py, passando quaisquer argumentos adicionais. "$@" vem dos parâmetros CMD ou docker run.
• COPY entrypoint.sh  copia o script entrypoint.sh para o diretório /app do contêiner.
• ENTRYPOINT ["./entrypoint.sh"] define entrypoint.sh como o script de inicialização padrão quando o contêiner é executado.
• CMD ["--port", "8080"] fornece argumentos padrão que serão passados para o script entrypoint.sh e, eventualmente, para python app.py. O comando final executado será semelhante a: python app.py --port 8080. 

Manuseio de sinais e PID 1

ENTRYPOINTafeta significativamente a capacidade do Docker de lidar com sinais devido à importância do PID 1. Vamos explorar isso com mais detalhes: 

Formulário de execução e PID 1

O formulário Exec executa comandos diretamente como o processo PID 1 do Docker, o que melhora a confiabilidade do encaminhamento de sinal e o comportamento adequado de parada ou reinício.

Limitações do formulário de casca

O formulário de shell adiciona um processo de shell intermediário. Isso evita que os sinais de encerramento cheguem aos processos de aplicativos, criando um risco de contêineres travados ou que não respondem.

Depuração do comportamento do ENTRYPOINT

A solução de problemas das configurações do entrypoint é mais fácil com o uso de certas técnicas e truques. Vamos descobri-los a seguir. 

Usando --entrypoint para depuração

As substituições temporárias permitem rapidamente shells de depuração interativos nos seus contêineres sem reconstrução da imagem. Isso permite que você teste coisas diferentes em seu aplicativo sem reconstruir a imagem. 

Visualização dos registros do ENTRYPOINT

A verificação dos registros de saída com docker logs simplifica o rastreamento do histórico de execução e a localização de problemas de configuração de forma clara e rápida.

Evite modificar o Dockerfile para testes temporários

Substituições de tempo de execução de fácil depuração ENTRYPOINT permitem que você isole e corrija problemas sem modificar e reconstruir repetidamente imagens de contêineres.

Técnicas de otimização e práticas recomendadas

Abaixo estão várias otimizações recomendadas para melhorar a confiabilidade e a capacidade de manutenção do site ENTRYPOINT.

Usar o formulário exec para tratamento de sinais

Prefira sempre o formato exec para obter sinais de terminação adequados e melhor confiabilidade e gerenciamento geral do contêiner.

Combinação eficaz de ENTRYPOINT e CMD

Separe seu executável (ENTRYPOINT) dos argumentos padrão do tempo de execução (CMD) e utilize as substituições do tempo de execução para obter o máximo de flexibilidade e facilidade de gerenciamento.

Minimizar a complexidade no ENTRYPOINT

Mantenha o site ENTRYPOINT simples, delegando condições ou lógica de inicialização complexas em scripts separados para garantir o gerenciamento adequado da complexidade e aumentar a clareza.

Casos de uso e padrões avançados

Vamos explorar alguns casos de uso e padrões avançados do ENTRYPOINT.

Construções em vários estágios com o ENTRYPOINT

ENTRYPOINT nos estágios finais do Docker reforça a execução confiável, fornecendo compilações mais limpas, adaptadas especificamente para tarefas de produção em fluxos de trabalho de CI/CD.

Scripts dinâmicos de ENTRYPOINT

ENTRYPOINT Os scripts podem ajustar dinamicamente sua lógica de inicialização de acordo com as variáveis de ambiente fornecidas ou com os argumentos de tempo de execução, adaptando-se perfeitamente a diferentes contextos de aplicativos.

ENTRYPOINT para pipelines de CI/CD

O uso do site ENTRYPOINT melhora a consistência entre os ambientes de teste e produção, garantindo comportamentos previsíveis de tempo de execução e repetibilidade. Por exemplo, você pode configurar o site ENTRYPOINT para um script que executa testes automaticamente. 

Outros aplicativos incluem: 

• Um ENTRYPOINT que aguarda o banco de dados, executa migrações e, por fim, inicia o app.
• Um site ENTRYPOINT que compila ativos, imprime código ou valida configurações automaticamente.
• ENTRYPOINT Os scripts podem detectar ambientes (desenvolvimento, preparação, produção) e ajustar as configurações de acordo com a inicialização do contêiner. 

Aqui está um exemplo de uma imagem do Docker que executa testes automaticamente:

FROM python:3.11
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
ENTRYPOINT ["pytest"]

O site .gitlab-ci.yml teria a seguinte aparência:

build-test:
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t myapp-test .
    - docker run myapp-test  # <-- No need to specify 'pytest', ENTRYPOINT does it

Quando o docker run é executado, ele aciona automaticamente o pytest dentro do contêiner. Isso garantirá que todos os testes sejam encontrados e executados imediatamente. 

Há várias vantagens em usar o ENTRYPOINT em CI/CD:

• Todos os contêineres iniciam e se comportam da mesma maneira. 
• Simplifica os scripts de CI/CD porque você não precisa passar comandos completos todas as vezes. 
• Automatiza as verificações de pré-inicialização, execuções de testes e migrações, reduzindo o erro humano. 

Armadilhas comuns e solução de problemas

ENTRYPOINT tem algumas armadilhas que vale a pena evitar em seus fluxos de trabalho.

Uso indevido do formulário shell

O formato de concha atrapalha os sinais e os gerenciadores de contêineres; prefira sempre o formato exec para o manuseio adequado de sinais, saídas de contêineres e paradas limpas.

ENTRYPOINT excessivamente complicado

Os scripts complexos que não são claros ou confiáveis se deterioram ainda mais durante a depuração ou a manutenção contínua. As configurações simples do ENTRYPOINT simplificam significativamente a solução de problemas.

Conclusão

Compreender e implementar efetivamente o Docker ENTRYPOINT permite que você crie contêineres Docker previsíveis, confiáveis e de fácil manutenção para seus aplicativos. Usado corretamente, o ENTRYPOINT cria consistência sem sacrificar a flexibilidade devido ao poderoso sistema de substituição do Docker. Experimentar cuidadosamente os padrões do ENTRYPOINT, aderindo às práticas recomendadas descritas acima, simplifica significativamente o uso do Docker e leva a ciclos de implantação e gerenciamento mais suaves na produção.

Confira nossos cursos do Docker para explorar mais tópicos do Docker, como:

• Introdução ao Docker
• Conceitos de virtualização e de contêineres 
• Containerização e virtualização com Docker e Kubernetes
• Docker intermediário