@regrapes/gangway

A way aboard remote docker containers over ssh.

Expose a container's port on your local machine or pull a postgres dump to your CWD — without publishing ports on the server, editing your ssh config, or installing anything on the remote.

npx @regrapes/gangway expose my-server
npx @regrapes/gangway pg-dump my-server

Why

You have a database (or any service) running in a container on a remote docker host — maybe inside a swarm overlay network, with no published port. Reaching it used to mean: add a LocalForward to your ssh config, ssh in, install a helper on the server, start a relay, and remember to clean it all up.

gangway does the whole dance from your machine in one command. Everything runs over a single ssh connection, relays bind to the remote's loopback only, and Ctrl+C tears everything down.

Usage

Run ad hoc via npx/bunx, or install globally:

npm install -g @regrapes/gangway

The global install also provides the direct commands gangway-expose and gangway-postgres-dump (same as gangway expose / gangway pg-dump).

Hosts are passed straight to ssh, so both my-server (an alias from your ~/.ssh/config) and [email protected] work.

All selection lists are searchable: type to filter, where every whitespace-separated term must appear in the name (test db matches names containing both test and db).

gangway expose [ssh-host]

Forward a port of a remote container to your local machine:

$ gangway expose my-server
? Select container › myapp_db.1.zbog13… (postgres:17-alpine)
? What local port to open? › 5432
Forwarding localhost:5432 → my-server → myapp_db…:5432

Now connect to localhost:5432 as if the container ran locally. The tunnel stays in the foreground; Ctrl+C stops it and removes the relay from the remote.

The container port is read from the image's exposed ports (you pick one if there are several, or type one if the image declares none). The local port defaults to the container port and is fully editable.

Without an ssh host, gangway expose works on your local docker instead: it publishes a port of an already-running local container that was started without -p, via a socat sidecar.

gangway pg-dump <ssh-host>

Dump postgres databases from a remote container to the current directory:

$ gangway pg-dump my-server
? Select container › myapp_db.1.zbog13… (postgres:17-alpine)
? Select databases › ◉ myapp ◯ postgres
Dumping myapp → my-server_myapp_2026-08-18T11-16-32.sql.gz (4.2 MB)

Databases are listed live from the server; select one or more (the prompt is skipped when there is only one). Each database becomes a gzipped plain-SQL file named <host>_<database>_<timestamp>.sql.gz. Restore with:

gunzip -c my-server_myapp_*.sql.gz | psql -h localhost -U myapp myapp

A failing pg_dump fails the run and removes the partial file — you never end up with a silently truncated dump.

How it works

• All remote commands and the tunnel share one ssh connection (ControlMaster), so you authenticate once.
• expose (remote): container IPs on overlay/bridge networks are often not reachable from the docker host itself, so gangway starts a throwaway alpine/socat relay container attached to the target's network, published on the remote's loopback only at a random port, and opens ssh -L localPort:127.0.0.1:relayPort. Nothing is ever exposed on the server's public interfaces, and the relay is removed on exit.
• expose (local): a foreground alpine/socat sidecar joined to the container's network, publishing the chosen port.
• pg-dump: docker exec <container> pg_dump | gzip on the remote, streamed over ssh into a local file. The connecting role is taken from the container's POSTGRES_USER env var (falling back to postgres).

Requirements

• Local: node ≥ 18, an ssh client.
• Remote: docker; bash (for pg_dump pipe failure detection); for expose, the container must be on an attachable, non-internal network and the host must be able to run alpine/socat.

Caveats

• If the process is killed hard (SIGKILL, terminal crash), the relay container can linger on the remote. It is named expose-relay-<pid> and started with --rm, so it is easy to spot and remove: docker rm -f expose-relay-…
• pg_dump runs with the version shipped inside the selected container, which always matches the server version.

License

MIT