Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: refactor cli run reference #4615

Merged
merged 24 commits into from
Dec 13, 2023
Merged

docs: refactor cli run reference #4615

Changes from 1 commit
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
2f48f41
docs: improve introduction to docker run
dvdksn Oct 20, 2023
fad227d
docs: move info about fg/bg flags to run reference
dvdksn Oct 20, 2023
03dc883
docs: improve docs on container identification
dvdksn Nov 8, 2023
d66fe78
docs: move --pid to docker run reference
dvdksn Nov 22, 2023
ff62bf4
docs: move --uts to docker run reference
dvdksn Nov 22, 2023
5dd6e9a
docs: move --ipc to docker run reference
dvdksn Nov 22, 2023
7362097
docs: simplify container networking intro
dvdksn Nov 22, 2023
dbffa0d
docs: move --restart to docker run reference
dvdksn Nov 23, 2023
32189ca
docs: improve description about container exit codes
dvdksn Nov 23, 2023
f984444
docs: move --rm to docker run reference
dvdksn Nov 23, 2023
92c664b
docs: move info about --security-opt to docker run reference
dvdksn Nov 23, 2023
9e75a4c
docs: move --init to docker run reference
dvdksn Nov 23, 2023
72df196
docs: move --cgroup-parent to docker run reference
dvdksn Nov 23, 2023
4a6cde8
docs: move --log-driver to docker run reference
dvdksn Nov 23, 2023
c695ad9
docs: rewrite section on overriding image defaults
dvdksn Nov 23, 2023
b01e287
docs: rewrite section on default entrypoint
dvdksn Nov 27, 2023
3eeac20
docs: rewrite section on exposing ports
dvdksn Nov 27, 2023
7585d66
docs: rewrite section on overriding environment variables
dvdksn Nov 27, 2023
5ede4c8
docs: minor improvements to the healthcheck section
dvdksn Nov 27, 2023
52716c8
docs: move --tmpfs to docker run reference
dvdksn Nov 27, 2023
259aa90
docs: rewrite section on filesystem mounts
dvdksn Nov 27, 2023
4a84514
docs: rewrite section on setting user id
dvdksn Nov 27, 2023
2e394eb
docs: rewrite section on working directory
dvdksn Nov 28, 2023
f8dd8f0
docs: refresh --publish, add --publish-all
dvdksn Dec 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 32 additions & 11 deletions docs/reference/commandline/run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ Create and run a new container from an image
| `--platform` | `string` | | Set platform if server is multi-platform capable |
| [`--privileged`](#privileged) | | | Give extended privileges to this container |
| [`-p`](#publish), [`--publish`](#publish) | `list` | | Publish a container's port(s) to the host |
| `-P`, `--publish-all` | | | Publish all exposed ports to random ports |
| [`-P`](#publish-all), [`--publish-all`](#publish-all) | | | Publish all exposed ports to random ports |
| [`--pull`](#pull) | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) |
| `-q`, `--quiet` | | | Suppress the pull output |
| [`--read-only`](#read-only) | | | Mount the container's root filesystem as read only |
Expand Down Expand Up @@ -483,26 +483,47 @@ $ docker run -t -i --mount type=bind,src=/data,dst=/data busybox sh
### <a name="publish"></a> Publish or expose port (-p, --expose)

```console
$ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash
$ docker run -p 127.0.0.1:80:8080/tcp nginx:alpine
```

This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host
machine. You can also specify `udp` and `sctp` ports.
The [Docker User Guide](https://docs.docker.com/network/links/)
explains in detail how to use ports in Docker.
This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the
host. You can also specify `udp` and `sctp` ports. The [Networking overview
page](https://docs.docker.com/network/) explains in detail how to publish ports
with Docker.

Note that ports which are not bound to the host (i.e., `-p 80:80` instead of
`-p 127.0.0.1:80:80`) are externally accessible. This also applies if
you configured UFW to block this specific port, as Docker manages its
own iptables rules. [Read more](https://docs.docker.com/network/iptables/)
> **Note**
>
> If you don't specify an IP address (i.e., `-p 80:80` instead of `-p
> 127.0.0.1:80:80`) when publishing a container's ports, Docker publishes the
Comment on lines +496 to +497
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also for a follow-up; we need to make a pass at reviewing examples like this in light of IPv6 (i.e., both 127.0.0.x and ::1 becoming more relevant). /cc @akerouanton @robmry

> port on all interfaces (address `0.0.0.0`) by default. These ports are
> externally accessible. This also applies if you configured UFW to block this
> specific port, as Docker manages its own iptables rules. [Read
> more](https://docs.docker.com/network/packet-filtering-firewalls/)

```console
$ docker run --expose 80 ubuntu bash
$ docker run --expose 80 nginx:alpine
```

This exposes port `80` of the container without publishing the port to the host
system's interfaces.

### <a name="publish-all"></a> Publish all exposed ports (-P, --publish-all)

```console
$ docker run -P nginx:alpine
```

The `-P`, or `--publish-all`, flag publishes all the exposed ports to the host.
Docker binds each exposed port to a random port on the host.

The `-P` flag only publishes port numbers that are explicitly flagged as
exposed, either using the Dockerfile `EXPOSE` instruction or the `--expose`
flag for the `docker run` command.

The range of ports are within an *ephemeral port range* defined by
`/proc/sys/net/ipv4/ip_local_port_range`. Use the `-p` flag to explicitly map a
single port or range of ports.
Comment on lines +523 to +525
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Sorry for being picky on that one, but I know it's been troublesome in the past, so trying to preserve the information.

Related to that, I need to check with @akerouanton and @robmry what options we currently have to influence these; I know there's some ports used by Windows itself that are within the ephemeral port range, and I know there's been issues with Swarm services picking their own range(s).

Perhaps we need configuration options for this on the daemon (not just a "range", but also options to exclude range(s) or individual ports from being used).


### <a name="pull"></a> Set the pull policy (--pull)

Use the `--pull` flag to set the image pull policy when creating (and running)
Expand Down
Loading