Docs: Improve the usability and security of Docker on Unix

[FrancoisCapon]

Hello,

• Usability: the Docker container user is the same as the Docker host, so there are no longer any file permission issues

$ id -u ; id -g
1000
1000
...
$ ls -ltrn
total 12
-rw-r--r-- 1 1000 1000   19 sept.  1 10:53 mkdocs.yml
drwxr-xr-x 2 1000 1000 4096 sept.  1 10:54 docs
drwxr-xr-x 5 1000 1000 4096 sept.  1 10:54 site

• Security: by default, Docker publishes to 0.0.0.0, so the Docker host exposes the documentation to all other hosts

Important

Publishing container ports is insecure by default. Meaning, when you publish a container's ports it becomes available not only to the Docker host, but to the outside world as well.

If you include the localhost IP address (127.0.0.1, or ::1) with the publish flag, only the Docker host and its containers can access the published container port.

https://docs.docker.com/engine/network/#published-ports

$ ... -p 8000:8000 ...
$ ss -ltrn 
State           Recv-Q          Send-Q                    Local Address:Port                      Peer Address:Port          Process                                                        
LISTEN          0               4096                            0.0.0.0:8000                           0.0.0.0:*                                                     
LISTEN          0               4096                               [::]:8000                              [::]:* 
$ curl -I 192.168.1.30:8000
HTTP/1.0 200 OK
Date: Mon, 01 Sep 2025 09:46:27 GMT
Server: WSGIServer/0.2 CPython/3.11.13
Content-Type: text/html
Content-Length: 11125
$ curl -I localhost:8000 
HTTP/1.0 200 OK
Date: Mon, 01 Sep 2025 09:46:29 GMT
Server: WSGIServer/0.2 CPython/3.11.13
Content-Type: text/html
Content-Length: 11125

$ ... -p 127.0.0.1:8000:8000 ...
$ ss -ltrn 
State           Recv-Q          Send-Q                    Local Address:Port                      Peer Address:Port          Process                                                        
LISTEN          0               4096                            localhost:8000                           0.0.0.0:* 
$ curl -I 192.168.1.30:8000
curl: (7) Failed to connect to 192.168.1.30 port 8000 after 0 ms: Couldn't connect to server
$ curl -I localhost:8000 
HTTP/1.0 200 OK
Date: Mon, 01 Sep 2025 09:44:57 GMT
Server: WSGIServer/0.2 CPython/3.11.13
Content-Type: text/html
Content-Length: 11125                                               

[FrancoisCapon]

I added the docker documentation reference of the ports publication on the initial comment.

[squidfunk]

Thanks for the PR! Could you please elaborate a little more why the changes are necessary?

Please keep in mind that we want to keep the getting started guide as simple as possible, and this does not include having a hardened setup. The Docker image is only intended for previewing, not for production. Additionally, please understand that we're currently very busy with bigger picture topics, so this change has to wait for a bit.

[FrancoisCapon]

Thanks for your response.

• By default the docker container user is root so the files writes belong to root and the docker host user can not handle it, that's here that my students stop using the docker image!

  drwxr-xr-x 2 root root 4096 sept.  9 10:57 docs
  -rw-r--r-- 1 root root   19 sept.  9 10:57 mkdocs.ym
  

The Docker image is only intended for previewing, not for production.

• I know, but security by default is always the best policy. Your host can potentially exposed your "secret" documentation to other hosts (lan or bigger network) when all you need to do is add 127.0.0.1 to avoid that (docs.docker.com: Publishing container ports is insecure by default.)

• The command lines can be monoline if you think it's simpler I can change it

  docker run --rm -u $(id -u):$(id -g) -v $(pwd):/docs squidfunk/mkdocs-material new .
  docker run --rm -u $(id -u):$(id -g) -v $(pwd):/docs -p 127.0.0.1:8000:8000 squidfunk/mkdocs-material
  docker run --rm -u $(id -u):$(id -g) -v $(pwd):/docs -p 127.0.0.1:8000:8000 squidfunk/mkdocs-material build
  

Additionally, please understand that we're currently very busy with bigger picture topics, so this change has to wait for a bit.

Yes, I understand.

[squidfunk]

Thanks again for the PR and providing more information. I agree regarding security by default, and I wasn't aware that we can scope this to be less permissive. I thought exposing on 0.0.0.0 is the only thing that works. Does this also mean we can just use 127.0.0.1 in Docker, and map that through as well?

Please also read the comments, I have some minor remarks.

[squidfunk]

Could you explain why this change is necessary? It doesn't have anything to do with what you described in your PR.

[squidfunk]

Please format this as:

docker run --rm \
  ... (two spaces) \
  .... (and so on)

[squidfunk]

Why did you remove -it?

[squidfunk]

Please remove the comment, this is not necessary, as it's described in the paragraph above.

[squidfunk]

See above.

[squidfunk]

See above.