Docker

Run your services in Docker Compose? Add one container to your project and your services become reachable from the internet on a dedicated public IPv4 address, without changing those services at all. You do not add ports: entries, you do not need a routable address from your ISP, and there is nothing to open on your router or your host firewall: inbound traffic arrives over the tunnel rather than through a published port.

Before you start

• A GetPublicIP IP address and its API key — see Create an API Key
• Linux: Docker Engine and Compose v2, meaning docker compose rather than the older docker-compose script
• macOS: Docker Desktop, on either Intel or Apple Silicon
• Windows: Docker Desktop in Linux containers mode, on a WSL2 6.6 kernel. Check with wsl --version, and run wsl --update if it reports anything older, because kernels before 6.6 are missing a netfilter module the tunnel needs

Everything on this page works unchanged on Windows and macOS with Docker Desktop, with nothing to install beyond Docker Desktop itself. It is free for personal use, education, non-commercial open source, and small businesses with fewer than 250 employees and under $10M in annual revenue; larger organisations need a paid subscription from Docker. See macOS and Windows for the detail on each.

The image is published for linux/amd64 and linux/arm64 at ghcr.io/getpublicip/getpublicip.

Put your API key in a .env file

Create a .env file next to your compose file. See Create an API Key for more information.

CopyGETPUBLICIP_API_KEY=your-api-key-from-the-dashboard

Compose reads that file automatically, which is why the compose files below refer to ${GETPUBLICIP_API_KEY} rather than containing the key itself. Add .env to your .gitignore.

Add to your Docker compose file

Add this service alongside the containers you already run:

Copyservices:
  getpublicip:
    image: ghcr.io/getpublicip/getpublicip:latest
    restart: unless-stopped
    environment:
      GETPUBLICIP_API_KEY: "${GETPUBLICIP_API_KEY}"
      GETPUBLICIP_MAPPINGS: "8080/tcp->web:80; 443/tcp->web:443"
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    sysctls:
      net.ipv4.ip_forward: 1
      net.ipv4.conf.all.src_valid_mark: 1
      net.ipv6.conf.all.forwarding: 1
    networks:
      - appnet

Replace appnet with the network your own services are already on, and web with your own service names. Everything else can stay as it is.

Keep restart: unless-stopped. It is not boilerplate. It is how the agent recovers from the faults it cannot fix in place, as described in Connection drops.

A complete working example

Nothing to add it to yet? This is a whole setup in one file: a web server on your own public IP address, reachable from anywhere. Save it as compose.yaml:

Copyservices:
  web:
    image: nginx:alpine
    restart: unless-stopped
    networks:
      - appnet

  getpublicip:
    image: ghcr.io/getpublicip/getpublicip:latest
    restart: unless-stopped
    environment:
      GETPUBLICIP_API_KEY: "${GETPUBLICIP_API_KEY}"
      GETPUBLICIP_MAPPINGS: "80/tcp->web:80"
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    sysctls:
      net.ipv4.ip_forward: 1
      net.ipv4.conf.all.src_valid_mark: 1
      net.ipv6.conf.all.forwarding: 1
    networks:
      - appnet

networks:
  appnet:

Then start it:

Copydocker compose up -d

Give it about 30 to 60 seconds and open http://{YOUR IP ADDRESS} from any network, or from your phone on mobile data. The nginx welcome page means a request from the internet reached your container.

Two things are worth noticing about that file. web has no ports: entry, so nginx is reachable from the internet while not being published on the machine running it. And both services join appnet, because the agent resolves web by service name and can only do that on a network the two of them share. Compose would put both on the project's default network if you left the networks: blocks out entirely, and that works just as well, but naming the network makes the requirement visible.

Map your ports

GETPUBLICIP_MAPPINGS decides which ports on your public IP go to which of your containers. Separate entries with ; or newlines:

CopypublicPort[/proto[,proto]][/stack[,stack]]->service[:internalPort]

The segments after the port are matched by keyword, so their order does not matter. 8080/tcp/ipv4 and 8080/ipv4/tcp mean the same thing.

Note that you refer to your containers by service name, never by IP address. Compose assigns container IPs dynamically, so the agent resolves those names itself and re-checks them every 30 seconds. When a container restarts on a different IP, the forwarding rules are updated automatically.

A destination can also be any hostname that resolves, or a literal IPv4 address, and all three behave identically. A literal IPv6 address is not accepted; use a hostname with an AAAA record instead.

SSL / TLS

