From 70d03a93abb76ae164a5e56c5f6b4cd55678a56a Mon Sep 17 00:00:00 2001
From: Marcello Lamonaca <marcello@lamonaca.eu>
Date: Sun, 19 May 2024 10:58:06 +0200
Subject: [PATCH] docker: refine networking notes

---
 docs/containers/docker.md | 51 +++++++++++++++++++++------------------
 1 file changed, 27 insertions(+), 24 deletions(-)

diff --git a/docs/containers/docker.md b/docs/containers/docker.md
index f738a75..5886ab0 100644
--- a/docs/containers/docker.md
+++ b/docs/containers/docker.md
@@ -63,7 +63,7 @@ VMs incur a lot of overhead beyond what is being consumed by your application lo
 
 ### [`docker run`](https://docs.docker.com/engine/reference/commandline/run/)
 
-```sh linenums="1"
+```sh
 docker run <image>  # run selected app inside a container (downloaded from Docker Hub if missing from image)
 docker run -d|--detach <image>  # run docker container in the background (does not occupy stdout & stderr)
 docker run -i|--interactive <image>  # run docker container in interactive mode (read stdin)
@@ -80,7 +80,7 @@ docker run --name=<container_name> <image>  # set container name
 
 ### [`docker container`](https://docs.docker.com/engine/reference/commandline/container/)
 
-```sh linenums="1"
+```sh
 docker container ls  # list of currently running containers
 docker container ls -a|--all  # list of all containers, running and exited
 docker container rm <container>  # remove one or more containers
@@ -97,7 +97,7 @@ docker container exec <container> <command>  # exec a command inside a container
 
 ### [`docker image`](https://docs.docker.com/engine/reference/commandline/image/)
 
-```sh linenums="1"
+```sh
 docker image ls  # list of existing images
 docker image rm <image>  # remove one or more images
 docker image prune <image>  # remove unused images
@@ -106,20 +106,20 @@ docker image pull <image>  # download an image w/o starting the container
 
 ### [`docker build`](https://docs.docker.com/engine/reference/commandline/build/)
 
-```sh linenums="1"
+```sh
 docker build -t <tag> -f <dockerfile> <context>  # build image with specific tag (usually user/app:version)
 docker build -t <tag> -f <dockerfile> --build-arg ARG=value <context>  # pass args to ARG steps
 ```
 
 ### [`docker push`](https://docs.docker.com/engine/reference/commandline/push/)
 
-```sh linenums="1"
+```sh
 docker push <image>  # publish image to registry (defaults to Docker Hub)
 ```
 
 ## [Dockerfile](https://docs.docker.com/engine/reference/builder/)
 
-```docker linenums="1"
+```dockerfile
 # starting image or scratch
 FROM <base_image>:<tag>
 
@@ -160,7 +160,7 @@ With multi-stage builds, it's possible to use multiple `FROM` statements in the
 
 It's possible to selectively copy artifacts from one stage to another, leaving behind everything not wanted in the final image.
 
-```docker linenums="1"
+```dockerfile
 FROM <base_image>:<tag> AS <runtime_alias>
 RUN <command>  # install external dependencies (apt get ...)
 
@@ -186,7 +186,7 @@ COPY --from=<build_alias|stage_number> <src> <dir_in_container>
 CMD ["executable"]  # run app
 ```
 
-```docker linenums="1"
+```dockerfile
 FROM mcr.microsoft.com/dotnet/<runtime|aspnet>:<alpine_tag> AS runtime
 RUN <command>  # install external dependencies (apt get ...)
 
@@ -219,28 +219,28 @@ ENTRYPOINT ["dotnet", "<project>.dll"]
 
 Starting container networks: `bridge` (default), `none`, `host`.
 
-```sh linenums="1"
+```sh
 docker run <image> --network=none/host  # specify a non-default network to be used
+docker run <image> --add-host=<hostname>:<ip>  # add hostname mapping
 docker network ls  # list all available networks
 ```
 
-Bridge: Private internal network created by Docker. All containers ara attached to this network by default and get an IP in the `[172.17.xxx.xxx](http://172.12.xxx.xxx)` series.
-Containers can access each other by using the IP `172.17.0.1`. It is possible to create multiple sub-networks in the bridge network to isolate groups of containers from each other.
+- **Bridge**: Private internal network created by Docker.
+  All containers ara attached to this network by default and get an IP in the `172.17.xxx.xxx-172.12.xxx.xxx` series.  
+  Containers can access each other by using the IP `172.17.0.1`.  
+  It is possible to create multiple sub-networks in the bridge network to isolate groups of containers from each other.
+- **Host**: Removes any network isolation between the host and the containers. Cannot run multiple containers on the same port.
+- **None**: Containers are not attached to a network and cannot access other containers or the external network.
 
-Host: Removes any network isolation between the host and the containers. Cannot run multiple containers on the same port.
+> **Note**: Mapping `host-gateway` to an hostname allows the container to reach the host network even with networks types different from `host`
 
-None: Containers are not attached to a network and cannot access other containers or the external network.
+### User-defined Networks
 
-## User-defined Networks
-
-```sh linenums="1"
-docker network create \
-  --driver NETWORK_TYPE \
-  --subnet GATEWAY_TP/SUBNET_MASK_SIZE 
-  NETWORK_NAME
+```sh
+docker network create --driver NETWORK_TYPE --subnet GATEWAY_TP/SUBNET_MASK_SIZE NETWORK_NAME
 ```
 
-## Embedded DNS
+### Embedded DNS
 
 Docker has an internal DNS that allows finding other container by their name instead of their IP. The DNS always runs at the address `127.0.0.11`.
 
@@ -250,7 +250,7 @@ Docker has an internal DNS that allows finding other container by their name ins
 
 ## File System
 
-```sh linenums="1"
+```sh
 /var/lib/docker
 |_<storage_driver>
 |_containers
@@ -270,7 +270,7 @@ To modify a file during while the container runs docker creates a local copy in
 **volume mounting**: create a volume under the docker installation folder (`/var/lib/docker/volumes/`).
 **bind mounting**: link docker to an exiting folder to be used as a volume.
 
-```sh linenums="1"
+```sh
 docker run -v <existing_dir>:<container_dir> <image>:<tag>  # older command for bind mounting
 docker run --mount type=bind, source=:<existing_dir>, target=<container_dir> <image>:<tag>  # modern command for bind mounting
 ```
@@ -287,7 +287,7 @@ Using Compose is basically a three-step process:
 2. Define the services that make up your app in `docker-compose.yml` so they can be run together in an isolated environment.
 3. Run `docker-compose up` and Compose starts and runs the entire app.
 
-```yaml linenums="1"
+```yaml
 version: 3.x
 services:
   <service_name>:
@@ -302,6 +302,9 @@ services:
         - ARG=<value>
     ports: 
       - <host_port>:<container_port>
+    extra_hosts:  # add hostname mappings to container network interface config
+      - <hostname>:<ip>
+      - <hostname>:host-gateway  # map host machine network
     networks:  # attach container to one or more networks
       - <network_name>
     depends_on:  # make sure dependencies are running before this container