From 984f650c6b0b77c49d3dba8577c6acd11318407f Mon Sep 17 00:00:00 2001 From: yvanzo Date: Thu, 26 May 2022 10:49:42 +0100 Subject: [PATCH 1/3] Use --expose instead of EXPOSE for optional ports The idea is to prevent false positives when listing containers: https://github.com/metabrainz/guidelines/pull/18#discussion_r858967135 Changes originally submitted by @alastair at: https://github.com/metabrainz/guidelines/pull/18#discussion_r863882982 --- Docker.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Docker.md b/Docker.md index e103762..66374fd 100644 --- a/Docker.md +++ b/Docker.md @@ -4,7 +4,9 @@ When building an image that is running some services, use the [`EXPOSE` directive](https://docs.docker.com/engine/reference/builder/#expose), -to document which ports the services are listening to. +to document which ports the services are listening to. If the image will be used to run many +containers, some of which don't listen on a port, instead use the `expose` option in +`docker-compose.yml` or the `--expose` flag to `docker run`. Some tools ([such as the nginx proxy companion](https://github.com/nginx-proxy/acme-companion#step-3---proxied-containers)) use it to define a contract between different containers too. Not using this directive doesn’t prevent exposing those ports to the Docker network. From de72171df5bce28bce4ef077491457bc8b1176b4 Mon Sep 17 00:00:00 2001 From: yvanzo Date: Thu, 26 May 2022 10:59:20 +0100 Subject: [PATCH 2/3] Narrow the conditions to use EXPOSE directive To follow the previous commit, it makes explicit that only mandatory ports should be exposed through the EXPOSE directive, so as to avoid false positives when listing containers. --- Docker.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Docker.md b/Docker.md index 66374fd..5747857 100644 --- a/Docker.md +++ b/Docker.md @@ -2,9 +2,10 @@ ## `Dockerfile` -When building an image that is running some services, -use the [`EXPOSE` directive](https://docs.docker.com/engine/reference/builder/#expose), -to document which ports the services are listening to. If the image will be used to run many +When building an image that will be run by one (or many) container(s) providing (the same) services, +use the [`EXPOSE` directive](https://docs.docker.com/engine/reference/builder/#expose) +with mandatory ports only, +to document which ports the services are necessarily listening to. If the image will be used to run many containers, some of which don't listen on a port, instead use the `expose` option in `docker-compose.yml` or the `--expose` flag to `docker run`. Some tools ([such as the nginx proxy companion](https://github.com/nginx-proxy/acme-companion#step-3---proxied-containers)) From 4c3103c64b067cfd36baf33b2c98ee6c049cea97 Mon Sep 17 00:00:00 2001 From: yvanzo Date: Thu, 26 May 2022 11:01:28 +0100 Subject: [PATCH 3/3] Refer to the below section for expose in Compose --- Docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Docker.md b/Docker.md index 5747857..2ceaba3 100644 --- a/Docker.md +++ b/Docker.md @@ -7,7 +7,7 @@ use the [`EXPOSE` directive](https://docs.docker.com/engine/reference/builder/#e with mandatory ports only, to document which ports the services are necessarily listening to. If the image will be used to run many containers, some of which don't listen on a port, instead use the `expose` option in -`docker-compose.yml` or the `--expose` flag to `docker run`. +`docker-compose.yml` (see the below section for details) or the `--expose` flag to `docker run`. Some tools ([such as the nginx proxy companion](https://github.com/nginx-proxy/acme-companion#step-3---proxied-containers)) use it to define a contract between different containers too. Not using this directive doesn’t prevent exposing those ports to the Docker network.