How to Debug an Endlessly Restarting Docker Container

1. Stop the endlessly restarting container:

docker stop <container-name>

Please see the reference for docker stop.

2. Start a Docker container in interactive mode (replace the <image-name> with your image name):

docker run -it --entrypoint /bin/bash <image-name>

Here:

• docker run — Starts a new container from the image <image-name>. See the reference for docker run.
• -it — Runs the container in the interactive mode:
  • -i (or --interactive) — Keeps STDIN (standard input) stream open.
    Normally, when you run a Docker container, the STDIN stream closes immediately unless you’re attached to it. The -i flag prevents this, keeping the input channel open.
  • -t (or --tty) — Allocates a pseudo-TTY (short for “pseudo-terminal“).
    Without -t, running a container interactively (for example, with a shell) would lack proper terminal capabilities. For example, top, vi, etc. might not work correctly.
    (source)
• --entrypoint /bin/bash — Overrides the container’s default entrypoint with the bash shell.

docker run -it --entrypoint /bin/sh <image-name>

3. If your container is based on a Docker Compose file, you can temporarily replace the entrypoint of the container:

services:
  wordpress:
    container_name: wordpress-wpd
    # Temporarily add these 2 lines. Remove or comment them out after debugging:
    entrypoint: [/bin/bash] # this line replaces the entrypoint inside the container
    command: ["-c", "tail -f /dev/null"] # this prevents the container from starting, executing the /bin/bash shell, and then exiting immediately

Here:

• entrypoint: [/bin/bash] — Overrides the container’s default entrypoint with the bash shell.
  If your container does not have bash, you can try [/bin/sh] instead.
• command: ["-c", "tail -f /dev/null"] — Passes parameters to /bin/bash. The container executes:
  /bin/bash -c 'tail -f /dev/null'
  • -c — Means the following string is a command to execute. See man bash.
  • tail -f /dev/null — A command that will run endlessly and will prevent the container from exiting immediately:
    • tail — Displays the end of a file. See man tail.
    • -f (or --follow) — Makes tail continuously wait for updates instead of terminating after reaching the file’s end.
    • /dev/null — A special file in Unix-like systems. Anything written to it is discarded, and it returns EOF when read from. (source)

tail -f /dev/null does not consume any resources, because it “follows” the file /dev/null that will never have any new data.

Now, you can run the container:

docker compose up -d

Then you can enter the Docker container terminal by running the command:

docker exec -it wordpress-wpd bash

Here:

• docker exec — Starts a new container from the image <image-name>. See the reference for docker run.
• -it — Explained right above.
• wordpress-wpd — The container name. Replace it with your container name.
• bash — The bash shell (or you can use sh instead).

4. Now you can run commands inside the Docker container, explore volumes, etc.

For example, if the script entrypoint.sh serves as your entrypoint, you can run it manually inside the container to find any errors:

./entrypoint.sh

Of course, any testing or debugging needs to be done in the local development environment, not on production. I prefer to do it on a VirtualBox virtual machine, where I install exactly the same operating system as on a production server.

Conclusion

Thank you very much for reading to the end!

I’d be very grateful for any comments.