CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

docker-entrypoint-pattern

Padrão para criar entrypoint.sh com múltiplos comandos para containers Docker, permitindo execução flexível de diferentes operações.

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/infrastructure/docker-entrypoint/SKILL.md
SKILL.md
Quality
Evals
Security

Docker Entrypoint Pattern

Padrão para criar entrypoint.sh com múltiplos comandos, permitindo execução flexível de diferentes operações em containers Docker.


Quando Usar

Aplicar esta skill quando:

  • Criando ou modificando Dockerfiles
  • Precisando de múltiplos comandos no container (dev, test, prod, migrate, etc.)
  • Querendo flexibilidade para executar diferentes operações sem modificar Dockerfile
  • Precisando de inicialização antes de iniciar a aplicação (migrations, health checks, etc.)

Por Que Usar Entrypoint.sh?

Vantagens

  1. Flexibilidade: Um único Dockerfile pode executar múltiplos comandos
  2. Inicialização: Executar tarefas antes de iniciar a aplicação (migrations, seed, health checks)
  3. Reutilização: Mesmo container para dev, test, prod
  4. Sinais Unix: exec "$@" garante que o processo principal receba SIGTERM corretamente
  5. Manutenibilidade: Lógica de inicialização centralizada em um script

Padrão Docker

# Copiar entrypoint
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

# Usar como entrypoint
ENTRYPOINT ["/entrypoint.sh"]
CMD ["runserver"]  # Comando padrão

Uso:

# Executar comando padrão
docker run myapp

# Executar comando específico
docker run myapp test
docker run myapp migrate
docker run myapp dev

Estrutura Padrão do Entrypoint

Template Base

#!/usr/bin/env bash

# Exit immediately if a command exits with a non-zero status
# Treat unset variables as errors
# Fail on pipeline errors
set -euo pipefail

# Function to display CLI help
cli_help() {
  local cli_name=${0##*/}
  echo "
$cli_name
[Project Name] - Entrypoint CLI
Usage: $cli_name [command]

Commands:
  dev           Start development server
  prod          Start production server
  test          Run tests with coverage
  migrate       Apply database migrations
  health        Check service health
  *             Display this help message

Environment Variables:
  PORT          Server port (default: 8000)
  WORKERS       Number of workers (default: 4)
  LOG_LEVEL     Logging level (default: info)
"
  exit 1
}

# Main command handler
case "${1:-help}" in
  dev)
    # Development server
    ;;
  prod|runserver)
    # Production server
    ;;
  test)
    # Run tests
    ;;
  migrate)
    # Run migrations
    ;;
  health)
    # Health check
    ;;
  *)
    cli_help
    ;;
esac

Regras Obrigatórias

  1. Sempre usar set -euo pipefail:

    • set -e: Para ao primeiro erro
    • set -u: Erro se variável não definida
    • set -o pipefail: Falha se qualquer comando em pipeline falhar
  2. Sempre usar exec "$@" no final:

    • Substitui o processo shell pelo processo principal
    • Garante que sinais Unix (SIGTERM) cheguem ao processo correto
    • Evita problemas com PID 1
  3. Sempre tornar executável:

    RUN chmod +x /entrypoint.sh
  4. Sempre usar formato exec no ENTRYPOINT:

    ENTRYPOINT ["/entrypoint.sh"]  # ✅ Correto
    # NÃO usar: ENTRYPOINT /entrypoint.sh  # ❌ Errado
  5. Sempre validar variáveis críticas:

    if [ -z "${SECRET_KEY:-}" ]; then
      echo "ERROR: SECRET_KEY not set"
      exit 1
    fi

Templates por Stack

Django

Referência: core/templates/entrypoint/django-entrypoint.sh

Comandos típicos:

  • migrate - Aplicar migrations
  • test - Executar testes
  • dev - Django runserver
  • prod - Gunicorn
  • collectstatic - Coletar arquivos estáticos

