Most production Minimus container images do not include a shell. While we recommend use of the dev tagged Minimus images for troubleshooting whenever possible, sometimes it may be necessary to mount a debugger on a production container.
1

Prepare the debugger container

We can use the Minimus BusyBox image as our debugger container. We will first create the container (without running it), extract its filesystem, and place it in a local directory.
# Authenticate to the Minimus registry
docker login reg.mini.dev -u minimus
# Password: {your Minimus token}

# Create a container from the Minimus BusyBox image
docker create --name debugger \
reg.mini.dev/busybox:latest-dev

# Create a local directory to store the filesystem
mkdir debugger

# Export the root filesystem and save it to the local directory
docker export debugger | sudo tar -xC debugger
  • docker export saves the root filesystem of the container to a tar archive
  • | (the pipe) passes the output directly into the next command to avoid creating an intermediate tar file
  • tar -xC debugger extracts the archive files and saves them to the local directory
2

Start the target container and mount the debugger image

docker run -d --rm \
  -v $(pwd)/debugger:/.debugger \
  --name my-image {your production Minimus image}
3

Start the debugging session

Exec into the target container to start a debug session. This is possible because the debugger container and target container (my-image) share namespaces and cgroups.
docker exec -it my-image /.debugger/bin/sh
3

Update the system's executable search path

Now that we’ve mounted the BusyBox toolkit, we need to add the directory /.debugger/bin to the current shell’s path environment variable to make the tools executable from anywhere. This works because the BusyBox toolkit in the mounted volume is statically linked.
export PATH=${PATH}:/.debugger/bin  
# The target container takes precedence
You can either prepend or append the debug tools. In the case of a name collision:
  • If the debugger was appended, the binaries from the target container will take precedence.
  • If the debugger was prepended, the binaries from the debugger container will take precedence.
Note that this change only affects the current shell session.
5

Ready to debug!

That’s it. You are now ready to use the BusyBox toolkit as if it were natively part of the target container.For example, you can explore the filesystem of the target container and list the running processes and network interfaces:
# List files and directories in long format
ls -l

# List all running processes on the system in full detail
ps -ef

# List IP addresses for all network interfaces
ip addr
The output should show you the information for your target Minimus container as if you were running the command directly inside it.
This article was inspired by Ivan Velichko’s blog.