docs: refactor cli run reference #4615

dvdksn · 2023-10-20T14:39:42Z

- What I did

Improving & consolidating the docker run reference instructions.

docs/reference/run.md

Make this a conceptual/introductory page for understanding how docker run works, and the different options at a very high level.
docs/reference/commandline/run.md

Make this the canonical page for looking up the different flags/options for the docker run command.

network: add container networking intro from docker run reference docs#18753

- How I did it

- How to verify it

- Description for the changelog

- A picture of a cute animal (not mandatory but encouraged)

docs/reference/run.md

thaJeztah

just some quick comments

docs/reference/run.md

codecov-commenter · 2023-11-23T14:49:29Z

Codecov Report

Merging #4615 (f8dd8f0) into master (4dd5c23) will decrease coverage by 0.09%.
Report is 11 commits behind head on master.
The diff coverage is n/a.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4615      +/-   ##
==========================================
- Coverage   59.77%   59.68%   -0.09%     
==========================================
  Files         287      287              
  Lines       24830    24865      +35     
==========================================
  Hits        14841    14841              
- Misses       9103     9138      +35     
  Partials      886      886

thaJeztah

I'm gonna take a break for a bit; I looked at commits until "docs: rewrite section on overriding image defaults"

Most comments are probably for follow-ups, but some could be part of this PR (for some follow-ups we may want to create tracking tickets)

docs/reference/run.md

thaJeztah · 2023-11-28T11:46:12Z

docs/reference/run.md

+```console
+$ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...]
+```


Not sure if this gets removed in a later commit, and not a show-stopper in any way, but it just occurred to me that this "usage" output may add to the confusion around docker run reference vs run (command) reference, as both outline the USAGE

docs/reference/run.md

thaJeztah · 2023-11-28T13:31:31Z

docs/reference/commandline/run.md

+The default init process used is the first `docker-init` executable found in the
+system path of the Docker daemon process. This `docker-init` binary, included in
+the default installation, is backed by [tini](https://github.com/krallin/tini).
+


For a follow-up; I think the init-binary to use is configurable on the daemon (if so, we may need a link to that part of the daemon config)

thaJeztah · 2023-11-28T13:33:30Z

docs/reference/commandline/run.md

+## <a name="cgroup-parent"></a> Specify custom cgroups
+
+Using the `--cgroup-parent` flag, you can pass a specific cgroup to run a
+container in. This allows you to create and manage cgroups on their own. You can
+define custom resources for those cgroups and put containers under a common
+parent group.


For a follow-up; this section may need a rewrite (but it's pretty-much "power-user" area). There's some (not so) subtle issues with group-parent when using cgroups v2, besides currently this section doesn't describe at all how to use it 😞 (We may have a tracking issue for that somewhere, but not sure if it's still open)

docs/reference/commandline/run.md

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

Create an easier to digest introduction to container networking, move the bulk of information to the networking overview page. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs/reference/run.md

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

thaJeztah

LGTM!!

docs/reference/commandline/run.md

thaJeztah · 2023-12-13T11:32:11Z

docs/reference/run.md

+Docker supports two main categories of mounts:
+
+- Volume mounts
+- Bind mounts


Related to my previous comment. Looks like this section is not as complete as https://docs.docker.com/storage/, and misses at least the tmpfs mounts.

yeah I didn't intend to make everything on this page exhaustive; it could put us back where this page started. My thinking is:

General information here

All the details in the reference docs

docs/reference/run.md

thaJeztah · 2023-12-13T11:43:02Z

docs/reference/commandline/run.md

+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.


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).

thaJeztah · 2023-12-13T11:44:34Z

docs/reference/commandline/run.md

+> 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


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

dvdksn commented Oct 20, 2023

View reviewed changes

docs/reference/run.md Outdated Show resolved Hide resolved

thaJeztah reviewed Nov 6, 2023

View reviewed changes

docs/reference/run.md Outdated Show resolved Hide resolved

docs/reference/run.md Show resolved Hide resolved

docs/reference/run.md Outdated Show resolved Hide resolved

dvdksn force-pushed the docs-cli-reference-refresh branch 2 times, most recently from b59f6d1 to 0d1582e Compare November 7, 2023 12:00

dvdksn mentioned this pull request Nov 22, 2023

network: add container networking intro from docker run reference docker/docs#18753

Merged

dvdksn force-pushed the docs-cli-reference-refresh branch from 22e4d2b to d06e3a7 Compare November 23, 2023 12:59

dvdksn self-assigned this Nov 23, 2023

dvdksn added the kind/docs label Nov 23, 2023

dvdksn force-pushed the docs-cli-reference-refresh branch 2 times, most recently from 1dfbda9 to 43dda63 Compare November 28, 2023 10:27

