> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minimus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mount a Debugger

> How to debug a Minimus container by mounting debug tools

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.

<Steps>
  <Step title="Prepare the debugger container">
    We can use the [Minimus BusyBox](https://images.minimus.io/gallery/images/busybox/lines/latest) image as our debugger container. We will first create the container (without running it), extract its filesystem, and place it in a local directory.

    ```bash theme={null}
    # 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
  </Step>

  <Step title="Start the target container and mount the debugger image">
    ```bash theme={null}
    docker run -d --rm \
      -v $(pwd)/debugger:/.debugger \
      --name my-image {your production Minimus image}
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    docker exec -it my-image /.debugger/bin/sh
    ```
  </Step>

  <Step title="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.

    <CodeGroup>
      ```bash Append Debugger theme={null}
      export PATH=${PATH}:/.debugger/bin  
      # The target container takes precedence
      ```

      ```bash Prepend Debugger theme={null}
      export PATH=/.debugger/bin:${PATH}
      # The debugger container takes precedence 
      ```
    </CodeGroup>

    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.

    <Warning>
      Note that this change only affects the current shell session.
    </Warning>
  </Step>

  <Step title="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:

    ```bash theme={null}
    # 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.
  </Step>
</Steps>

<Info>
  This article was inspired by [Ivan Velichko's blog](https://iximiuz.com/en/posts/docker-debug-slim-containers/).
</Info>