basforge

Search titles, text and the “If it doesn’t work” cases.

    RU

    Docker networks: neighbors by name, a shared network with Traefik and a database with no way out

    Containers find each other by name only within their own network: the default bridge network has no names. A service behind a proxy needs two networks — a shared proxy network that Traefik uses to reach it, and an internal one with internal: true, where the database is visible to its neighbors but can’t reach the outside itself.

    How containers find each other

    A Docker network with the bridge driver is a bridge on the host (docker0 for the default network, br-<id> for the rest) plus its own subnet: 172.17.0.0/16, 172.18.0.0/16 and onward in order. A container gets an address in it, and after a recreate the address may be different. That’s why neighbors are reached by name.

    Names are answered by the DNS built into Docker: in every container on a user-defined network it listens on 127.0.0.11 (nameserver 127.0.0.11 in the container’s /etc/resolv.conf). It knows the container name, the compose service name and aliases — but only for neighbors on the network: from another network the name db won’t resolve. The default bridge network, where docker run without --network lands, has no built-in DNS at all: a neighbor is visible there only by address.

    For each stack, compose creates a <project>_default network and puts every service without its own networks: list on it. The project name is the stack directory name (The compose project name), so a stack in /opt/umami gets the umami_default network.

    Neighbors don’t need published ports: on one network a container sees all of the other’s ports. ports: is only for access from the host and the outside, and Docker opens it past the firewall (Docker ports bypass the input chain).

    Which network for what

    Network What it gives When to use it
    default bridge an address and internet access; no names a one-off docker run --rm
    the stack network <project>_default neighbors by service name; compose creates and removes it with the stack everything inside one stack
    your own shared one, external: true in compose neighbors from different stacks; the stack neither creates nor removes it the proxy and the services behind it — the proxy network
    internal: true neighbors by name, no way out a database, a cache — anything that only talks to its own
    network_mode: host the whole host network, no ports: needed; the host firewall treats it like a regular program the service needs the host network: device discovery over mDNS, hundreds of ports

    On a server with Traefik, a stack ends up laid out like this:

    network proxy — shared per server, created once
    ├── traefik        ports 80 and 443 published on the host
    ├── umami          on two networks: Traefik reaches it here
    └── memos
    
    network umami_internal — internal: true, the umami stack only
    ├── umami          DATABASE_URL=…@db:5432
    └── db             no ports on the host, no internet access

    Setup

    The example is an Umami stack with Postgres in /opt/umami on a server that already runs Traefik (A service over HTTPS). The compose snippets below show only what concerns networks.

    1. See which networks already exist

      docker network ls --format '{{.Name}}\t{{.Driver}}'
      # bridge	bridge
      # host	host
      # none	null

      Docker always has these three. host is the host’s own network, none is a container with no network, only lo. Everything else in the list was created by us or by compose.

    2. Create a shared network for the proxy

      sudo docker network create proxy

      Once per server. Compose neither creates nor removes such a network: docker compose down in any stack, even Traefik’s, leaves it alone, and the other services on it stay where they are.

    3. Connect the service to the shared network

      services:
        umami:
          networks: [proxy, internal]
          labels:
            - "traefik.enable=true"
            - "traefik.docker.network=proxy"
      
      networks:
        proxy:
          external: true

      external: true — compose looks for an existing network with this name and doesn’t add the project prefix.

      traefik.docker.network is needed as soon as a service has more than one network. Without it, Traefik takes the container’s address from any of them — and if it took the address on the internal network, where Traefik itself isn’t, the request hangs until Gateway Timeout. The label holds the network name in Docker, as in docker network ls. If the compose key is different (traefik_proxy: with name: proxy), the label still says proxy.

    4. Lock the database into an internal network

      services:
        umami:
          environment:
            - DATABASE_URL=postgresql://umami:${DB_PASSWORD}@db:5432/umami
          networks: [proxy, internal]
      
        db:
          image: postgres:16-alpine
          networks: [internal]
      
      networks:
        proxy:
          external: true
        internal:
          internal: true

      A network with internal: true has no way out: umami reaches the database by the name db, while no packet from the database itself will get to the internet — it doesn’t need to. The database has no ports:: its port 5432 is visible to a network neighbor anyway.

      Compose names the network umami_internal: it adds the project name to the key from the file.

      A service’s networks: list replaces the default network rather than adding to it. So for every service, list all the networks it should be on (networks replaces default).

    5. Bring the stack up and check names from inside the network

      cd /opt/umami
      docker compose up -d
      docker run --rm --network umami_internal alpine ping -c1 -W2 db
      # PING db (172.19.0.2): 56 data bytes
      # 64 bytes from 172.19.0.2: seq=0 ttl=64 time=0.104 ms

      A throwaway container on the same network finds db by service name: the name works across the whole network, not just inside the stack. Your subnet will differ — Docker hands them out in order.

    A service on the host itself

    Sometimes the program runs on the host and a container talks to it: Ollama on the host and a web UI for it in a container. 127.0.0.1 inside the container is the container itself, so give it a name for the host:

    services:
      open-webui:
        extra_hosts:
          - "host.docker.internal:host-gateway"

    Docker substitutes the address of the docker0 bridge for host-gateway, usually 172.17.0.1, and the container goes to http://host.docker.internal:11434. A service that listens only on 127.0.0.1 won’t answer on that address: Ollama does exactly that by default and needs OLLAMA_HOST=0.0.0.0.

    The host firewall closes such a port to the outside: a program on the host itself, unlike a published Docker port, receives packets through input. A request from a container to the host is incoming for the firewall too, so ufw with default deny incoming drops it as well until there’s a rule sudo ufw allow from 172.16.0.0/12 to any port 11434. 172.16.0.0/12 covers Docker’s default subnets, 172.17–172.31. Check from another computer that the port is closed from the outside (A model on your own hardware, “How to check”).

    If it doesn’t work

    A container can’t find its neighbor: could not translate host name "db" to address or getaddrinfo ENOTFOUND db

    Cause
    They’re on different networks. Often because the service got a networks: list and left the default network, where the database stayed (networks replaces default).
    Fix
    See who’s on the network: docker network inspect umami_internal --format '{{range .Containers}}{{.Name}} {{end}}'. Put both services on one network.

    Containers started with docker run; the neighbor answers by IP, but by name — bad address

    Cause
    Without --network a container lands on the default bridge network, which has no built-in DNS.
    Fix
    Create your own network and run with --network, or move the launch to compose: it creates the stack’s network itself.

    network proxy declared as external, but could not be found

    Cause
    Compose doesn’t create a network with external: true: it’s created once per server.
    Fix
    sudo docker network create proxy, then docker compose up -d again.

    The service is on two networks, and Traefik returns Gateway Timeout — always or after a recreate

    Cause
    Without the traefik.docker.network label, Traefik takes the container’s address from any of its networks and may pick the address on the internal one, which Traefik itself isn’t connected to.
    Fix
    Add the label traefik.docker.network=proxy. The value is the network name from docker network ls, not the key from compose.

    A host service doesn’t open from the container at 127.0.0.1

    Cause
    127.0.0.1 inside a container is the container itself: it has its own network and its own lo.
    Fix
    extra_hosts: ["host.docker.internal:host-gateway"] and the address host.docker.internal. The host service listens on 0.0.0.0; ufw closes it from the outside and lets the Docker subnets in.

    A new stack came up, and the server vanished for machines on the home or office network

    Cause
    The new Docker network got a subnet from 192.168.0.0/16, and it clashed with the network the server is reached from.
    Fix
    Set your own address pool in daemon.json (Docker subnet clashes with home network).

    How to check

    Which networks the container is on, and with which addresses:

    docker inspect umami-umami-1 --format '{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{$v.IPAddress}}{{"\n"}}{{end}}'
    # proxy 172.18.0.5
    # umami_internal 172.19.0.3

    Who’s on the shared network — Traefik and every service behind it:

    docker network inspect proxy --format '{{range .Containers}}{{.Name}} {{end}}'

    The database can’t reach the outside:

    docker compose exec db wget -T 5 -q -O /dev/null https://example.org && echo "has access" || echo "no access"
    # no access