TunnelNet Guides

Docker Compose with a static IP: fixed container addresses and a fixed public address (tested)

2026-11-25

"Static IP" means two different things with Docker Compose, and this page tests both:

  1. A fixed address for each container on its Compose network. Docker does this.
  2. A fixed public address that people on the internet can reach. TunnelNet does this.

Tested on

Date: 18 November 2026 · Host: Debian 12, Docker Engine 29.10.0 and Docker Compose v5.8.0 from Docker's own repository, a test virtual machine in our lab behind a NAT router with no port forwarding · On the real service: the normal TunnelNet installer, on an internal test account · The visitor: a test machine in Atlanta. Not tested: IPv6 fixed addresses (ipv6_address), macvlan or ipvlan networks (containers with addresses on your home network), carrier CGNAT itself (our line was NAT without port forwarding; inbound behaves the same), and https. Addresses here are examples: 203.0.113.47 is your TunnelNet address and 192.168.240.0/24 is the private Compose network we chose (any private range you do not already use works).

Part 1: a fixed address for each container

This is the compose.yaml we ran:

services:
  web:
    image: nginx:1.27-alpine
    restart: unless-stopped
    volumes:
      - /srv/web:/usr/share/nginx/html:ro
    ports:
      - "8081:80"
    networks:
      appnet:
        ipv4_address: 192.168.240.10
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/pg
    secrets: [pg]
    networks:
      appnet:
        ipv4_address: 192.168.240.20
networks:
  appnet:
    ipam:
      config:
        - subnet: 192.168.240.0/24
          gateway: 192.168.240.1
secrets:
  pg:
    file: ./pg.txt

pg.txt holds the database password and is readable only by root. Keep passwords out of compose.yaml.

Start it and look at the addresses:

$ sudo docker compose up -d
 Network compose-static_appnet Created
 Container compose-static-web-1 Started
 Container compose-static-db-1 Started
$ for c in $(sudo docker compose ps -q); do sudo docker inspect -f "{{.Name}} {{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}" $c; done
/compose-static-db-1 192.168.240.20
/compose-static-web-1 192.168.240.10
$ curl -s http://192.168.240.10/
hello from a container

The addresses stay put. After a full recreate:

$ sudo docker compose down && sudo docker compose up -d
/compose-static-db-1 192.168.240.20
/compose-static-web-1 192.168.240.10

After a host reboot (back in 34 seconds), both containers were up again on the same addresses and the page answered.

Undo: sudo docker compose down removes the containers and the network. Add -v to also remove named volumes; this example has none.

Mistakes, and the exact errors we got

A: ipv4_address on a network with no subnet set
Error response from daemon: invalid config for network compose-bad_appnet: invalid endpoint settings:
no configured subnet contains IP address 192.168.241.10

B: an address outside the network's subnet
... no configured subnet contains IP address 192.168.99.10

C: a subnet another Compose project already uses
failed to create network compose-bad_appnet: Error response from daemon: invalid pool request: Pool overlaps with other one on this address space
  • A: add ipam: with a config: entry and a subnet: to the network.
  • B: pick an address inside that subnet.
  • C: pick a subnet nothing else on the host uses. docker network ls and docker network inspect show the ones in use.

Part 2: a fixed public address for the stack

Install TunnelNet on the host first; the install is shown in Expose a Docker container without port forwarding. Then open the port Compose published on the host:

$ sudo tnet ports allow tcp 8081 --note=compose-web
Allowed tcp 8081

From the outside machine:

03:02:06 visitor -> 203.0.113.47:8081: hello from a container   (1 s after allow)
03:02:06 visitor -> 203.0.113.47:5432 (database, not published, not allowed): (no answer)

The database has no ports: line, so it is only reachable inside appnet: by web at 192.168.240.20 or by the service name db. That is the usual pattern: publish only what visitors need.

Undo:

$ sudo tnet ports deny 8081
Denied port 8081

It stopped answering 59 seconds later in our run. Use deny 8081, not deny tcp 8081: the second is refused with ERROR: 'tcp' is not a port.

Good to know

  • Containers on the same Compose network can also reach each other by service name (db). A fixed address is mainly useful when something outside Docker needs to know where a container is: a firewall rule, a reverse proxy on the host, or an old app that only takes an address.
  • The fixed container address is private. Visitors never use it; they use the public address and the published port.
  • tnet ports allow opens the port to everyone, so close ports you are not using.