Docker MiniUPnPc

A minimal image containing MiniUPnPc, the MiniUPnP client.

MiniUPnPc's upnpc command allows for opening and closing ports via UPnP.

Using upnpc in a Docker container makes it possible to add UPnP support for applications in a Docker Compose stack that might not support it themselves.

Installation

The container image is available from Docker Hub and GitHub Packages:

xanderxaj/miniupnpc           # Docker Hub
ghcr.io/xanderxaj/miniupnpc   # GitHub Packages

Security

The image is automatically rebuilt every day to ensure the latest versions of MiniUPnPc and the base image are pulled in.

The images are signed using Cosign and the Fulcio public CA. The images can be verified by running:

cosign verify --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' --certificate-identity-regexp 'https://github.com/XanderXAJ/docker-miniupnpc/.+@refs/heads/main' xanderxaj/miniupnpc
cosign verify --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' --certificate-identity-regexp 'https://github.com/XanderXAJ/docker-miniupnpc/.+@refs/heads/main' ghcr.io/xanderxaj/miniupnpc

Usage

Run the container image as if it is the upnpc command:

# Display usage information (technically this doesn't need host networking but it's kept for consistency)
docker run --rm --net=host xanderxaj/miniupnpc -h

# Forward internal TCP port 1234 to external port 12345
docker run --rm --net=host xanderxaj/miniupnpc -r 1234 12345 TCP

# Delete any forwarding rules exposed on external TCP port 12345 (deleting the previous forwarding rule)
docker run --rm --net=host xanderxaj/miniupnpc -N 12345 12345 TCP

Since UPnP is a multicast protocol, the simplest way to ensure that the Docker container can both contact the router and apply the correct IP address to the port forwarding rule is to use host networking (e.g. as specified in docker-compose.yaml or by using docker --net=host ...).

Build and run locally

If you prefer to build and run it locally, a Docker Compose file has been provided to make it simple:

# Display usage information
docker compose run --build upnp -h

You can test the PR workflows locally using act.

Only run this command on a trusted machine (e.g. a local machine) as the GITHUB_TOKEN will be available in process listings (e.g. ps):

act -s GITHUB_TOKEN="$(gh auth token)" pull_request

xanderxaj / docker-miniupnpc Goto Github PK