Gro 109

[aevesdocker]

Description

Compose networking refresh

Related issues or tickets

Reviews

• Technical review
• Editorial review
• Product review

[netlify]

✅ 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]

/review

[thaJeztah]

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.

[aevesdocker]

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.

[thaJeztah]

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.

[aevesdocker]

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

[thaJeztah]

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]

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.

[aevesdocker]

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

[thaJeztah]

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