{"id":18636672,"url":"https://github.com/localstack/localstack-docker-debug","last_synced_at":"2025-04-11T09:31:04.403Z","repository":{"id":185836391,"uuid":"668327456","full_name":"localstack/localstack-docker-debug","owner":"localstack","description":null,"archived":false,"fork":false,"pushed_at":"2024-08-29T17:24:05.000Z","size":300,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":15,"default_branch":"main","last_synced_at":"2024-08-30T12:41:10.965Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/localstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-19T14:41:08.000Z","updated_at":"2024-08-29T17:24:02.000Z","dependencies_parsed_at":"2024-08-29T12:40:10.676Z","dependency_job_id":"f9b217c7-835e-4cf6-bc98-0aa27967085c","html_url":"https://github.com/localstack/localstack-docker-debug","commit_stats":null,"previous_names":["simonrw/localstack-docker-debug","localstack/localstack-docker-debug"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocalstack-docker-debug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocalstack-docker-debug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocalstack-docker-debug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocalstack-docker-debug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/localstack","download_url":"https://codeload.github.com/localstack/localstack-docker-debug/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223464578,"owners_count":17149576,"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-11-07T05:31:06.251Z","updated_at":"2024-11-07T05:32:17.336Z","avatar_url":"https://github.com/localstack.png","language":"Python","readme":"# LocalStack docker debug image\n\nThis repository contains the source code for the LocalStack docker debug application.\n\n\u003e [!TIP]\n\u003e Please see the [Network Troubleshooting Guide](https://docs.localstack.cloud/references/network-troubleshooting) for more up to date guidance.\n\n## Usage\n\nIf you have an issue with your docker networking setup, you can use this docker container to investigate further.\nThe tool has multiple usage modes.\n\n### Diagnose\n\nIn this mode, the tool will replicate attempting to connect from your application container to your target container.\n\n\n```mermaid\nflowchart LR;\n    ls[LocalStack]\n    app[Application Container]\n\n    app --\u003e ls\n```\n\nThe general usage of this mode is to run\n\n```bash\ndocker run --rm \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    ghcr.io/localstack/localstack-docker-debug:main \\\n        diagnose \\\n        --source-container \"Application Container\" \\\n        --target-container \"LocalStack\"\n```\n\nThis attempts to diagnose the connectivity issues between your application container and target container by temporarily adjusting docker user-defined networks.\n\nIt will output suggestions on what changes to make to the command line.\n\nIf the `--localstack` flag is supplied, or the `--target-container` flag is not supplied, we assume the target container is LocalStack, and verify connectivity by making a request to the [health endpoint](https://docs.localstack.cloud/references/internal-endpoints/#localstack-endpoints).\n\n### Probe\n\nThis mode scans your docker network for network specific information about the containers you are currently running, and outputs a JSON log file to stdout.\n\n```bash\ndocker run --rm \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    ghcr.io/localstack/localstack-docker-debug:main \\\n        probe \u003e topology.json\n```\n\nThis command collects:\n\n* networks:\n    * id\n    * name\n    * subnet\n    * gateway\n    * containers:\n        * id\n        * name\n        * image\n        * labels\n        * status\n        * interfaces:\n            * network name\n            * gateway\n            * ip address\n\nand outputs the results to `topology.json`.\n\n### Bundled networking tools\n\nIn addition to the code bundled in this docker image, we also add a few networking tools to the container, so that they can be run to gather more information.\nThe tools we bundle are listed in the [`Dockerfile`](https://github.com/localstack/localstack-docker-debug/tree/main/Dockerfile#L7-L13).\n\nTo use the desired tool, run\n\n```bash\ndocker run --rm \\\n    --entrypoint \u003ctool\u003e \\\n    ghcr.io/localstack/localstack-docker-debug:main \\\n    \u003cargs\u003e\n```\n\nfor example\n\n```\ndocker run --rm \\\n    --entrypoint dig \\\n    ghcr.io/localstack/localstack-docker-debug:main \\\n    example.com\n\n; \u003c\u003c\u003e\u003e DiG 9.18.16-1~deb12u1-Debian \u003c\u003c\u003e\u003e example.com\n;; global options: +cmd\n;; Got answer:\n;; -\u003e\u003eHEADER\u003c\u003c- opcode: QUERY, status: NOERROR, id: 47090\n;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1\n\n;; OPT PSEUDOSECTION:\n; EDNS: version: 0, flags:; udp: 4096\n;; QUESTION SECTION:\n;example.com.                   IN      A\n\n;; ANSWER SECTION:\nexample.com.            78631   IN      A       93.184.216.34\n\n;; Query time: 10 msec\n;; SERVER: 192.168.0.2#53(192.168.0.2) (UDP)\n;; WHEN: Wed Aug 16 08:34:44 UTC 2023\n;; MSG SIZE  rcvd: 56\n```\n\n\n## LocalStack team usage\n\nThis tool can be installed as a pip package, and gives access to an additional command: `render`.\nThis command renders the output of the `probe` command to a graphviz dot files:\n\n```bash\npython -m dockerdebug render -f \u003coutput.json\u003e \u003e output.dot\ndot -Tpng -o output.png output.dot\nopen output.png\n```\n\nIf this doesn't work, you can generate the png in the container:\n\n```bash\ndocker run --rm \\\n    -v \u003cpath to topology.json\u003e:/topology.json \\\n    ghcr.io/localstack/localstack-docker-debug:main render \\\n    -f /topology.json \u003e out.dot\ndocker run --rm \\\n    -v $PWD:/out \\\n    --entrypoint dot \\\n    ghcr.io/localstack/localstack-docker-debug:main \\\n    -Tpng /out/out.dot -o /out/out.png\n```\n\n### Package installation\n\n1. Install `dot` (graphviz)\n2. `pip install -e .`\n\n### Scenarios\n\nThis repository contains scenarios that help explore how this tool works.\nUnder the `scenarios` subdirectory, there are a number of samples, each that set up docker containers.\nEach sample contains the following scripts:\n\n* `setup.sh`: set up the scenario\n* `test.sh`: demonstrate the connectivity issue\n* `teardown.sh`: remove resources created by the `setup.sh` script\n\n\n## Security\n\nWe mount the docker socket because we have to be able to run docker commands.\nIf you have concerns about what this tool does, the source code is available in this repo.\n\n## Contributing\n\nTODO\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Flocalstack-docker-debug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocalstack%2Flocalstack-docker-debug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Flocalstack-docker-debug/lists"}