How do you make a containerized process wait at startup until your debugger attaches?

### Why suspend exists at all Outside a container you can start a process under a debugger and it is stopped from instruction one. Attaching to something already running is different: whatever happened before you connected is gone. That is fine for a request handler you can trigger again, and useless for a bug in startup - a configuration value read once, a database migration, a cache warmed at boot. Containers make the gap worse. The process starts the moment the container starts, and by the time you notice the container is up, click attach in your editor and the connection completes, several seconds have passed. For a short-lived container - a job that indexes documents and exits - the process may be gone entirely. The answer is to let the debug agent block the program until a client connects. ### The spelling per runtime **JVM.** `-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005`. Two independent switches are often confused. `server=y` means the JVM *listens* and the debugger dials in (the normal container arrangement, because the container has the published port); `server=n` means the JVM dials out to a listening debugger. `suspend=y` is orthogonal: it decides whether the JVM waits before running your code. The startup line printed by the JVM - `Listening for transport dt_socket at address: 5005` - is your confirmation that the agent is up and waiting. **Python.** `python -m debugpy --listen 0.0.0.0:5678 --wait-for-client -m indexer`. Without `--wait-for-client` the module runs immediately and an attach later may miss everything interesting. **Go.** `dlv --headless --listen=:2345 --api-version=2 exec /app/indexer` starts the program under the debugger and holds it, so a client that connects can set breakpoints before anything runs and then continue. ### Getting the flags in without rebuilding The worst version of this workflow is editing the Dockerfile, rebuilding and hoping. Two better routes: Override the command for one run. The image's ENTRYPOINT/CMD is a default; `docker run` can replace the arguments for a single container, so the debug variant of the command is a shell-history line rather than a commit. Use an environment variable the runtime already reads. The JVM reads `JAVA_TOOL_OPTIONS` and prepends whatever it finds to the command line, printing `Picked up JAVA_TOOL_OPTIONS:` as it does. So `docker run -e JAVA_TOOL_OPTIONS='-agentlib:jdwp=...'` turns on debugging in an image built with no knowledge of debugging at all - the single most useful trick in this area, and the reason a Java service rarely needs a separate debug image. When the flags genuinely must live in the image - a Go binary that needs the delve server present, for instance - put them in a dedicated build stage and build that stage explicitly, so the artefact that ships is a different image from the one you debug. ### The side effects a suspended container produces A process stopped before `main` has not opened its service port and is not answering anything. Expect these consequences: - **HEALTHCHECK.** If the image declares one, it will fail while the process is suspended, and after the configured retries the container's health state becomes `unhealthy`. That is correct behaviour, but it can be alarming, and any automation that acts on health state will act. - **Restart policy.** A container that exits and is restarted under `--restart` will suspend again on every start; if you are not watching, you get a container that appears hung instead of one that appears crash-looping. - **Dependent services.** Anything waiting for this process to answer will wait as long as you do. - **Timeouts inside the app.** Once you are stopped on a breakpoint, wall-clock time keeps running. Connection pools, leases and heartbeats can expire while you read a variable, so the state you resume into is not always the state you paused. ### Never ship it `suspend=y` in a production image is a service that does not start: the container comes up, the agent waits for a debugger that will never connect, and every health check fails. It is the single most damaging way to get this wrong, and it is why the flags belong on the run command or in a debug-only build target rather than in the default command of the image you push. The same discipline covers the security problem - an image that never carries the agent by default cannot accidentally expose an unauthenticated debug port in production.