Skip to content
DevOps AI ToolKit
Newsletter
All prompts
Docker with AI Difficulty: Advanced ClaudeChatGPTCursor

Graceful Shutdown & Signal Handling Design Prompt

Design correct PID 1 signal handling so containers catch SIGTERM, drain in-flight work, and exit cleanly within the stop grace period instead of being SIGKILLed.

Target user
DevOps and platform engineers hardening container lifecycle behavior
Difficulty
Advanced
Tools
Claude, ChatGPT, Cursor

The prompt

You are a senior container reliability engineer who specializes in the process lifecycle inside Docker containers.

I will provide some or all of:
- The Dockerfile (especially the `ENTRYPOINT`/`CMD` lines and any shell wrapper or entrypoint script)
- How the process is started (exec form vs shell form, `sh -c`, a supervisor, or a wrapper script)
- The application language/runtime and how it currently handles signals (if at all)
- The `docker run`/Compose config, including any `stop_grace_period`, `stop_signal`, or `--init` usage
- What "in-flight work" means for this service (open HTTP requests, queue messages being processed, DB transactions, buffered writes)

Your job:

1. **Diagnose the PID 1 problem** — determine what is actually running as PID 1. Explain that `CMD ["sh", "-c", "node app.js"]` (shell form) makes the shell PID 1, which does not forward `SIGTERM` to the child and does not reap zombies, so `docker stop` waits the full grace period and then `SIGKILL`s the app mid-request. Show whether the current setup has this defect.
2. **Fix signal delivery** — rewrite `ENTRYPOINT`/`CMD` to exec form so the real process becomes PID 1 and receives `SIGTERM` directly, or introduce a minimal init (`tini`, or `docker run --init`) when the process legitimately spawns children that must be reaped. Explain the trade-off between `exec` in the entrypoint script vs a dedicated init.
3. **Design the drain sequence** — specify, in order, what the app must do on `SIGTERM`: stop accepting new work (close the listener / stop pulling from the queue), finish in-flight work up to a deadline, flush buffers, close DB and pool connections, then exit 0. Provide language-appropriate handler pseudocode.
4. **Size the grace period** — recommend a `stop_grace_period` / `--stop-timeout` that is longer than the worst-case drain but bounded, and explain the relationship between that timeout and the app's internal drain deadline (internal deadline must be shorter so the app exits before Docker escalates to `SIGKILL`).
5. **Handle the load-balancer race** — note that in-flight and newly arriving connections during shutdown need a readiness/health flip so the router stops sending traffic before the app stops accepting it; describe the ordering.
6. **Verify** — give exact commands to prove correct behavior: send `docker stop` and observe a clean exit code 0 within the grace period, inspect logs for the drain sequence, and confirm no requests are dropped.

Output as: (a) PID 1 diagnosis, (b) corrected Dockerfile ENTRYPOINT/CMD and init decision with rationale, (c) ordered drain sequence with signal-handler pseudocode, (d) recommended stop_grace_period and internal deadline values, (e) load-balancer drain ordering, (f) verification commands.

Prefer exec-form ENTRYPOINT and explicit signal handling over relying on Docker's SIGKILL fallback — state the exit-code and dropped-work consequences of getting this wrong.

Run this prompt with AI

Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.

Related prompts

More Docker with AI prompts & error guides

Browse every Docker with AI prompt and troubleshooting guide in one place.

Free download · 368-page PDF

Reading prompts? Get all 500 in one free PDF

500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.

  • 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
  • Instant PDF download — yours free, forever
  • Plus one practical AI-workflow email a week (no spam)

Single opt-in · unsubscribe anytime · no spam.