dvdksn marked this pull request as ready for review November 28, 2023 10:27

dvdksn requested a review from thaJeztah November 28, 2023 10:29

thaJeztah added this to the 25.0.0 milestone Nov 28, 2023

thaJeztah reviewed Nov 28, 2023

View reviewed changes

dvdksn force-pushed the docs-cli-reference-refresh branch 3 times, most recently from ad6338d to 01dbbf0 Compare November 29, 2023 12:10

dvdksn requested a review from thaJeztah November 29, 2023 12:10

dvdksn added 11 commits December 11, 2023 22:17

docs: improve introduction to docker run

2f48f41

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: move info about fg/bg flags to run reference

fad227d

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: improve docs on container identification

03dc883

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: move --pid to docker run reference

d66fe78

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: move --uts to docker run reference

ff62bf4

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: move --ipc to docker run reference

5dd6e9a

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: simplify container networking intro

7362097

Create an easier to digest introduction to container networking, move the bulk of information to the networking overview page. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: move --restart to docker run reference

dbffa0d

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: improve description about container exit codes

32189ca

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: move --rm to docker run reference

f984444

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: move info about --security-opt to docker run reference

92c664b

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

dvdksn added 5 commits December 11, 2023 22:17

docs: move --init to docker run reference

9e75a4c

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: move --cgroup-parent to docker run reference

72df196

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: move --log-driver to docker run reference

4a6cde8

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: rewrite section on overriding image defaults

c695ad9

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: rewrite section on default entrypoint

b01e287

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

dvdksn force-pushed the docs-cli-reference-refresh branch from 01dbbf0 to 99072a2 Compare December 11, 2023 21:19

thaJeztah reviewed Dec 11, 2023

View reviewed changes

docs/reference/run.md Show resolved Hide resolved

docs/reference/run.md Outdated Show resolved Hide resolved

docs/reference/run.md Show resolved Hide resolved

docs/reference/run.md Show resolved Hide resolved

docs/reference/run.md Outdated Show resolved Hide resolved

dvdksn added 7 commits December 12, 2023 10:44

docs: rewrite section on exposing ports

3eeac20

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: rewrite section on overriding environment variables

7585d66

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: minor improvements to the healthcheck section

5ede4c8

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: move --tmpfs to docker run reference

52716c8

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: rewrite section on filesystem mounts

259aa90

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: rewrite section on setting user id

4a84514

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs: rewrite section on working directory

2e394eb

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

dvdksn force-pushed the docs-cli-reference-refresh branch from 99072a2 to 2e394eb Compare December 12, 2023 09:45

dvdksn requested a review from thaJeztah December 12, 2023 09:45

docs: refresh --publish, add --publish-all

f8dd8f0

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

thaJeztah approved these changes Dec 13, 2023

View reviewed changes

thaJeztah merged commit 103840e into docker:master Dec 13, 2023
76 checks passed

dvdksn deleted the docs-cli-reference-refresh branch December 13, 2023 12:17

dvdksn mentioned this pull request Dec 13, 2023

docs: editorial improvements, typo fixes #4712

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: refactor cli run reference #4615

docs: refactor cli run reference #4615

dvdksn commented Oct 20, 2023 •

edited

Loading

thaJeztah left a comment

codecov-commenter commented Nov 23, 2023 •

edited

Loading

thaJeztah left a comment

thaJeztah Nov 28, 2023

thaJeztah Nov 28, 2023

thaJeztah Nov 28, 2023

thaJeztah left a comment

thaJeztah Dec 13, 2023

dvdksn Dec 13, 2023

thaJeztah Dec 13, 2023

thaJeztah Dec 13, 2023

		> 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

docs: refactor cli run reference #4615

docs: refactor cli run reference #4615

Conversation

dvdksn commented Oct 20, 2023 • edited Loading

thaJeztah left a comment

Choose a reason for hiding this comment

codecov-commenter commented Nov 23, 2023 • edited Loading

Codecov Report

thaJeztah left a comment

Choose a reason for hiding this comment

thaJeztah Nov 28, 2023

Choose a reason for hiding this comment

thaJeztah Nov 28, 2023

Choose a reason for hiding this comment

thaJeztah Nov 28, 2023

Choose a reason for hiding this comment

thaJeztah left a comment

Choose a reason for hiding this comment

thaJeztah Dec 13, 2023

Choose a reason for hiding this comment

dvdksn Dec 13, 2023

Choose a reason for hiding this comment

thaJeztah Dec 13, 2023

Choose a reason for hiding this comment

thaJeztah Dec 13, 2023

Choose a reason for hiding this comment

dvdksn commented Oct 20, 2023 •

edited

Loading

codecov-commenter commented Nov 23, 2023 •

edited

Loading