{"id":13451603,"url":"https://github.com/Shimmur/shipspotter","last_synced_at":"2025-03-23T19:32:08.556Z","repository":{"id":36686262,"uuid":"165446547","full_name":"Shimmur/shipspotter","owner":"Shimmur","description":"Tool for tunneling a port forward into remote Docker containers over SSH 🚢","archived":false,"fork":false,"pushed_at":"2024-01-25T16:14:24.000Z","size":164,"stargazers_count":120,"open_issues_count":1,"forks_count":7,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-16T05:27:16.302Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Shimmur.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-12T23:29:26.000Z","updated_at":"2024-07-23T06:16:34.000Z","dependencies_parsed_at":"2024-06-18T22:53:43.057Z","dependency_job_id":"bfcc2ecd-dd88-4f3e-9fd7-780cf0161ccc","html_url":"https://github.com/Shimmur/shipspotter","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shimmur%2Fshipspotter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shimmur%2Fshipspotter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shimmur%2Fshipspotter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shimmur%2Fshipspotter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shimmur","download_url":"https://codeload.github.com/Shimmur/shipspotter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245157941,"owners_count":20570100,"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-07-31T07:00:56.834Z","updated_at":"2025-03-23T19:32:07.642Z","avatar_url":"https://github.com/Shimmur.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"Shipspotter\n===========\n\nA remote port forwarding tool for accessing services inside Docker containers.\nThose private admin interfaces, JMX ports, or Erlang/Elixir distribution ports\nnot open to the outside world? No problem.\n\nShipspotter automates the workflow of connecting to a remote Docker host,\nfinding the container you need to connect to, and then forwarding the ports to\nthe appropriate container on the Docker bridge network.\n\n**Example:** Nginx with no exposed ports, inside a remote Docker container.\n![Shipspotter demo](./assets/shipspotter.gif)\n\nInstallation\n------------\n\n * Binaries: [On the releases page](https://github.com/Shimmur/shipspotter/releases)\n * From Source: `go get github.com/Shimmur/shipspotter`\n\nBasic Usage\n-----------\n```\n./shipspotter -h docker1 -n elixir -p 9001:9001 -p 7946:7946 -a 127.0.0.2\n```\n\nThis will open an SSH tunnel to the host `docker1`, leveraging either an SSH\nagent, or prompting you for the passphrase to your SSHKey. Over the tunnel,\nshipspotter will connect to Docker on the default Unix socket\n`/var/run/docker.sock` and look for a container with an image name that\ncontains `elixir`. If more than one is present, it will list all of them and\nthen connect to the last one it finds. If you'd rather connect to a different\none you can supply the `--container-id` option and specify one of the others it\nlisted for you. You may specify any number of ports to forward. \n\n**Note**: only TCP forwarding is supported.\n\nThe final `-a` argument tells shipspotter to bind on the local address\n`127.0.0.2`. This is useful for remotely connecting Erlang/Elixir containers\nusing EPMD and distribution. The EPMD 4369 port is also forwarded by default.\nIf you don't want it to be you may specify `--no-forward-epmd`.\n\n\n```\nusage: shipspotter --hostname=HOSTNAME [\u003cflags\u003e]\n\nFlags:\n      --help                   Show context-sensitive help (also try --help-long and --help-man).\n  -h, --hostname=HOSTNAME      The remote hostname to connect to\n  -p, --port=8080:80 ...       The local:remote port to connect to. e.g. 8080:80\n  -a, --local-address=\"127.0.0.1\"\n                               The local IP address to listen on\n  -l, --username=\"youruser\"    The ssh username on the remote host\n  -s, --docker-sock=\"unix:///var/run/docker.sock\"\n                               The Docker socket address on the remote host\n  -n, --image-name=IMAGE-NAME  The Docker image to match on for this application\n  -c, --container-id=CONTAINER-ID\n                               The Docker container ID to match for this application\n  -i, --ssh-key=\"/Users/youruser/.ssh/id_rsa\"\n                               Path to the ssh private key to use\n  -P, --ssh-port=\"22\"          Port to connect to ssh on the remote host\n  -e, --forward-epmd           Shall we also forward the EPMD port?\n  -d, --debug                  Turn on debug logging\n```\n\nShipspotter attempts sane default values for most of the options. You should\nonly override them if you are sure you need to.\n\nSample Output\n-------------\n```\n$ ./shipspotter -h docker1 -n elixir -p 9001:9001 -d -a 127.0.0.2\n\n     _     _                       _   _\n    | |   (_)                     | | | |\n ___| |__  _ _ __  ___ _ __   ___ | |_| |_ ___ _ __\n/ __| '_ \\| | '_ \\/ __| '_ \\ / _ \\| __| __/ _ \\ '__|\n\\__ \\ | | | | |_) \\__ \\ |_) | (_) | |_| ||  __/ |\n|___/_| |_|_| .__/|___/ .__/ \\___/ \\__|\\__\\___|_|\n            | |       | |\n            |_|       |_|\n\nDEBU[0000] Turning on debug logging\nINFO[0000] Found matching container:\nINFO[0000]  - id:    9b62e46debe1\nINFO[0000]  - image: elixir\nINFO[0000]  - name:  /thirsty_keller\nINFO[0000]  - up:    22h34m30.789978s\nINFO[0000] Using container: 9b62e46debe1\nINFO[0000] Container IP address: 172.17.0.4\nINFO[0000] Forwarding ports:\nINFO[0000]  - 9001:9001\nINFO[0000] Forwarding EPMD on 4369\n```\n\nRequirements\n------------\n\n1. You must have read access to the Docker Unix socket on the remote system\n   with the user you are logging in with. This can usually be accomplished\n   by adding the user to the `docker` group on most distros. **If you do not**\n   you may also connect over TCP on the remote host, by specifying the\n   `--docker-sock` option. Note that this requires Docker to be listening\n   on the non-SSL TCP port (usually on 127.0.0.1 only). Specify TCP sockets\n   prefixed with `tcp://` according to the manner that Docker would normally\n   expect.\n\n2. You must be using ssh key authentication, either with an agent or without.\n   It would not be hard to add password auth.\n\nUtilities\n---------\n\nFor some use cases it's helpful to add an aliased address locally. This is true\nwhen, for example, you need to connect an Erlang VM up to a remote container\nto do distribution or run remote Observer. There is an `alias.sh` script provided\nto do that, with support for macOS and Linux.\n\nElixir/Erlang Remote Observer\n-----------------------------\n\nOne good use case for Shipspotter is connecting to a remote Erlang VM and\nrunning a remote observer process there. To do this you must:\n\n * Set the remote node name to `\u003cyour process\u003e@127.0.0.2` beforehand\n * Run the `alias.sh` script from this distribution\n * Start shipspotter:\n   ```\n   shipspotter -h docker1 -n \u003cyour image\u003e -p 9001:9001 -d -a 127.0.0.2\n   ```\n * Start a local `iex` session like:\n   ```\n   iex --name debug@127.0.0.1 --cookie \u003cyour cookie\u003e\n   ```\n * Then in the iex session:\n   ```\n   iex(1)\u003e Node.connect :\"\u003cyour process\u003e@127.0.0.2\"\n   true\n   ```\n   If you don't get `true` back, look for error output from shipspotter.\n * Start Observer `:observer.start`. The select the remote node from the\n   menu.\n\nElixir Remote Shell\n--------------------\n\nAnother good use case for Shipspotter is connecting to a remote Elixir shell \nso that you can run functions directly.\n\n * Run `sudo ./alias.sh` in the directory where you downloaded it. \n * Start shipspotter:\n   ```\n   shipspotter -h \u003chostname\u003e -n \u003cservice\u003e -p 9001:9001 -d -a 127.0.0.2\n   ```\n    * Example values for `service` are `hermes` or `digits`. **NOTE** if you\n      have a different user ID on your local machine than you do on our\n      infrastructure, you will need to also supply `--username` or `-l` and provide\n      the correct user ID.\n * Inspect the output to make sure that shipspotter has connected to the\n   correct container. A host may have more than one container. If not, use\n   the `-c` option to specify the exact container ID and remove the `-n`\n   option.\n * Start a local `iex` session like:\n   ```\n   iex --name debug@127.0.0.1 --cookie \u003cyour cookie\u003e --remsh \"\u003cservice\u003e@127.0.0.2\"\n   ```\n     * In place of `\u003cservice\u003e` substitute the name of the service. E.g. `digits`\n * Then in the iex session:\n   ```\n   iex(\u003cservice\u003e@127.0.0.2)1)\u003e run the command you want\n   ```\n\nNote: If hitting tab to autocomplete crashes the remote shell, make sure that\nthe local and remote versions of elixir and otp match.\n\nContributing\n------------\n\nContributions are more than welcome. Bug reports with specific reproduction\nsteps are great. If you have a code contribution you'd like to make, open a\npull request with suggested code.\n\nPull requests should:\n\n * Clearly state their intent in the title\n * Have a description that explains the need for the changes\n * Not break the public API\n\nPing us to let us know you're working on something interesting by opening a\nGitHub Issue on the project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShimmur%2Fshipspotter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FShimmur%2Fshipspotter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShimmur%2Fshipspotter/lists"}