Skip to content

Engineering11 min read

Docker networking: from localhost to production with Coolify

localhost inside a container, service names, what Coolify wires up for you, and why a published port walks right past UFW.

Loïc Simon

Fullstack Developer

Cover image for “Docker networking: from localhost to production with Coolify”

One evening, I wanted to keep an eye on my VPS. Nothing ambitious: Prometheus to collect metrics, cAdvisor to tell it what each container was using. Two services, a bit of YAML, one click on "Deploy" in Coolify. Everything was green.

Then I opened the Prometheus logs:

dial tcp: lookup cadvisor on 127.0.0.11:53: no such host

"No such host." But cAdvisor was running, right there, on the same machine. I could see it in the container list. Prometheus, meanwhile, was calmly insisting it didn't exist.

That's the moment Docker networking stops being a detail. As long as everything works, you don't think about it. The day it breaks, it feels like black magic, especially with an extra layer like Coolify on top. This post is the mental model I wish I'd had that evening. Four pictures are enough: some islands, a bedroom, a boat and a wall.

You don't need to be a sysadmin. If you've ever written a docker-compose.yml, you have everything you need.

The mental model: islands on a sea

Picture your VPS as a calm sea. Every time you start a Docker Compose project, Docker builds a little island on it: a network all of its own. The Compose docs put it plainly. For a project in a myapp folder: "A network called myapp_default is created." Each service then joins it (Docker, Networking in Compose).

Hand-drawn sketch titled each Compose project is an island. A sea labelled your VPS holds a large island named myapp_default, with two cabins, web and db, linked by a dotted line labelled db:5432, and a phone book at 127.0.0.11. A smaller island, another project, holds a cadvisor cabin, with a red question mark between the two. Caption: on the island, containers call each other by service name; across the sea, the phone book says no such host.

Life on an island is simple. Docker keeps a private phone book there, a small DNS server that always answers at the same address, 127.0.0.11 (Docker, Networking overview). If your file has a web service and a db service, web reaches the database by simply writing db:

YAML
services:
  web:
    build: .
    environment:
      DATABASE_URL: postgres://app:password@db:5432/app
  db:
    image: postgres:18

No IP address, and that's on purpose: IPs can change when a container is recreated, names stay. Notice the port too: between services, you use the container port (5432 here). The host port, the one on the left in ports:, "is only used when accessing the service from outside the network" (Docker, Networking in Compose).

Now you can reread my error message. 127.0.0.11:53 is the phone book of Prometheus's island. It looked up cadvisor and answered honestly: nobody by that name lives here. cAdvisor did exist. It just lived on another island.

localhost, or the art of looking under your own bed

Before building any bridges, we need to clear up the most common misunderstanding, the one that trips up almost everyone on day one.

Inside a container, localhost doesn't mean "the server". It means "me". Each container has its own network stack, with its own loopback. An app looking for its database on localhost:5432 is searching its own bedroom, under its own bed. It can search for a long time: the database lives in the next room.

Cross-section sketch titled localhost = my own room. In the left room, my container (web), a puzzled person stands by a bed and asks localhost:5432? Through the wall, in the next room, a database labelled db waits, ignored. Caption: inside a container, localhost means me; call the others by name, db:5432, and listen on 0.0.0.0.

You already know the fix: replace localhost with the service name, db.

The trap has a mirror version, sneakier, and I fell right into it while containerizing my CMS. This time, it's the app that listens in the wrong place. In standalone mode, the little Next.js server listens on the address given by the HOSTNAME variable (Next.js, output). The problem: inside a container, Docker already fills HOSTNAME with the container's ID. So Next.js listens on a single address instead of all of them. The proxy (or the health check that calls localhost), which doesn't necessarily come in through that address, knocks on a door nobody opens, and the browser shows a 502 Bad Gateway. The line that fixes everything, in my Dockerfile:

Dockerfile
ENV HOSTNAME=0.0.0.0

0.0.0.0 means "listen on every interface of the container", including the one the island's network sees. The Coolify docs give exactly this advice when you get a "No Available Server" error: check that the process listens on 0.0.0.0, not only on 127.0.0.1 (Coolify, Docker Compose).

