docs(docker-compose): Add example README Markdown file

docker-compose/examples/grafana/README.md

@@ -0,0 +1,55 @@
+# Grafana Docker Compose files
+
+Docker Compose files to spin up an instance of Grafana.
+
+# How to run
+
+Add a `COMPOSE_ENV` file and save its location as a shell variable along with the location where this repo lives, here for example `/opt/containers/grafana` plus all other variables. At [env/fqdn_context.env.example](env/fqdn_context.env.example) you'll find an example environment file.
+
+When everything's ready start Grafana with Docker Compose, otherwise head down to [Initial setup](#initial-setup) first.
+
+## Environment
+```
+export COMPOSE_DIR='/opt/containers/grafana'
+export COMPOSE_CTX='cncf'
+export COMPOSE_PROJECT='grafana-'"${COMPOSE_CTX}"
+export COMPOSE_FILE="${COMPOSE_DIR}"'/docker-compose.yml'
+export COMPOSE_ENV=<add accordingly>
+```
+
+## Start
+
+```
+docker compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --env-file "${COMPOSE_ENV}" --profile 'full' up --detach
+```
+
+# Initial setup
+
+We're assuming you run Docker Compose workloads with ZFS-based bind mounts. ZFS management, creating a zpool and setting adequate properties for its datasets is out of scope of this document.
+
+## Datasets
+
+Create ZFS datasets and set permissions as needed.
+
+* Parent dateset
+    ```
+    zfs create -o mountpoint=/opt/docker-data 'zpool/docker-data'
+    ```
+
+* Container-specific datasets
+    ```
+    zfs create -p 'zpool/docker-data/grafana-${COMPOSE_CTX}/grafana/data/db'
+    zfs create -p 'zpool/docker-data/grafana-${COMPOSE_CTX}/grafana/data/logs'
+    zfs create -p 'zpool/docker-data/grafana-${COMPOSE_CTX}/grafana/config'
+    zfs create -p 'zpool/docker-data/grafana-${COMPOSE_CTX}/nginx/data/db'
+    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).
+
+* Change ownership
+    ```
+    chown -R 1000:1000 '/opt/docker-data/grafana-${COMPOSE_CTX}/grafana/data'
+    ```
+
+When done head back up to [How to run](#how-to-run).

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

@@ -14,6 +14,8 @@ services:
         ports:
             # - "8080:80"
         volumes:
+            # When changing bind mount locations to real ones remember to
+            # also update "Initial setup" section in README.md.
             # - /opt/docker-data/grafana-${CONTEXT}/grafana/data/db:/usr/lib/grafana
             # - /opt/docker-data/grafana-${CONTEXT}/grafana/data/logs:/var/log/grafana
             # - /opt/docker-data/grafana-${CONTEXT}/grafana/config:/etc/grafana
@@ -38,6 +40,8 @@ services:
         ports:
             # - "8080:80"
         volumes:
+            # When changing bind mount locations to real ones remember to
+            # also update "Initial setup" section in README.md.
             # - /opt/docker-data/grafana-${CONTEXT}/nginx/data/db:/usr/lib/nginx
             # - /opt/docker-data/grafana-${CONTEXT}/nginx/data/logs:/var/log/nginx
             # - /opt/docker-data/grafana-${CONTEXT}/nginx/config:/etc/nginx

docker-compose/examples/hashicorpvault/README.md

@@ -0,0 +1,59 @@
+# Vault Docker Compose files
+
+Docker Compose files to spin up an instance of Vault.
+
+# How to run
+
+Add a `COMPOSE_ENV` file and save its location as a shell variable along with the location where this repo lives, here for example `/opt/containers/hashicorpvault` plus all other variables. At [env/fqdn_context.env.example](env/fqdn_context.env.example) you'll find an example environment file.
+
+When everything's ready start Vault with Docker Compose, otherwise head down to [Initial setup](#initial-setup) first.
+
+## Environment
+```
+export COMPOSE_DIR='/opt/containers/hashicorpvault'
+export COMPOSE_CTX='fsf'
+export COMPOSE_PROJECT='vault-'"${COMPOSE_CTX}"
+export COMPOSE_FILE="${COMPOSE_DIR}"'/docker-compose.yml'
+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
+```
+
+## Start
+
+```
+docker compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --env-file "${COMPOSE_ENV}" up --detach
+```
+
+# Initial setup
+
+We're assuming you run Docker Compose workloads with ZFS-based bind mounts. ZFS management, creating a zpool and setting adequate properties for its datasets is out of scope of this document.
+
+## Datasets
+
+Create ZFS datasets and set permissions as needed.
+
+* Parent dateset
+    ```
+    zfs create -o mountpoint=/opt/docker-data 'zpool/docker-data'
+    ```
+
+* Container-specific datasets
+    ```
+    zfs create -p 'zpool/docker-data/vault-${COMPOSE_CTX}/vault/data/db'
+    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).
+
+* Change ownership
+    ```
+    chown -R 1000:1000 '/opt/docker-data/vault-${COMPOSE_CTX}/vault/data'
+    ```
+
+When done head back up to [How to run](#how-to-run).

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

@@ -10,9 +10,11 @@ services:
         ports:
             # - "8080:80"
         volumes:
-            # - /opt/docker-data/vault-${CONTEXT}/data/db:/usr/lib/vault
+            # When changing bind mount locations to real ones remember to
-            # - /opt/docker-data/vault-${CONTEXT}/data/logs:/var/log/vault
+            # also update "Initial setup" section in README.md.
-            # - /opt/docker-data/vault-${CONTEXT}/config:/etc/vault
+            # - /opt/docker-data/vault-${CONTEXT}/vault/data/db:/usr/lib/vault
+            # - /opt/docker-data/vault-${CONTEXT}/vault/data/logs:/var/log/vault
+            # - /opt/docker-data/vault-${CONTEXT}/vault/config:/etc/vault
         environment:
             # VAULT_USER: ${VAULT_USER}
             # VAULT_PASSWORD: ${VAULT_PASSWORD}