Docker
Proceso principal, formas exec y shell, PID 1 y graceful shutdown.
ENTRYPOINT y no son dos formas redundantes de escribir “qué ejecutar”. Juntas definen cómo la imagen propone su proceso principal y qué parte de ese comando puede reemplazar el usuario al crear un contenedor.
CMDENTRYPOINT ["node"]
CMD ["server.js"]La configuración anterior produce por defecto:
node server.jsLa decisión importa porque el proceso resultante se convierte normalmente en PID 1 dentro del contenedor. Debe recibir señales, terminar de forma ordenada, propagar errores y administrar procesos hijos.
Una imagen puede construir y arrancar correctamente durante pruebas simples, pero fallar durante un deployment si su shell, script o proceso principal no maneja estas responsabilidades.
Una imagen reutilizable necesita responder dos preguntas:
Una herramienta CLI puede querer un ejecutable fijo con subcomandos variables:
image de terraform
ENTRYPOINT → terraform
CMD → --helpUna aplicación web puede querer un command completamente reemplazable para ejecutar servidor, migraciones o tests:
image de API
CMD → node dist/server.jsDocker necesita combinar los defaults de la imagen con argumentos y overrides de runtime de forma predecible.
Piensa en el command final como una composición:
ENTRYPOINT de la image
+ CMD de la image
+ argumentos de docker run
+ --entrypoint opcional
→ argv del proceso principalLa regla práctica más importante:
docker run reemplazan normalmente CMD;--entrypoint reemplaza ENTRYPOINT;CMD define un command predeterminado o argumentos predeterminados.
CMD ["node", "server.js"]Ejecutar:
docker run my-apiproduce:
node server.jsPero:
docker run my-api node migrate.jsreemplaza el CMD con node migrate.js.
Este diseño es flexible para imágenes de aplicación que pueden ejecutar diferentes procesos relacionados.
ENTRYPOINT ["node"]
CMD ["server.js"]Ahora:
docker run my-api worker.jsproduce:
node worker.jsEl ejecutable permanece estable; cambian los argumentos.
Si un Dockerfile contiene varios CMD, únicamente el último queda como default de la etapa. No se concatenan.
ENTRYPOINT define el ejecutable o prefijo estable de la imagen.
ENTRYPOINT ["/usr/local/bin/my-cli"]
CMD ["--help"]Esto es apropiado cuando la imagen representa claramente una herramienta.
docker run my-cli versionproduce:
/usr/local/bin/my-cli versionUn ENTRYPOINT rígido dificulta ejecutar herramientas de diagnóstico o comandos alternativos:
docker run my-cli shno abre necesariamente un shell; se convierte en:
/usr/local/bin/my-cli shPara reemplazarlo:
docker run --entrypoint sh my-cliEn imágenes de servicios, usar solo CMD puede ser más flexible si no existe un ejecutable que deba permanecer fijo.
CMD ["node", "server.js"]
ENTRYPOINT ["/entrypoint.sh"]La forma JSON define argumentos directamente, sin insertar un shell implícito.
Beneficios:
La forma exec no expande variables automáticamente:
ENV APP_FILE=server.js
CMD ["node", "$APP_FILE"]Node recibe literalmente $APP_FILE. Para expansión, la aplicación debe leer la variable, el command debe usar un shell conscientemente o un script debe construir los argumentos.
CMD node server.jsDocker utiliza el shell predeterminado de la plataforma, conceptualmente:
/bin/sh -c "node server.js"La shell form permite:
&& y ||;Pero para el proceso principal introduce una capa:
PID 1 → /bin/sh -c
└── node server.jsEl shell puede no reenviar señales de la forma esperada y Node deja de ser PID 1. Durante docker stop, SIGTERM puede llegar al shell mientras la aplicación continúa hasta que Docker fuerza SIGKILL.
Para runtime, prefiere exec form salvo que el shell sea una parte intencional y correctamente administrada del diseño.
PID 1 tiene comportamiento especial en Linux.
Algunas señales cuya acción predeterminada terminaría un proceso normal pueden tener tratamiento diferente para PID 1 si no existe un handler. La aplicación debe registrar handlers cuando necesita graceful shutdown.
Cuando un proceso hijo termina, su padre debe recolectar su estado mediante wait. Si el padre desaparece, procesos huérfanos pueden ser adoptados por PID 1. Una aplicación que crea muchos hijos y no los recolecta puede acumular zombies.
Docker considera la vida del contenedor ligada a PID 1. Si termina, el contenedor termina, aunque queden procesos mal administrados.
Un script puede preparar configuración antes de ejecutar la aplicación:
#!/bin/sh
set -eu
if [ "${RUN_MIGRATIONS:-false}" = "true" ]; then
node dist/migrate.js
fi
exec "$@"Dockerfile:
COPY docker-entrypoint.sh /usr/local/bin/
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["node", "dist/server.js"]exec "$@" reemplaza el shell."$@"sin exec deja el shell como PID 1 y la aplicación como hijo.
Otro error:
node dist/server.js &
waitpuede ser válido solo si el script implementa forwarding de señales, waits y manejo de múltiples procesos correctamente. Para una aplicación simple, exec es más seguro.
| Dockerfile | `docker run image` | `docker run image arg` |
|---|---|---|
| `CMD ["a", "b"]` | `a b` | `arg` |
| `ENTRYPOINT ["a"]` • `CMD ["b"]` | `a b` | `a arg` |
| `ENTRYPOINT ["a"]` | `a` | `a arg` |
Esta tabla representa el modelo común con exec form. La shell form añade reglas y resultados menos intuitivos.
docker run --rm --entrypoint sh my-apiReemplaza el ENTRYPOINT. Es útil para:
No es una corrección permanente. Si producción siempre necesita sobrescribirlo, el diseño de la imagen probablemente no representa bien su responsabilidad.
--entrypoint recibe el ejecutable; los argumentos adicionales se escriben después de la imagen:
docker run --rm --entrypoint node my-api --versionEs la señal habitual de parada ordenada. La aplicación debe:
No puede capturarse. Docker la utiliza después del timeout si el proceso no termina.
Suele venir de una interrupción interactiva, como Ctrl+C, según cómo esté attached el contenedor.
Algunas aplicaciones la utilizan para recargar configuración. No asumas soporte sin documentación.
Una imagen puede declarar la señal que Docker enviará por defecto al detener:
STOPSIGNAL SIGTERMPuede ser útil si la aplicación espera otra señal soportada. Cambiarla para evitar implementar shutdown correcto suele ser una mala solución.
La plataforma y el runtime pueden tener diferencias, especialmente en contenedores Windows.
Una parada segura no significa “capturar SIGTERM y llamar process.exit(0) inmediatamente”.
Para una API:
SIGTERM
→ marcar instancia no ready
→ dejar de aceptar conexiones nuevas
→ esperar requests activos
→ detener workers
→ cerrar pools y telemetry
→ salir antes del timeoutEjemplo Node.js simplificado:
import http from 'node:http';
const sockets = new Set();
const server = http.createServer((request, response) => {
response.end('ok');
});
server.on('connection', (socket) => {
sockets.add(socket);
socket.on('close', () => sockets.delete(socket));
});
server.listen(3000, '0.0.0.0');
let shuttingDown = false;
const shutdown = (signal) => {
if (shuttingDown) return;
shuttingDown = true;
console.log({ signal }, 'shutdown started');
server.close((error) => {
if (error) {
console.error(error);
process.exitCode = 1;
}
});
setTimeout(() => {
for (const socket of sockets) socket.destroy();
}, 20_000).unref();
setTimeout(() => {
console.error('shutdown deadline exceeded');
process.exit(1);
}, 25_000).unref();
};
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));Si la aplicación no administra procesos hijos correctamente:
docker run --init my-apiDocker inserta un init mínimo como PID 1 que reenvía señales y recolecta hijos.
Es útil para:
No reemplaza graceful shutdown de la aplicación. El init puede reenviar SIGTERM, pero la app todavía debe reaccionar.
También pueden utilizarse init systems dentro de la imagen, pero añadir un supervisor completo requiere justificar múltiples procesos y políticas de reinicio.
“Un proceso por contenedor” es una guía, no una ley del kernel. La idea real es mantener una responsabilidad operativa clara.
Puede ser válido que una aplicación cree hijos o que un container especializado ejecute varios procesos estrechamente acoplados. Sin embargo, debes resolver:
Ejecutar API, database y cron en un solo contenedor suele mezclar lifecycle y estado que deberían administrarse por separado.
FROM alpine:3.22
COPY my-tool /usr/local/bin/my-tool
ENTRYPOINT ["my-tool"]
CMD ["--help"]Uso:
docker run --rm my-tool version
docker run --rm my-tool convert input.jsonLa imagen representa claramente el ejecutable. CMD --help aporta una experiencia útil por defecto.
Para diagnóstico:
docker run --rm --entrypoint sh my-toolCMD ["node", "dist/server.js"]Servidor:
docker run my-apiMigración:
docker run --rm my-api node dist/migrate.jsAquí no se fija ENTRYPOINT porque la imagen contiene varios commands legítimos. El runtime reemplaza CMD de forma directa.
Una alternativa con entrypoint puede funcionar, pero debe evitar convertir todos los argumentos en parámetros obligatorios de Node si necesitas ejecutar shell u otras herramientas.
Compose expresa entrypoint y command por separado.
services:
api:
image: my-api:1.0
command: ["node", "dist/server.js"]En términos generales:
command sobrescribe el default asociado a CMD;entrypoint sobrescribe ENTRYPOINT.La sintaxis corta como string puede introducir diferencias de shell. Para claridad, usa listas cuando necesitas argv explícito y verifica la configuración final con:
docker compose configdocker run --entrypoint sh distroless-imagefalla porque sh no existe. El diagnóstico debe usar logs, debug images, mounts o herramientas externas.
Puede producir errores como no such file or directory aunque el archivo exista, porque el shebang termina en \r. Normaliza LF.
El runtime puede devolver exit code 126. Usa permisos correctos durante build:
COPY --chmod=755 docker-entrypoint.sh /usr/local/bin/#!/bin/bashfallará en una imagen que solo contiene /bin/sh.
Docker espera y luego fuerza SIGKILL. Revisa PID 1, forma exec, handlers y timeout.
No se expande automáticamente. Decide si la app lee la variable o utiliza un script controlado.
Varias réplicas pueden ejecutar migraciones concurrentes. Las migraciones necesitan coordinación, idempotencia y un lifecycle separado cuando el riesgo lo exige.
Consecuencia: señales no llegan correctamente y deployments terminan con SIGKILL.
Corrección: exec form o script que finaliza con exec.
Consecuencia: shell permanece como PID 1.
Corrección: reemplazar el proceso tras la preparación.
Consecuencia: ejecutar migrations, tests o debug requiere overrides extraños.
Corrección: usar solo CMD o diseñar un entrypoint que represente un ejecutable real.
Consecuencia: el script termina o administra mal señales.
Corrección: mantener el proceso en foreground.
Consecuencia: requests y jobs se interrumpen aunque exista handler.
Corrección: implementar draining con deadline.
Consecuencia: el contenedor parece healthy mientras la aplicación real no existe.
Corrección: PID 1 debe representar el workload.
docker image inspect my-api \
--format '{{json .Config.Entrypoint}} {{json .Config.Cmd}}'docker inspect api \
--format '{{json .Path}} {{json .Args}}'docker run --name signal-test my-api
docker stop --time 10 signal-test
docker inspect signal-test --format '{{json .State}}'Revisa logs para confirmar que la aplicación recibió SIGTERM y terminó antes de SIGKILL.
docker run --rm my-api node --version
docker run --rm --entrypoint node my-api --versionExplica por qué cada comando produce un argv distinto.
docker top signal-testConfirma si PID 1 lógico es la app, un shell o un init.
CMD aporta defaults reemplazables.ENTRYPOINT define un ejecutable o prefijo más estable.docker run suelen reemplazar CMD.--entrypoint reemplaza ENTRYPOINT.exec "$@".--init ayuda con hijos, pero no sustituye lógica de shutdown.--init?Cache de build y BuildKit, para comprender cómo el builder calcula reutilización, qué inputs invalidan cada paso y cómo acelerar sin sacrificar corrección.