Keep the pair in mind: call others by their name, listen on 0.0.0.0.

Talking to the server itself: host.docker.internal

Sometimes, what your container wants to reach isn't on an island at all but on the mainland: a PostgreSQL installed directly on the VPS, for example.

On Windows and macOS, Docker Desktop gives you a ready-made name, host.docker.internal, that points to your machine. That's what I use to test my CMS image against the PostgreSQL on my PC. On a Linux server, that name doesn't exist by default. You create it with the special value host-gateway, which "resolves to the internal IP address of the host" (Docker, docker container run):

YAML
services:
  web:
    extra_hosts:
      - "host.docker.internal:host-gateway"

This is where most tutorials stop, and where a lot of people get stuck. The container now knows where the server is. Someone still has to answer. By default, PostgreSQL only listens on localhost, which "allows only local TCP/IP 'loopback' connections to be made" (PostgreSQL, Connection settings). From PostgreSQL's point of view, your container isn't local at all. So you also need to:

  1. add the Docker gateway address to listen_addresses in postgresql.conf (avoid *: you'd open the database on every interface, including the public one);
  2. allow the container's subnet in pg_hba.conf. Don't guess it: it depends on the network the container lives on (Coolify creates several), and docker network inspect <network> shows it in the Subnet field;
  3. if UFW is active, allow that same subnet on port 5432 (ufw allow from <subnet> to any port 5432): this traffic, from the container to the host, does go through the firewall;
  4. restart PostgreSQL, because this setting is only read at startup.

Honestly, if the database can live in a container on the same island as the app, that's often simpler. It's what I do for my CMS: the production PostgreSQL is a Coolify resource, reachable only through the internal network, and the "Make it publicly available" option stays unchecked.

What Coolify wires up for you, and what it leaves to you

Back to my error. Coolify adds two things to our map: a boat and a bridge.

The boat: the proxy

Coolify installs a proxy, Traefik by default, in a container called coolify-proxy. It's the one that greets visitors on ports 80 and 443 and drops them off in front of the right app. And here's the part I had misunderstood: you do not need to connect your app to any particular network for the proxy to find it. The proxy "joins the coolify network and the resource-specific networks" (Coolify, Networking in Coolify). The boat docks at every island on its own.

Sketch titled the boat docks by itself, bridges are yours. A sailboat labelled proxy (Traefik) sits by the island my app, with a note: it joins each resource&#x27;s network on its own. On the right, two islands, prometheus and cadvisor, are joined by a plank bridge labelled the coolify network (external: true), with a builder in a hard hat standing on it holding a plan. Caption: a web app behind Coolify has nothing to connect; two resources that talk must both join the bridge.

What the proxy does need to know is which port your container listens on. In a Compose resource, you add it as a suffix to the domain, for example https://app.example.com:3000: the suffix "tells the Coolify proxy which container port receives the request" (Coolify, Docker Compose).

The bridge: the coolify network

This is a shared network that Coolify creates on every server (Coolify, Networking in Coolify). The proxy doesn't use it to find your app. It's for when two different resources need to talk to each other. And that was exactly my situation: I had deployed Prometheus and cAdvisor as two separate resources, so on two islands. The boat docked at each one just fine, but no bridge connected them.

The fix takes a few lines. In the Compose file, you declare that the coolify network already exists (it's external), and you connect the services that need it:

YAML
services:
  prometheus:
    image: prom/prometheus
    networks:
      - coolify

networks:
  coolify:
    external: true

Same thing on the cAdvisor side. For a Compose resource, Coolify also offers a checkbox, Connect to Predefined Network, that does the wiring for you. One detail worth knowing: in that case, Coolify may prefix names to avoid collisions, and its docs advise you to "verify the generated container or service name before using it as a hostname" (Coolify, Docker Compose). If your no such host survives the bridge, that's the first thing to check.

Once both services were on the same network, Prometheus found cAdvisor on the first try. The error that had ruined my evening was actually a very accurate sentence: "I don't know anyone by that name on my island".

Zero ports: why your firewall isn't protecting you

That leaves the most dangerous reflex, one I had too before I understood bridges: "they can't talk to each other, I'll just open the port".

YAML
services:
  prometheus:
    ports:
      - "9090:9090"   # "just testing"

It works, of course. But what you just wrote is "open port 9090 on this server to the whole world". And if you were counting on UFW to filter that, bad news: when Docker publishes a port, the traffic is routed "before the firewall rules can be applied, effectively ignoring your firewall configuration" (Docker, Packet filtering and firewalls). Your ufw status can proudly say "deny", and the side door is open anyway.

Side-view sketch titled a published port walks right past UFW. Between the internet and your VPS stands a wall labelled UFW with a single door, 443, and a stern guard who checks everyone who comes in. A dashed red arrow labelled ports: "9090:9090" runs under the ground from a curious stranger on the internet side straight to a box labelled prometheus :9090, because Docker routes it before the firewall rules apply. Caption: between containers the network is enough; no browser needed means no ports, or 127.0.0.1 only.

Coolify says the same thing, in fewer words: "Do not publish a service with ports: unless it must be reachable directly on a server interface." The reason: "A published host port bypasses domain-based proxy routing and can expose an internal service" (Coolify, Docker Compose).

The good news is that you almost never need it:

  • Between containers, the network is enough. Prometheus reads cAdvisor at cadvisor:8080 across the bridge, without any port being published. Seen from the internet, port 8080 doesn't exist.
  • For your visitors, the proxy handles it. On the app side, only 80 and 443 need to be published, and the proxy is the one holding them.
  • For you, when debugging, publish on the host's loopback only, "127.0.0.1:9090:9090" (Docker, Compose file reference, ports), then go through an SSH tunnel. The port exists, but only for someone already logged into the server.

Your VPS then becomes a small private town: the services talk quietly among themselves, and only a few well-guarded doors open onto the street.

The two-minute test

Log into your server and run:

Terminal
docker ps --format "table {{.Names}}\t{{.Ports}}"

Look at the PORTS column. Every entry that starts with 0.0.0.0: or [::]: is open to the world, UFW or not.

Don't panic about the ones that belong to Coolify itself: its dashboard publishes 8000, and 6001 and 6002 are used for real-time updates and the web terminal. Its docs explain that once the dashboard is served through a domain, behind the proxy, you can "close public access to ports 8000, 6001, and 6002", keeping 22, 80 and 443 open (Coolify, Firewall). That's set at the server level, not in your Compose file.

For all the others, the ones from your own services, ask yourself: does a human really need to reach this from a browser? If the answer is no, delete the ports: section, or bind it to 127.0.0.1 instead.

Next, to see who lives on the bridge:

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

If two services need to talk and they aren't both in that list (or in the same resource), you're probably looking at your next no such host.

What to remember

Situation

What to do

Two services in the same Compose file

Nothing: they reach each other by service name and container port.

An app looking for its database on localhost

Replace localhost with the service name (db).

A 502 or "No Available Server"

Make the app listen on 0.0.0.0, and check the port you gave the proxy.

Reaching a service installed on the server

host.docker.internal:host-gateway, and make the service listen on the Docker gateway address.

Two Coolify resources that need to talk

Connect both to the coolify network (external: true, or the "Connect to Predefined Network" checkbox), then check the real name.

A web app behind Coolify

Don't connect anything: the proxy joins the resource's network on its own.

The urge to open a port "just to test"

Don't write ports:. At most, 127.0.0.1:PORT:PORT and an SSH tunnel.

Since that evening, my house rule fits in one sentence:

Call each other by name, listen on 0.0.0.0, and only publish what a browser needs to see.

There's nothing magic about Docker networking. It's a map: islands, bedrooms, a boat and a wall. Once you know which island each service lives on, error messages go back to being what they were all along, perfectly honest sentences. Mine was simply saying "not here". It was right.

Sources


I'm Loïc Simon, a freelance web developer in Brittany, France. I take over, secure and document web apps that were left behind by their original developers, and I write about it at dev-relax.com. The quotes in this post link to the official documentation; the cAdvisor error and the CMS 502 come from my own deployments. Like the rest of my work, this post was written with help from an AI assistant, then reviewed and checked by me. Spotted a mistake? Tell me.