GetPublicIP works at the packet level. It forwards TCP and UDP to your containers and leaves everything above that to you, and encryption is one of the things above it. So if you serve HTTPS, your own service terminates the TLS connection. Map 443 to the container that already holds your certificate, and nothing about your TLS setup changes:

CopyGETPUBLICIP_MAPPINGS: "443/tcp->web:443; 80/tcp->web:80"

We do not decrypt your traffic

Your public IP is not a TLS proxy. It holds none of your certificates or private keys, so it has nothing to decrypt with. The TLS session is negotiated directly between your visitor's browser and your own service, and it stays encrypted the whole way: out of the browser, across the internet to your public IP, through the WireGuard tunnel, and into your container, where it is decrypted for the first time.

The tunnel adds a second layer of encryption between our network and your machine, but it is the outer layer. What travels inside it is the same TLS ciphertext your visitor sent. Your certificates and private keys never leave your machine, there is nothing to upload to us, and your traffic is never decrypted and re-encrypted on the way through. We do not decrypt TLS traffic, and we have no plans to.

Your service needs a valid certificate

Because the certificate lives on whichever service terminates the connection, that service needs a valid one, exactly as it would on any other public host.

• Point a domain at your public IP. Add an A record for your IPv4 address, and an AAAA record if you serve IPv6 as well. Certificate authorities issue for domain names, so a bare IP address is not enough.
• Get the certificate from Let's Encrypt. It is free, automated, and well suited to this. Caddy and Traefik request and renew for you with no more configuration than your domain name; nginx and Apache pair with certbot.
• If you use an HTTP-01 challenge, map port 80 as well as 443 to the same service. Let's Encrypt connects to port 80 on your public IP to answer the challenge, and it fails if only 443 is mapped. A DNS-01 challenge does not need port 80.
• Leave those ports mapped. Renewal repeats the same challenge every 60 days or so, and it fails quietly if the mapping has gone.

Plain HTTP is still plain

A mapping to port 80 serving unencrypted HTTP is unencrypted between your visitor and your public IP, exactly as it would be anywhere else on the internet. The WireGuard tunnel covers only the hop between our network and your machine. If the content matters, terminate TLS.

Forwarding to a service on the host

Already running something on the box and just want it public? Point a mapping at host.docker.internal, the address you would reach for anyway:

Copyservices:
  getpublicip:
    environment:
      GETPUBLICIP_MAPPINGS: "8081/tcp->host.docker.internal:8081"
    extra_hosts:
      - "host.docker.internal:host-gateway"   # needed on Linux; built in on Docker Desktop

Two things to check, because they produce the same "it just doesn't work" symptom:

• The host service must listen on 0.0.0.0, not 127.0.0.1. A service bound to loopback refuses the connection from the container. Confirm with ss -lntp.
• A host firewall will drop it silently unless you allow the bridge subnet inbound on docker0 or the br-* interface. This is the one case on this page where a firewall rule is needed, and it covers the container-to-host hop, not inbound traffic from the internet.

Host and container destinations can be mixed freely in a single GETPUBLICIP_MAPPINGS.

Docker Compose networks

Because targets are resolved by service name, the getpublicip container has to be on the same Docker network as the containers it forwards to.

• One default network. Nothing to do, it works as-is.
• Several networks. List getpublicip on every network that holds a service it forwards to.
• Targets in a different compose project. Both projects need to join a shared external network:

  Copydocker network create shared
  

  
  Then in each compose file:

  Copyservices:
    getpublicip:
      networks:
        - shared
  
  networks:
    shared:
      external: true
  

If this is wrong, the logs repeat waiting for destinations to resolve and the agent keeps retrying rather than failing outright.

Check the logs

Copydocker compose up -d
docker compose logs -f getpublicip

A healthy start brings the tunnel up on interface pi0, resolves your destinations, installs the forwarding rules, and pushes the mappings to GetPublicIP. The agent then keeps running, re-checking the destinations and the tunnel itself on an interval.

This is what a healthy tunnel looks like in the log. It is worth knowing now, so you have something to compare against later:

Copytunnel status up=true interfaces=1 peers=1 healthy=true handshakeAge=31s rxDelta=0

healthy=true is the field that matters. Do not read up=true on its own as good news, because it only means the interface exists, and it stays true even on a tunnel that has quietly stopped passing traffic.

Testing

Give it about 30 to 60 seconds before you test. Pushing new mappings puts your IP address into an updating state while the platform applies them, and requests made during that window fail. Two or three failures followed by success is the normal sequence, not a fault.

