Description of EXPOSE instruction is unclear

[lorin]

Problem description

I can't figure out when I would ever need to EXPOSE a port. the docs say:

The EXPOSE instruction informs Docker that the container listens on the specified network ports at runtime.

But why do I need to inform Docker about which network ports a container will listen to at runtime? I apparently don't need to expose a port to publish it at runtime (or do I?). I also apparently don't need to expose a port to have Docker containers communicate over a Docker network (or do I?).

Apparently, it was once required for legacy Docker links, but those have been deprecated, so should this be deprecated? If not, why not?

Problem location

• I couldn't find the information I wanted. I expected to find it near the following URL: https://docs.docker.com/engine/reference/builder/#expose

Suggestions for a fix

As best as I can tell, the only real purpose EXPOSE has is to document in the Dockerfile which port the service is listening on. If that is the case, I would suggest something like:

Currently, the EXPOSE instruction's only purpose is to document in the Dockerfile which port the service will listen on. The instruction is also required for the deprecated legacy container links feature.

If that's not true, please clarify!

[unbreakableIce]

dibs for the hackathon

[mdlinville]

No action for two days, so this is up for grabs!

However, this may have been addressed by #2882

[clocklear]

@mstanleyjones looks as though #2882 does address this:

You expose ports using the EXPOSE keyword in the Dockerfile or the
--expose flag to docker run. Exposing ports is a way of documenting which
ports are used, but does not actually map or open any ports. Exposing ports
is optional.

noop?

[mdlinville]

Thanks @clocklear

[sarusso]

The doc here: https://docs.docker.com/engine/reference/builder/#expose is still very misleading. The sentence "Exposing ports is a way of documenting which ports are used, but does not actually map or open any ports. Exposing ports is optional." is very clear IMHO and should be put there. This issue should be re-opened...

[mdlinville]

@sarusso sorry, the doc you reference is actually sourced straight from the docker/cli repository so is you think that the file should be changed, the issue needs to be raised there.

@johndmulhausen can we re-fix it so that the "Report an issue" for these external topics goes to the right place again?

[sarusso]

@mstanleyjones is it? The readme of this repository states on the first line that "this is the source for https://docs.docker.com", which is the source of the document I referenced. Why this inconsistency then?

[mdlinville]

If you look in our repository you will see that we don't have the corresponding Markdown file in our repository at all. We fetch it as part of our build process (see the script). Also, if you look at the source of the file in the docker/cli repository, you will see the following comment:

<!-- This file is maintained within the docker/cli Github
     repository at https://github.com/docker/cli/. Make all
     pull requests against that repo. If you see this file in
     another repository, consider it read-only there, as it will
     periodically be overwritten by the definitive file. Pull
     requests which include edits to this file in other repositories
     will be rejected.
-->

[sarusso]

@mstanleyjones Look, I saw a issue with the doc, wanted to help/contribute, found this issue here (which was started as an issue referencing the same doc I did by the way), I double-checked on the readme if I were in the right place, and discovered after commenting that I was actually in the wrong one. I did not dig into the repo to triple-check, and I honestly don't think that it should have been my responsibility to do so. There is no need to prove me wrong, just take it as a feedback from a user (me): it is not clear.

[docker-robott]

Closed issues are locked after 30 days of inactivity.
This helps our team focus on active issues.

If you have found a problem that seems similar to this, please open a new issue.

/lifecycle locked