FastAPI

Referência: core/templates/entrypoint/fastapi-entrypoint.sh

Comandos típicos:

  • migrate - Alembic upgrade head
  • test - Executar testes
  • dev - Uvicorn com reload
  • prod - Uvicorn multi-worker
  • health - Health check

Node.js (Backend)

Referência: core/templates/entrypoint/nodejs-entrypoint.sh

Comandos típicos:

  • test - Executar testes
  • dev - Nodemon ou ts-node-dev
  • prod - Node dist/index.js
  • seed - Executar seed scripts
  • health - Health check

React.js (Frontend)

Referência: core/templates/entrypoint/react-entrypoint.sh

Comandos típicos:

  • dev - Vite/Next.js dev server
  • build - Build de produção
  • prod - Servir build estático (nginx)
  • test - Executar testes

Boas Práticas

1. Aguardar Dependências

wait_for_service() {
  local host=$1
  local port=$2
  local service=$3
  
  echo "⏳ Waiting for $service at $host:$port..."
  until nc -z "$host" "$port"; do
    echo "$service is unavailable - sleeping"
    sleep 2
  done
  echo "✅ $service is ready!"
}

# Aguardar dependências antes de iniciar
wait_for_service db 5432 "PostgreSQL"
wait_for_service redis 6379 "Redis"

2. Validação de Variáveis

# Validar variáveis críticas
REQUIRED_VARS=("DATABASE_URL" "SECRET_KEY")
for var in "${REQUIRED_VARS[@]}"; do
  if [ -z "${!var:-}" ]; then
    echo "ERROR: $var not set"
    exit 1
  fi
done

3. Logging Estruturado

log() {
  echo "[$(date +'%Y-%m-%d %H:%M:%S')] $1"
}

log "Starting application..."
log "Port: ${PORT:-8000}"
log "Environment: ${ENVIRONMENT:-development}"

4. Health Checks

health)
  # Verificar dependências
  check_database || exit 1
  check_redis || exit 1
  echo "✅ All services healthy"
  exit 0
  ;;

5. Condicionais por Ambiente

# Rodar migrations apenas se necessário
if [ "${RUN_MIGRATIONS:-false}" = "true" ]; then
  echo "📦 Running migrations..."
  alembic upgrade head
fi

# Coletar estáticos apenas em produção
if [ "${ENVIRONMENT:-development}" = "production" ]; then
  echo "📁 Collecting static files..."
  python manage.py collectstatic --noinput
fi

Integração com Dockerfile

Padrão Multi-Stage

FROM python:3.11-slim AS base

WORKDIR /app

# Instalar dependências
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copiar código
COPY . .

# Copiar entrypoint
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

# Expor porta
EXPOSE 8000

# Entrypoint e CMD
ENTRYPOINT ["/entrypoint.sh"]
CMD ["prod"]  # Comando padrão

Uso no Docker Compose

services:
  backend:
    build: .
    entrypoint: ["/entrypoint.sh"]
    command: ["dev"]  # Override CMD
    environment:
      - PORT=8000
      - RUN_MIGRATIONS=true

Checklist

  • set -euo pipefail no início
  • Função cli_help() implementada
  • exec "$@" usado no final de cada comando
  • Entrypoint tornando executável no Dockerfile
  • Validação de variáveis críticas
  • Aguardar dependências (se necessário)
  • Logging estruturado
  • Health check implementado
  • Comandos documentados no help
  • Testado em dev e prod

Referências

  • Templates: core/templates/entrypoint/
  • Django Template: core/templates/django/entrypoint.sh
  • DevOps Docs: core/docs/programming/devops.md (seção entrypoint)
  • Docker Best Practices: Sempre usar exec "$@" para sinais Unix

Última Atualização: 2026-01-21

Repository

fernandezbaptiste/cursor-multiagent-system

Path

skills/infrastructure/docker-entrypoint/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.