{"id":16945352,"url":"https://github.com/felipecruz91/debug-ctr","last_synced_at":"2025-03-22T12:33:13.103Z","repository":{"id":61916918,"uuid":"555941688","full_name":"felipecruz91/debug-ctr","owner":"felipecruz91","description":"Commandline tool for interactive container troubleshooting.","archived":false,"fork":false,"pushed_at":"2023-01-27T10:01:13.000Z","size":23,"stargazers_count":52,"open_issues_count":1,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-18T11:38:23.552Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/felipecruz91.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-10-22T17:44:18.000Z","updated_at":"2025-01-02T16:33:35.000Z","dependencies_parsed_at":"2023-02-15T07:40:38.517Z","dependency_job_id":null,"html_url":"https://github.com/felipecruz91/debug-ctr","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipecruz91%2Fdebug-ctr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipecruz91%2Fdebug-ctr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipecruz91%2Fdebug-ctr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipecruz91%2Fdebug-ctr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/felipecruz91","download_url":"https://codeload.github.com/felipecruz91/debug-ctr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244959445,"owners_count":20538625,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T21:22:08.795Z","updated_at":"2025-03-22T12:33:12.760Z","avatar_url":"https://github.com/felipecruz91.png","language":"Go","readme":"# debug-ctr\n\nA commandline tool for interactive troubleshooting when a container has crashed or a container image doesn't include debugging utilities, such as distroless images. Heavily inspired by `kubectl debug`, but for containers instead of Pods.\n\n## Option 1: Debugging adding a mount\n\nThis approach uses [justincormack/addmount](https://github.com/justincormack/addmount) to mount the tools from a running container (e.g. `busybox`) into a target container **without** having to restart it.\nThe benefit of this approach is that you wouldn't lose the running state of the container and the tools are available in the target container.\n\nFor example, you can run the following container from a distroless image that doesn't have a shell:\n\n```shell\ndocker run -d --rm \\\n  --name my-distroless gcr.io/distroless/nodejs \\\n  -e 'setTimeout(() =\u003e console.log(\"Done\"), 99999999)'\n```\n\nIf you try to access the container, it'll fail because it doesn't contain a shell:\n\n```shell\ndocker exec -it my-distroless /bin/sh\nOCI runtime exec failed: exec failed: unable to start container process: exec: \"/bin/sh\": stat /bin/sh: no such file or directory: unknown\n```\n\nYou can bring the tools from `busybox:1.28` that are available in `/bin` into the target container (**without** having to restart it) by simply running:\n\n```shell\ndebug-ctr debug --image=busybox:1.28 --target=my-distroless\n\n...\n2022/10/25 09:32:40 -------------------------------\n2022/10/25 09:32:40 Debug your container:\n2022/10/25 09:32:40 $ docker exec -it my-distroless /bin/sh\n2022/10/25 09:32:40 -------------------------------\n```\n\n## Option 2: Debugging using a \"copy\" of the container\n\nSometimes a container configuration options make it difficult to troubleshoot in certain situations. For example, you can't run `docker exec` to troubleshoot your container if your container image does not include a shell or if your application crashes on startup. In these situations you can use `debug-ctr debug` to create a \"copy\" of the container with configuration values changed to aid debugging.\n\n### How does it work?\n\n`debug-ctr debug` uses the `--copy-to` flag to run a new container (a \"copy\" a.k.a the debugger container) that can be useful when your application is running but not behaving as you expect, and you'd like to add additional troubleshooting utilities to the container. This new container is simply a \"copy\" of the container you want to debug which now includes the utilities tools that you need to debug it.\n\nThe tools are first downloaded into a Docker volume from the image you specify with the `--image` flag from the `/bin` directory. When the debugger container is created, the volume is mounted at `/.debugger` and thus the tools in `/bin` from the image are available in the debugger container filesystem (e.g. `ls` will be available at `/.debugger/ls`) and added to the `PATH` automatically for you.\n\nYou can bring the `sh` tool from `busybox:1.28` and simply run the following command to **create a new debugger container** and use the `docker exec` command suggested in the output to access it:\n\n```shell\ndebug-ctr debug --image=busybox:1.28 --target=my-distroless --copy-to=my-distroless-copy\n\n...\n2022/10/22 20:09:26 Starting debug container my-distroless-copy\n2022/10/22 20:09:26 -------------------------------\n2022/10/22 20:09:26 Debug your container:\n2022/10/22 20:09:26 $ docker exec -it my-distroless-copy /.debugger/sh -c \"PATH=\\$PATH:/.debugger /.debugger/sh\"\n2022/10/22 20:09:26 -------------------------------\n```\n\nNote that with this approach the `docker exec` command from the output is used to **exec into the debugger container, not into the original one**.\n\n### Changing its entrypoint and/or command\n\nSometimes it's useful to change the entrypoint and/or command for a container, for example to add a debugging flag or because the application is crashing.\n\nTo simulate a crashing application, use docker run to create a container that immediately exits:\n\n```shell\ndocker run --name crashing-container busybox:1.28 /bin/sh -c \"false\"\n```\n\nYou can use `debug-ctr debug` with `--entrypoint` and/or `--cmd` to create a copy of this container with the command changed to an interactive shell:\n\n```shell\ndebug-ctr debug --image=docker.io/alpine:latest --target=crashing-container --copy-to=crashing-container-copy --entrypoint=\"/.debugger/sleep\" --cmd=\"365d\"\n```\n\nNow you have an interactive shell that you can use to perform tasks like checking filesystem paths or running a container command manually.\n\n## Acknowledgements\n\n- https://iximiuz.com/en/posts/docker-debug-slim-containers/\n","funding_links":[],"categories":["Containers"],"sub_categories":["Shell into containers"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelipecruz91%2Fdebug-ctr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffelipecruz91%2Fdebug-ctr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelipecruz91%2Fdebug-ctr/lists"}