Gro 109 by aevesdocker · Pull Request #24961 · docker/docs

aevesdocker · 2026-05-05T12:14:17Z

Description

Compose networking refresh

Related issues or tickets

Reviews

Technical review
Editorial review
Product review

netlify · 2026-05-05T12:14:23Z

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	`9c75783`
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/69fb1b7d80b3e90008b2e1ba
😎 Deploy Preview	https://deploy-preview-24961--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

aevesdocker · 2026-05-05T12:21:53Z

/review

thaJeztah · 2026-05-05T12:23:25Z

+## Network drivers: bridge vs host

-## Link containers
+Compose supports multiple network drivers. The two most common are `bridge` and `host`.


I'm not sure if host is most common, and not sure if we should encourage users to use it; using host networking reduces the container's sandbox, and usually is reserved for expert use-cases where containers should not have a security boundary for networking.

Using host networking means that the container also won't have its own IP-address, and resolving containers won't be possible (as they share the host's IP-address.

I was keen to demonstrate network_mode here and took bridge and host as my examples. You're right to pick up on the most common. I have removed. I've re-framed the rest of the content too to focus on network_mode instead of comparing the drivers.

Ah, yeah, it's a tricky one; the "host" mode networking is really an expert use-case as it has many differences; unlike picking a different network-driver, host-mode means we completely disable the network namespace / network isolation of the container. It's useful for very specific situations, but for users not familiar with it (or aware of the wider consequences), it will be confusing.

Trying to think if we can find a different example, which could be a different network-driver, or if we want to keep it really basic none as networking (i.e., disable networking) to prevent going down the deep-end to explain the full network stack; https://docs.docker.com/engine/network/drivers/

We do have other driver (e.g. macvlan or ipvlan), but with those there's definitely a risk of going too much into depth on networking in general.

Perhaps @robmry has some ideas on some illustrative examples.

Yeh I think I'm leaning towards keeping it lighter with my new changes. We don't get a huge amount (if any) feedback on the lack of depth of the Compose network docs because we point to the Engine docs which are very comprehensive. I view this page as more of an entry point into networking

Yes, perhaps we should keep it simple for now, and indeed refer to the other docs for those that really need it. Of course we can revisit the if we come with a basic example to illustrate, but it may save us some headaches if users start to follow the example, then get back with questions.

thaJeztah · 2026-05-05T12:24:48Z

-    image: postgres:18
+    image: postgres:latest


Curious why this was switched to :latest (it's less maintenance, but not usually best-practice to use :latest - even more so for database containers, as updates to (in this case PostgreSQL) usually involves a migration step.

Yes this was a maintenance-related change. Also a consistency one - we do this quite a lot throughout the rest of docs. I personally think this is Ok for these non-normative examples

Yeah, it's a tricky balance; we should have a closer look at some of these; for the really "one-off" examples (just a docker run alpine / ubuntu / busybox), it's usually fine.

For other, more complete examples that users could use as a "template" / starting point for what they're doing, we should be more careful, and better to follow best practices.

I know we once had WordPress examples using mysql:latest and we had a ton of users that saw their stack break when MySQL moved :latest from v5 to something newer and their databases broke.

From a maintenance perspective for this specific case; postgres does a major version once per Year, and those are supported for 5 Years, so even if it's the previous major version, we would still have a good time window to update.

But we should look at either having some variables; we already have some for various versions (engine, alpine, etc); and we could probably automate some of these updates (or have Gordon do it for us);

docs/hugo.yaml

Lines 159 to 184 in 1414b91

docker_ce_version: "29.4.2"

# Previous version of the Docker Engine

# (Used to show e.g., "latest" and "latest"-1 in engine install examples

docker_ce_version_prev: "29.4.1"

# Latest Docker Compose version

compose_version: "v5.1.2"

# Latest BuildKit version

buildkit_version: "0.28.0"

# Latest actions version

bake_action_version: "v7"

build_push_action_version: "v7"

login_action_version: "v4"

metadata_action_version: "v6"

setup_buildx_action_version: "v4"

setup_compose_action_version: "v2"

setup_docker_action_version: "v5"

setup_qemu_action_version: "v4"

github_builder_version: "v1"

# Generic actions

checkout_action_version: "v6"

cache_action_version: "v5"

# Example runtime/library/os versions

example_go_version: "1.25"

example_alpine_version: "3.23"

example_node_version: "24"

docker-agent

Assessment: 🟡 NEEDS ATTENTION

akristen · 2026-05-07T14:33:54Z

-[network](/reference/cli/docker/network/create/) for your app. Each
-container for a service joins the default network and is both reachable by
-other containers on that network, and discoverable by the service's name.
+Compose handles networking for you by default, but gives you fine-grained control when you need it. This page explains how the default network works and how containers discover each other by name. It also covers when and how to define custom networks, choose between network drivers, connect services across separate Compose projects, map custom hostnames, and debug connectivity issues.


this is a great intro tbh

akristen · 2026-05-07T14:42:49Z

      - "8001:5432"
 ```

+Since `networks` is empty or absent from the Compose file, Compose automatically connects all services to the default network.


Can we reword "is empty or absent from the Compose file"? I can see this introducing ambiguity. Maybe something like, 'Compose automatically connects all services to the default network, so you don't need to define networks explicitly in the Compose file.'

akristen · 2026-05-07T14:44:53Z

+2. A container is created using `web`'s configuration. It joins `myapp_default` under the name `web`.
+3. A container is created using `db`'s configuration. It joins `myapp_default` under the name `db`.
+
+Each container can now look up the service name `web` or `db` and get back the appropriate container's IP address. The `web` service can connect to the database at `postgres://db:5432`. From the host machine, the same database is accessible at `postgres://localhost:8001` if your container is running locally.


this is really clear and good

akristen · 2026-05-07T14:47:05Z

-using the Postgres database.
+> [!TIP]
+>
+> Always reference services by name, not IP address. When containers are recreated, for example after a configuration change, they receive a new IP address. The service name stays stable.


So I understand this and it's clear why I'd use the service name, but I'm not understanding the why, for some reason. Is this an aspect of how docker handles networks? if i'm using network: host, would the IP address stay stable or does this rule still apply? (asking in case i'm missing something, or maybe it needs to be clearer in the content before the tip)

akristen · 2026-05-07T14:48:43Z

-`5432` (postgres default). Networked service-to-service
-communication uses the `CONTAINER_PORT`. When `HOST_PORT` is defined,
-the service is accessible outside the swarm as well.
+Your app's network is given a name based on the "project name", which is based on the name of the directory it lives in. You can override the project name with either the [`--project-name` flag](/reference/cli/docker/compose/) or the [`COMPOSE_PROJECT_NAME` environment variable](environment-variables/envvars.md#compose_project_name).


"Your app's network is given a name based on the "project name", which is based on the name of the directory it lives in."

Can we reword? Using 'based' twice is confusing. Do I read th is as the network is based on the project name, and the project name is based on the directory it lives in?

akristen · 2026-05-07T14:50:13Z

-Within the `web` container, your connection string to `db` would look like
-`postgres://db:5432`, and from the host machine, the connection string would
-look like `postgres://{DOCKER_IP}:8001` for example `postgres://localhost:8001` if your container is running locally.
+The `HOST_PORT` and `CONTAINER_PORT` serve different purposes. In the example above, for `db`, the `HOST_PORT` is `8001` and the container port is `5432` (the Postgres default). Networked service-to-service communication uses the `CONTAINER_PORT`. The host port is only used when accessing the service from outside the network.


ohhhhhhh. Is there a benefit to using two different ports? When I've done this, I usually use the same port for each (which I based off the sample compose file in registry.) this is mostly because i'm curious and maybe could be useful for other users

akristen · 2026-05-07T14:51:19Z

-  db:
-    image: postgres:18
-```
+You can override the networking mode on a per-service basis. `Network_mode` option accepts the following values:


Suggested change

You can override the networking mode on a per-service basis. `Network_mode` option accepts the following values:

You can override the networking mode on a per-service basis. `network_mode` option accepts the following values:

is yaml case sensitive? not sure what style guide suggests for variables leading in sentences

akristen · 2026-05-07T14:57:13Z

+  cache:
+    image: redis
+    networks:
+      - internal


The above paragraph defines networks: - internal without the true value, but in the example it's just internal. is true implied by virtue of defining networks as internal?

akristen · 2026-05-07T15:27:01Z

+  public: # Regular network connected to host
+```
+
+Note that a service connected to both an internal and a non-internal network (like `worker` above) can still reach the internet via the non-internal network `public`.


Do users need to define or configure public anywhere, or is it an "out of the box" feature (so to speak) that comes with default network

akristen · 2026-05-07T15:29:33Z

+  api:
+    image: myapi:latest
+    networks:
+      - shared


should it be shared-network instead of shared?

I see you use shared later on. What's the difference between the two, if any. lol maybe i'm missing something...

akristen · 2026-05-07T15:33:20Z

+      - "host.docker.internal:host-gateway"
+```
+
+On Linux, `host-gateway` resolves to the host's IP on the default bridge network. On Mac and Windows, Docker automatically provides this - `host-gateway` resolves to the same internal IP address as `host.docker.internal`.


Suggested change

On Linux, `host-gateway` resolves to the host's IP on the default bridge network. On Mac and Windows, Docker automatically provides this - `host-gateway` resolves to the same internal IP address as `host.docker.internal`.

On Linux, `host-gateway` resolves to the host's IP on the default bridge network. On Mac and Windows, Docker automatically resolves `host-gateway` to the same internal IP address as `host.docker.internal`.

maybe?

akristen · 2026-05-07T15:34:52Z

+
+## Link containers
+
+Links allow you to define extra aliases by which a service is reachable from another service. They are not required for basic service-to-service communication — by default, any service can reach any other service at that service's name. In the following example, `db` is reachable from `web` at both the hostnames `db` and `database`:


Suggested change

Links allow you to define extra aliases by which a service is reachable from another service. They are not required for basic service-to-service communication — by default, any service can reach any other service at that service's name. In the following example, `db` is reachable from `web` at both the hostnames `db` and `database`:

Links allow you to define extra aliases by which a service is reachable from another service. They are not required for basic service-to-service communication. By default, any service can reach any other service at that service's name. In the following example, `web` can reach `db` at both the hostnames `db` and `database`:

by all means keep the emdash lol but i think it can be separated into two distinct sentences

akristen

Made some small suggestions that are non-blocking and perhaps even obvious answers to our users. :) Overall I feel confident that I could do more advanced networking with what you have here. My only other thought:

Is it worth describing that you can test your network mode with the docker exec command? Maybe in a what's next section? I've found this helpful when I want to test that I've configured networks correctly.

aevesdocker added 2 commits April 28, 2026 13:28

gro-109

750e06b

edits

7dc0310

thaJeztah reviewed May 5, 2026

View reviewed changes

docker-agent Bot reviewed May 5, 2026

View reviewed changes

feedback

9c75783

akristen reviewed May 7, 2026

View reviewed changes

akristen approved these changes May 7, 2026

View reviewed changes

	docker_ce_version: "29.4.2"
	# Previous version of the Docker Engine
	# (Used to show e.g., "latest" and "latest"-1 in engine install examples
	docker_ce_version_prev: "29.4.1"
	# Latest Docker Compose version
	compose_version: "v5.1.2"
	# Latest BuildKit version
	buildkit_version: "0.28.0"
	# Latest actions version
	bake_action_version: "v7"
	build_push_action_version: "v7"
	login_action_version: "v4"
	metadata_action_version: "v6"
	setup_buildx_action_version: "v4"
	setup_compose_action_version: "v2"
	setup_docker_action_version: "v5"
	setup_qemu_action_version: "v4"
	github_builder_version: "v1"
	# Generic actions
	checkout_action_version: "v6"
	cache_action_version: "v5"

	# Example runtime/library/os versions
	example_go_version: "1.25"
	example_alpine_version: "3.23"
	example_node_version: "24"

	You can override the networking mode on a per-service basis. `Network_mode` option accepts the following values:
	You can override the networking mode on a per-service basis. `network_mode` option accepts the following values:

	On Linux, `host-gateway` resolves to the host's IP on the default bridge network. On Mac and Windows, Docker automatically provides this - `host-gateway` resolves to the same internal IP address as `host.docker.internal`.
	On Linux, `host-gateway` resolves to the host's IP on the default bridge network. On Mac and Windows, Docker automatically resolves `host-gateway` to the same internal IP address as `host.docker.internal`.


		## Link containers

		Links allow you to define extra aliases by which a service is reachable from another service. They are not required for basic service-to-service communication — by default, any service can reach any other service at that service's name. In the following example, `db` is reachable from `web` at both the hostnames `db` and `database`:

Conversation

aevesdocker commented May 5, 2026

Description

Related issues or tickets

Reviews

Uh oh!

netlify Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docsdocker ready!

Uh oh!

aevesdocker commented May 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

docker-agent Bot left a comment

Choose a reason for hiding this comment

Assessment: 🟡 NEEDS ATTENTION

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akristen May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akristen May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akristen May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akristen left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify Bot commented May 5, 2026 •

edited

Loading

akristen May 7, 2026 •

edited

Loading

akristen May 7, 2026 •

edited

Loading

akristen May 7, 2026 •

edited

Loading