Test from a network that is not your own. Mobile data is the easiest option:

Copycurl http://{YOUR IP ADDRESS}

Connection drops

Nothing to restart and nothing to configure. The tunnel re-establishes itself after a dropped connection, a router reboot, or your ISP handing you a new address.

Most of the time it repairs itself without the agent having to do anything. The tunnel is an outbound connection held open by a keepalive every 25 seconds, and our server re-learns your address from any packet the agent sends, so when your router drops the mapping or moves you to a new port, the next keepalive puts it back. On a real tunnel we measured traffic flowing again about 17 seconds after connectivity returned.

For the rarer faults a keepalive cannot fix, the agent stops rather than trying to repair the tunnel in place, and Docker restarts it into a clean, fresh connection. In the log you will see tunnel appears broken when it first notices, and then exiting so the container is restarted if the problem persists across several checks. That is the recovery working, not an error.

This is the one place the compose file has to be right: recovery depends on your restart policy, so keep restart: unless-stopped on the service. Without it the container stops and stays stopped.

What this does not do is keep your service reachable while your internet is down. If the connection to your machine is gone, so is your service. The tunnel simply picks itself back up as soon as there is a connection to use.

Container permissions

macOS

Use Docker Desktop and the compose file above works unchanged, on both Intel and Apple Silicon.

Other Docker runtimes for macOS (Colima, OrbStack, Rancher Desktop) run different kernels and have not been verified, so we cannot say whether the tunnel comes up on them.

Windows

The compose file above needs no changes on Windows using Docker Desktop.

Docker Desktop needs 64-bit Windows 10 or 11, on a version still supported by Microsoft, and the WSL 2 backend, which is the default. There are then two things to check before you start.

1. Docker Desktop must be in Linux containers mode. The Windows containers engine cannot run this image, and it is not available on the WSL 2 backend in any case.

2. Your WSL2 kernel must be 6.6.x. Older kernels, 5.15 among them, are missing a netfilter module the tunnel needs, and there is no way to work around it from inside the container. The tunnel simply fails to come up with unknown option '--save-mark'. Check and update from PowerShell:

Copywsl --version    # need "Kernel version: 6.6.x"
wsl --update     # if it reports anything older

6.6 only became the settled default around WSL 2.4 to 2.7, so a machine that has not been updated in a while can still be on 5.15. The same requirement applies if you run Docker CE inside a WSL2 distribution rather than Docker Desktop, because it shares the same kernel.

On 6.6, tun is a module rather than built in, so it is worth confirming the device node actually exists before blaming the agent. This command fails at container creation if it is missing:

Copydocker run --rm --device /dev/net/tun alpine ls -l /dev/net/tun

No Windows Firewall rule or port forward is needed. Inbound traffic arrives over the tunnel, so neither Windows Firewall nor WSL's NAT is in the path.

Laptops and sleep

Sleep drops the tunnel. On macOS and Windows the Linux VM suspends when your machine does, and your public IP is unreachable until it wakes, at which point the tunnel re-establishes itself automatically. Try it on your laptop by all means, but run it on a server: a machine that sleeps is a poor host for an always-on public IP.

One API key, one tunnel

A WireGuard key belongs to a single endpoint. If two containers run with the same API key, they will knock each other offline. Whichever one handshaked most recently wins, and the other silently drops traffic until its next keepalive. It looks like random flakiness rather than a clear error. The usual cause is testing on a laptop while a server is already connected with the same key.

This one is self-diagnosing: both containers restart over and over, because each keeps deciding it is the broken one. A container that is restart-looping on a machine whose internet is fine almost always means a second agent is using the same key.

Use one API key per running tunnel.

Troubleshooting

docker compose logs -f getpublicip is the place to start.

To check a configuration without bringing anything up or contacting the API, run it in dry run mode. It prints the rules it would apply and exits:

Copydocker run --rm \
  -e GETPUBLICIP_API_KEY=x -e GETPUBLICIP_DRY_RUN=true \
  -e GETPUBLICIP_ISOLATED_INTERFACE=eth0 \
  -e GETPUBLICIP_MAPPINGS="8080/tcp->web:80" \
  ghcr.io/getpublicip/getpublicip:latest

Frequently Asked Questions

New to GetPublicIP? Start with Getting Started for how the service works. Running your services directly on a host instead of in containers? See the Linux and Windows guides.