docs(docker-compose): In example dir layout focus on important files

docker-compose/examples/grafana/README.md

@@ -1,6 +1,10 @@
+# FIXME
+
+Search and replace all mentions of FIXME with sensible content in this file and in [docker-compose.yml](docker-compose.yml).
+
 # Grafana Docker Compose files
 
-Docker Compose files to spin up an instance of Grafana.
+Docker Compose files to spin up an instance of Grafana FIXME capitalization FIXME.
 
 # How to run
 
@@ -24,6 +28,25 @@ On your deployment machine create the necessary Docker context to connect to and
 docker context create fully.qualified.domain.name --docker 'host=ssh://root@fully.qualified.domain.name'
 ```
 
+## Pull
+
+Pull images from Docker Hub verbatim.
+
+```
+docker compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --env-file "${COMPOSE_ENV}" --profile 'full' pull
+```
+
+## Copy to target
+
+Copy images to target Docker host, that is assuming you deploy to a machine that itself has no network route to reach Docker Hub. Copying in its simplest form involves a local `docker save` and a remote `docker load`. Consider the helper mini-project [quico.space/Quico/copy-docker](https://quico.space/Quico/copy-docker) where [copy-docker.sh](https://quico.space/Quico/copy-docker/src/branch/main/copy-docker.sh) allows the following workflow:
+
+```
+source "${COMPOSE_ENV}"
+for image in 'grafana:'"${GRAFANA_VERSION}" 'nginx:'"${NGINX_VERSION}"; do
+    copy-docker.sh "${image}" fully.qualified.domain.name
+done
+```
+
 ## Start
 
 ```
@@ -52,7 +75,7 @@ Create ZFS datasets and set permissions as needed.
     zfs create -p 'zpool/docker-data/grafana-'"${COMPOSE_CTX}"'/nginx/data/logs'
     zfs create -p 'zpool/docker-data/grafana-'"${COMPOSE_CTX}"'/nginx/config'
     ```
-    When changing bind mount locations to real ones remember to also update `volumes:` in [docker-compose.yml](docker-compose.yml).
+    FIXME delete when all is done FIXME When changing bind mount locations to real ones remember to also update `volumes:` in [docker-compose.yml](docker-compose.yml).
 
 * Create subdirs
     ```
@@ -68,20 +91,22 @@ Create ZFS datasets and set permissions as needed.
 
 Place the following files on target server. Use the directory structure at [build-context](build-context) as a guide, specifically at `docker-data`.
 
