Gangplank opens ports on your router for your Docker containers. Add a label to a container and Gangplank asks your router, over UPnP, to forward its ports. When the container stops, the ports can be closed again.
It is made for homelabs and self-hosted setups: media servers, game servers, Nextcloud and anything else you want to reach from outside your home network.
Gangplank (nautical): a movable board used to get on or off a ship, bridging the gap between ship and shore.
Warning
Gangplank is in active development and configuration may change often. Please make sure to carefully read the release notes before updating.
- No router admin pages. Gangplank talks to your router for you.
- Follows your containers. Ports are opened when containers start and refreshed while they run.
- Simple setup. One container with access to the Docker socket, and labels on the services you want to expose.
You need:
- Docker
- A router with UPnP enabled
Run Gangplank as a daemon:
docker run -d --network host \
--restart unless-stopped \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
ionbazan/gangplank:latestOr with Docker Compose:
services:
gangplank:
image: ionbazan/gangplank
network_mode: host
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
restart: unless-stoppedGangplank must use the host network. Otherwise it can't find your router.
If you don't use Docker, download a binary for Linux, macOS, Windows or FreeBSD from the releases page.
Add the gangplank.forward label to a container. With published, every port the container publishes on the host is forwarded on the same port number:
services:
nginx:
image: nginx
ports:
- "80:80"
- "443:443"
labels:
gangplank.forward: "published"You can also pick specific ports, forward a container port that Docker published on a random host port, or list ports for services outside Docker in a YAML file. See the usage guide for examples.
All options, environment variables and commands are described in the advanced guide.
- Reads ports from container labels and from a YAML file.
- Opens ports as soon as containers start (
daemon --poll) and can close them when they stop (--cleanup-on-stop). - Renews mappings before they expire (
--refresh-interval). - Can remove leftover mappings (
--prune) and clean up when it shuts down (--cleanup-on-exit). - Keeps working when Docker restarts or the router is not ready yet.
- Commands to list, add and delete single mappings.
- Mappings are created with a 1 hour lease by default. The daemon renews them every 15 minutes.
- Access to the Docker socket is the same as root access on the host. The security notes show how to use a socket proxy instead.
- Every port you label can be reached from the internet. Only expose what you mean to.
Issues and pull requests are welcome on GitHub.
Before sending a pull request, run:
make test
make lintmake help lists the other commands, like make build and make docker.
Push a tag like v1.2.3. CI then:
- publishes Docker images for all supported platforms to Docker Hub and GHCR,
- creates a GitHub release with binaries, checksums and a changelog (using GoReleaser).
Forks work the same way. Images go to ghcr.io/<owner>/<repo>. To also push to Docker Hub, add a DOCKERHUB_PASSWORD secret. The image name defaults to <owner>/<repo>; set the DOCKERHUB_USERNAME or DOCKERHUB_REPOSITORY repository variables to change it.
MIT