Introduction

docker run -d only starts the container in detached mode. It does not guarantee that the container will stay alive. A container keeps running only while its main process is still running, so if that process exits, the container stops immediately even though it was started with -d.

Detached Mode Does Not Mean Persistent Mode

A container is tied to its PID 1 process. Detached mode just means Docker does not attach your terminal to that process.

For example:

docker run -d alpine echo hello

This starts the container, runs echo hello, prints once, and exits. The container stops because echo finished.

The same rule applies to every image. If the command completes, the container stops.

Check What Command the Container Is Running

A good first step is to inspect the image or container command.

docker ps -a
docker logs <container_id>
docker inspect <container_id>

Very often the logs show the whole story. If the application printed one line and exited cleanly, Docker is behaving correctly.

A typical long-running container needs a foreground process such as:

• a web server
• a database server
• a queue worker
• a shell loop for debugging only

Use a Real Foreground Service

A correct container usually runs the main service directly in the foreground.

Example Dockerfile:

FROM nginx:alpine
CMD ["nginx", "-g", "daemon off;"]

daemon off; is important because NGINX would otherwise daemonize itself and the container would lose its foreground process.

This pattern is common across many server images: run the main process in the foreground so PID 1 stays alive.

For Debugging, Keep It Alive Intentionally

If you only want the container to stay up for debugging, use a long-running command explicitly.

docker run -d alpine sh -c "while true; do sleep 3600; done"

This is useful for interactive inspection, but it is not how production containers should normally be designed. In real images, the foreground process should be the actual application.

Misconfigured Entry Points Are Common

Another common reason containers exit immediately is a bad CMD or ENTRYPOINT combination. For example:

• the entrypoint script finishes and exits
• the script launches the real service in the background and then exits
• the script fails because of a missing file or permission problem

If you use a shell script entrypoint, make sure it ends with the real process in the foreground, often via exec.

#!/bin/sh
exec python app.py

Without exec, signal handling and lifecycle behavior can also become messy.

Restart Policies Do Not Fix a Broken Main Process

You can add a restart policy:

docker run -d --restart unless-stopped my-image

But this only restarts the container after it exits. It does not solve the underlying issue if the main process is wrong or crashes instantly. Use restart policies for resilience, not as a substitute for a valid container command.

Common Pitfalls

• Assuming -d means Docker will keep the container alive regardless of the command is the core misunderstanding.
• Running a command that exits immediately, such as echo or a short script, causes the container to stop normally.
• Starting the real service in the background inside an entrypoint script makes PID 1 exit even though the service seems to have started.
• Ignoring docker logs wastes time because the reason for exit is often visible immediately there.
• Using an infinite sleep loop in production hides lifecycle problems instead of fixing the container design.

Summary

• A container stays alive only while its main foreground process is running.
• 'docker run -d detaches the terminal; it does not make a short-lived command persistent.'
• Check the container command, logs, and entrypoint behavior first.
• Run the actual service in the foreground, not in the background.
• Use restart policies only after the container's main process behavior is correct.