+FIXME Add details about files that aren't self-explanatory FIXME
+
 ```
 build-context/
 ├── grafana
 │   ├── docker-data
 │   |   └── config
 │   │       └── grafana.cfg
-│   ├── Dockerfile
-│   └── extras
+│   ├── ...
+│   └── ...
 └── nginx
     ├── docker-data
     |   └── config
     │       └── nginx.cfg
-    ├── Dockerfile
-    └── extras
+    ├── ...
+    └── ...
 ```
 
 When done head back up to [How to run](#how-to-run).

docker-compose/examples/grafana/docker-compose.yml

@@ -1,5 +1,6 @@
 services:
     grafana:
+        # FIXME Docker Hub image name with or without slash? FIXME
         image: "grafana:${GRAFANA_VERSION}"
         container_name: "grafana-grafana-${CONTEXT}"
         networks:
@@ -28,6 +29,7 @@ services:
             # GRAFANA_USER: ${GRAFANA_USER}
             # GRAFANA_PASSWORD: ${GRAFANA_PASSWORD}
     nginx:
+        # FIXME Docker Hub image name with or without slash? FIXME
         image: "nginx:${NGINX_VERSION}"
         container_name: "grafana-nginx-${CONTEXT}"
         networks:

docker-compose/examples/hashicorpvault/README.md

@@ -1,6 +1,10 @@
+# FIXME
+
+Search and replace all mentions of FIXME with sensible content in this file and in [docker-compose.yml](docker-compose.yml).
+
 # Vault Docker Compose files
 
-Docker Compose files to spin up an instance of Vault.
+Docker Compose files to spin up an instance of Vault FIXME capitalization FIXME.
 
 # How to run
 
@@ -18,12 +22,6 @@ export COMPOSE_OVERRIDE="${COMPOSE_DIR%/}"'/docker-compose.override.yml'
 export COMPOSE_ENV=<add accordingly>
 ```
 
-## Build
-
-```
-docker compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --file "${COMPOSE_OVERRIDE}" --env-file "${COMPOSE_ENV}" --profile 'build' build
-```
-
 ## Context
 
 On your deployment machine create the necessary Docker context to connect to and control the Docker daemon on whatever target host you'll be using, for example:
@@ -31,6 +29,30 @@ On your deployment machine create the necessary Docker context to connect to and
 docker context create fully.qualified.domain.name --docker 'host=ssh://root@fully.qualified.domain.name'
 ```
 
+## Build
+FIXME We build the `vault` image locally. Our adjustment to the official image is simply adding `/tmp/vault` to it. See [build-context/vault/Dockerfile](build-context/vault/Dockerfile). We use `/tmp/vault` to bind-mount a dedicated ZFS dataset for the application's `tmpdir` location.
+
+```
+docker compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --file "${COMPOSE_OVERRIDE}" --env-file "${COMPOSE_ENV}" --profile 'build-vault' build
+```
+
+## Pull
+
+FIXME Rewrite either [Build](#build) or this paragraph for which images are built and which ones pulled, `--profile 'full'` may not make sense FIXME Pull images from Docker Hub verbatim.
+
+```
+docker compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --env-file "${COMPOSE_ENV}" --profile 'full' pull
+```
+
+## Copy to target
+
+Copy images to target Docker host, that is assuming you deploy to a machine that itself has no network route to reach Docker Hub. Copying in its simplest form involves a local `docker save` and a remote `docker load`. Consider the helper mini-project [quico.space/Quico/copy-docker](https://quico.space/Quico/copy-docker) where [copy-docker.sh](https://quico.space/Quico/copy-docker/src/branch/main/copy-docker.sh) allows the following workflow:
+
+```
+source "${COMPOSE_ENV}"
+copy-docker.sh 'vault':"${VAULT_VERSION}" fully.qualified.domain.name
+```
+
 ## Start
 
 ```
@@ -56,7 +78,7 @@ Create ZFS datasets and set permissions as needed.
     zfs create -p 'zpool/docker-data/vault-'"${COMPOSE_CTX}"'/vault/data/logs'
     zfs create -p 'zpool/docker-data/vault-'"${COMPOSE_CTX}"'/vault/config'
     ```
-    When changing bind mount locations to real ones remember to also update `volumes:` in [docker-compose.yml](docker-compose.yml).
+    FIXME delete when all is done FIXME When changing bind mount locations to real ones remember to also update `volumes:` in [docker-compose.yml](docker-compose.yml).
 
 * Create subdirs
     ```
@@ -72,13 +94,15 @@ Create ZFS datasets and set permissions as needed.
 
 Place the following files on target server. Use the directory structure at [build-context](build-context) as a guide, specifically at `docker-data`.
 
+FIXME Add details about files that aren't self-explanatory FIXME
+
 ```
 build-context/
 ├── docker-data
 │   └── config
 │       └── vault.cfg
-├── Dockerfile
-└── extras
+├── ...
+└── ...
 ```
 
 When done head back up to [How to run](#how-to-run).

docker-compose/examples/hashicorpvault/docker-compose.yml

@@ -1,5 +1,6 @@
 services:
     vault:
+        # FIXME Docker Hub image name with or without slash? FIXME
         image: "vault:${VAULT_VERSION}"
         container_name: "vault-${CONTEXT}"
         networks:

docker-compose/{{ cookiecutter.__project_slug }}/README.md

@@ -1,6 +1,10 @@
+# FIXME
+
+Search and replace all mentions of FIXME with sensible content in this file and in [docker-compose.yml](docker-compose.yml).
+
 # {{ cookiecutter.__service_slug.capitalize() }} Docker Compose files
 
-Docker Compose files to spin up an instance of {{ cookiecutter.__service_slug.capitalize() }}.
+Docker Compose files to spin up an instance of {{ cookiecutter.__service_slug.capitalize() }} FIXME capitalization FIXME.
 
 # How to run
 
@@ -18,15 +22,6 @@ export COMPOSE_OVERRIDE="${COMPOSE_DIR%/}"'/docker-compose.override.yml'{% endif
 export COMPOSE_ENV=<add accordingly>
 ```
 
-{%- if cookiecutter.build == "yes" %}
-
-## Build
-
-```
-docker compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --file "${COMPOSE_OVERRIDE}" --env-file "${COMPOSE_ENV}" --profile 'build' build
-```
-{%- endif %}
-
 ## Context
 
 On your deployment machine create the necessary Docker context to connect to and control the Docker daemon on whatever target host you'll be using, for example:
@@ -34,6 +29,46 @@ On your deployment machine create the necessary Docker context to connect to and
 docker context create fully.qualified.domain.name --docker 'host=ssh://root@fully.qualified.domain.name'
 ```
 
+{%- if cookiecutter.build == "yes" %}
+
+## Build
+
+{%- set components = cookiecutter.__component_list_slug.split(',') -%}
+{% for component in components %}
+{%- if loop.first %}
+FIXME We build the `{{ cookiecutter.__service_slug }}` image locally. Our adjustment to the official image is simply adding `/tmp/{{ cookiecutter.__service_slug }}` to it. See [build-context/{{ cookiecutter.__service_slug }}/Dockerfile](build-context/{{ cookiecutter.__service_slug }}/Dockerfile). We use `/tmp/{{ cookiecutter.__service_slug }}` to bind-mount a dedicated ZFS dataset for the application's `tmpdir` location.
+
+```
+docker compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --file "${COMPOSE_OVERRIDE}" --env-file "${COMPOSE_ENV}" --profile 'build-{{ cookiecutter.__service_slug }}' build
+```
+{%- endif %}
+{%- endfor %}
+{%- endif %}
+
+## Pull
+
+{% if cookiecutter.build == "yes" %}FIXME Rewrite either [Build](#build) or this paragraph for which images are built and which ones pulled, `--profile 'full'` may not make sense FIXME {% endif %}Pull images from Docker Hub verbatim.
+
+```
+docker compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --env-file "${COMPOSE_ENV}" --profile 'full' pull
+```
+
+## Copy to target
+
+Copy images to target Docker host, that is assuming you deploy to a machine that itself has no network route to reach Docker Hub. Copying in its simplest form involves a local `docker save` and a remote `docker load`. Consider the helper mini-project [quico.space/Quico/copy-docker](https://quico.space/Quico/copy-docker) where [copy-docker.sh](https://quico.space/Quico/copy-docker/src/branch/main/copy-docker.sh) allows the following workflow:
+
+```
+source "${COMPOSE_ENV}"
+{%- set components = cookiecutter.__component_list_slug.split(',') -%}
+{%- if ',' in cookiecutter.__component_list_slug %}
+for image in{% for component in components %} '{{ component }}:'"${% raw %}{{% endraw %}{{ component.upper() }}_VERSION{% raw %}}{% endraw %}"{%- endfor %}; do
+    copy-docker.sh "${image}" fully.qualified.domain.name
+done
+{%- else %}
+copy-docker.sh '{{ cookiecutter.__component_list_slug }}':"${% raw %}{{% endraw %}{{ cookiecutter.__component_list_slug.upper() }}_VERSION{% raw %}}{% endraw %}" fully.qualified.domain.name
+{%- endif %}
+```
+
 ## Start
 
 ```
@@ -72,7 +107,7 @@ Create ZFS datasets and set permissions as needed.
     zfs create -p 'zpool/docker-data/{{ cookiecutter.__service_slug }}-'"${COMPOSE_CTX}"'/{{ cookiecutter.__service_slug }}/config'
 {%- endif %}
     ```
-    When changing bind mount locations to real ones remember to also update `volumes:` in [docker-compose.yml](docker-compose.yml).
+    FIXME delete when all is done FIXME When changing bind mount locations to real ones remember to also update `volumes:` in [docker-compose.yml](docker-compose.yml).
 
 * Create subdirs
     ```
@@ -98,6 +133,8 @@ Create ZFS datasets and set permissions as needed.
 
 Place the following files on target server. Use the directory structure at [build-context](build-context) as a guide, specifically at `docker-data`.
 
+FIXME Add details about files that aren't self-explanatory FIXME
+
 ```
 build-context/
 {%- if ',' in cookiecutter.__component_list_slug -%}
@@ -108,23 +145,23 @@ build-context/
 │   ├── docker-data
 │   |   └── config
 │   │       └── {{ component }}.cfg
-│   ├── Dockerfile
-│   └── extras
+│   ├── ...
+│   └── ...
 {%- else %}
 └── {{ component }}
     ├── docker-data
     |   └── config
     │       └── {{ component }}.cfg
-    ├── Dockerfile
-    └── extras
+    ├── ...
+    └── ...
 {%- endif %}
 {%- endfor %}
 {%- else %}
 ├── docker-data
 │   └── config
 │       └── {{ cookiecutter.__service_slug }}.cfg
-├── Dockerfile
-└── extras
+├── ...
+└── ...
 {%- endif %}
 ```
 

docker-compose/{{ cookiecutter.__project_slug }}/docker-compose.yml

@@ -12,6 +12,7 @@ services:
 {%- endfor -%}
 {%- for component in components %}
     {{ component }}:
+        # FIXME Docker Hub image name with or without slash? FIXME
         image: "{{ component }}:${% raw %}{{% endraw %}{{ component.upper() }}_VERSION{% raw %}}{% endraw %}"
         container_name: "{{ cookiecutter.__service_slug }}-{{ component }}-${CONTEXT}"
         networks:
@@ -51,6 +52,7 @@ services:
 {%- endfor -%}
 {%- else %}
     {{ cookiecutter.__component_list_slug }}:
+        # FIXME Docker Hub image name with or without slash? FIXME
         image: "{{ cookiecutter.__component_list_slug }}:${% raw %}{{% endraw %}{{ cookiecutter.__component_list_slug.upper() }}_VERSION{% raw %}}{% endraw %}"
         container_name: "{{ cookiecutter.__service_slug }}-${CONTEXT}"
         networks: