feat(meta): Use modern file names (#1)

README.md

@@ -1,2 +1,151 @@
-# nginx
+# FIXME
 
+Search and replace all mentions of FIXME with sensible content in this file and in [compose.yaml](compose.yaml).
+
+# Nginx Docker Compose files
+
+Docker Compose files to spin up an instance of Nginx.
+
+Nginx comes with an optional sidecar container we're calling `ping` whose purpose is to do health checks. If you want Nginx to bind to a specific virtual IP address you're going to want to use `ping`, it will quite literally ping the virtual IP address for you and report a successful health check once the address becomes reachable. Only then will Nginx start up. Management on your Docker host of a virtual IP address can happen via `iproute2`/`ip addr add`, `keepalived` or similar mechanisms and is out of scope of this repository.
+
+Feel free to run Nginx without `ping` if you have no need for a virtual IP address. Continue reading for details on how to start with and without the `ping` sidecar container.
+
+# 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/nginx` 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 Nginx with Docker Compose, otherwise head down to [Initial setup](#initial-setup) first.
+
+## Environment
+
+```
+export COMPOSE_DIR='/opt/containers/nginx'
+export COMPOSE_CTX='ux_vilnius'
+export COMPOSE_PROJECT='nginx-'"${COMPOSE_CTX}"
+export COMPOSE_FILE="${COMPOSE_DIR}"'/compose.yaml'
+export COMPOSE_OVERRIDE="${COMPOSE_DIR%/}"'/compose.override.yaml'
+export COMPOSE_ENV=<add accordingly>
+```
+
+## 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:
+```
+docker context create fully.qualified.domain.name --docker 'host=ssh://root@fully.qualified.domain.name'
+```
+
+## Build
+
+FIXME We build the `nginx` image locally. Our adjustment to the official image is simply adding `/tmp/nginx` to it. See [build-context/nginx/Dockerfile](build-context/nginx/Dockerfile). We use `/tmp/nginx` 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-nginx' 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}"
+# FIXME Docker Hub image name with or without slash? FIXME
+for image in 'nginx:'"${NGINX_VERSION}" 'ping:'"${PING_VERSION}"; do
+    copy-docker.sh "${image}" fully.qualified.domain.name
+done
+```
+
+## Start
+
+```
+docker --context 'fully.qualified.domain.name' 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/nginx-'"${COMPOSE_CTX}"'/nginx/data/db'
+    zfs create -p 'zpool/docker-data/nginx-'"${COMPOSE_CTX}"'/nginx/data/logs'
+    zfs create -p 'zpool/docker-data/nginx-'"${COMPOSE_CTX}"'/nginx/config'
+    zfs create -p 'zpool/docker-data/nginx-'"${COMPOSE_CTX}"'/ping/data/db'
+    zfs create -p 'zpool/docker-data/nginx-'"${COMPOSE_CTX}"'/ping/data/logs'
+    zfs create -p 'zpool/docker-data/nginx-'"${COMPOSE_CTX}"'/ping/config'
+    ```
+    FIXME When changing bind mount locations to real ones remember to also update `volumes:` in [compose.yaml](compose.yaml) FIXME
+
+* Create subdirs
+    ```
+    mkdir -p '/opt/docker-data/nginx-'"${COMPOSE_CTX}"'/nginx/'{'.ssh','config','data','projects'}
+    ```
+
+* Change ownership
+    ```
+    chown -R 1000:1000 '/opt/docker-data/nginx-${COMPOSE_CTX}/nginx/data/'{*,.*}
+    ```
+
+## Additional files
+
+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/
+├── nginx
+│   ├── docker-data
+│   |   └── config
+│   │       └── nginx.cfg
+│   ├── ...
+│   └── ...
+└── ping
+    ├── docker-data
+    |   └── config
+    │       └── ping.cfg
+    ├── ...
+    └── ...
+```
+
+When done head back up to [How to run](#how-to-run).
+
+# Development
+
+## Conventional commits
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) for its commit messages.
+
+### Commit types
+
+Commit _types_ besides `fix` and `feat` are:
+
+- `refactor`: Keeping functionality while streamlining or otherwise improving function flow
+- `docs`: Documentation for project or components
+
+### Commit scopes
+
+The following _scopes_ are known for this project. A Conventional Commits commit message may optionally use one of the following scopes or none:
+
+- `nginx`: A change to how the `nginx` service component works
+- `ping`: A change to how the `ping` service component works
+- `build`: Build-related changes such as `Dockerfile` fixes and features.
+- `mount`: Volume or bind mount-related changes.
+- `net`: Networking, IP addressing, routing changes
+- `meta`: Affects the project's repo layout, file names etc.

build-context/nginx/Dockerfile

@@ -0,0 +1,14 @@
+# For the remainder of this Dockerfile EXAMPLE_ARG_FOR_DOCKERFILE will be
+# available with a value of 'must_be_available_in_dockerfile', check out the env
+# file at 'env/fully.qualified.domain.name.example' for reference.
+# ARG EXAMPLE_ARG_FOR_DOCKERFILE
+
+# Another env var, this one's needed in the example build step below:
+# ARG NGINX_VERSION
+
+# Example
+# FROM "nginx:${NGINX_VERSION}"
+# RUN apt-get update && \
+#     apt-get -y install \
+#     somepackage-6.q16-6-extra && \
+#     rm -rf /var/lib/apt/lists/*

build-context/ping/Dockerfile

@@ -0,0 +1,14 @@
+# For the remainder of this Dockerfile EXAMPLE_ARG_FOR_DOCKERFILE will be
+# available with a value of 'must_be_available_in_dockerfile', check out the env
+# file at 'env/fully.qualified.domain.name.example' for reference.
+# ARG EXAMPLE_ARG_FOR_DOCKERFILE
+
+# Another env var, this one's needed in the example build step below:
+# ARG PING_VERSION
+
+# Example
+# FROM "ping:${PING_VERSION}"
+# RUN apt-get update && \
+#     apt-get -y install \
+#     somepackage-6.q16-6-extra && \
+#     rm -rf /var/lib/apt/lists/*

common-settings.yml

@@ -0,0 +1,11 @@
+services:
+    common-settings:
+        environment:
+            TZ: "${TIMEZONE:-Etc/UTC}"
+        logging:
+            driver: "json-file"
+            options:
+                max-size: "10m"
+                max-file: "10"
+                compress: "true"
+        restart: "${RESTARTPOLICY:-unless-stopped}"

compose.override.yaml

@@ -0,0 +1,19 @@
+services:
+    nginx-build:
+        image: "nginx:${NGINX_VERSION}"
+        profiles: ["build", "build-nginx"]
+        build:
+            context: "build-context/nginx"
+            dockerfile: Dockerfile
+            args:
+                EXAMPLE_ARG_FOR_DOCKERFILE: "${EXAMPLE_ARG_FROM_ENV_FILE}"
+                NGINX_VERSION: "${NGINX_VERSION}"
+    ping-build:
+        image: "ping:${PING_VERSION}"
+        profiles: ["build", "build-ping"]
+        build:
+            context: "build-context/ping"
+            dockerfile: Dockerfile
+            args:
+                EXAMPLE_ARG_FOR_DOCKERFILE: "${EXAMPLE_ARG_FROM_ENV_FILE}"
+                PING_VERSION: "${PING_VERSION}"

compose.yaml

@@ -0,0 +1,72 @@
+services:
+    nginx:
+        # FIXME Docker Hub image name with or without slash? FIXME
+        image: "nginx:${NGINX_VERSION}"
+        container_name: "nginx-nginx-${CONTEXT}"
+        networks:
+            nginx-default:
+        profiles: ["full", "nginx"]
+        depends_on:
+            ping:
+                condition: service_healthy
+        ulimits:
+            nproc: ${ULIMIT_NPROC-65535}
+            nofile:
+                soft: ${ULIMIT_NPROC-65535}
+                hard: ${ULIMIT_NPROC-65535}
+        extends:
+            file: common-settings.yml
+            service: common-settings
+        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/nginx-${CONTEXT}/nginx/data/db:/usr/lib/nginx
+            # - /opt/docker-data/nginx-${CONTEXT}/nginx/data/logs:/var/log/nginx
+            # - /opt/docker-data/nginx-${CONTEXT}/nginx/config:/etc/nginx
+        environment:
+            # NGINX_USER: ${NGINX_USER}
+            # NGINX_PASSWORD: ${NGINX_PASSWORD}
+    ping:
+        # FIXME Docker Hub image name with or without slash? FIXME
+        image: "ping:${PING_VERSION}"
+        container_name: "nginx-ping-${CONTEXT}"
+        networks:
+            nginx-default:
+        profiles: ["full", "ping"]
+        healthcheck:
+            test: ["CMD", "fping", "--count=1", "${NGINX_VIP}", "--period=500", "--quiet"]
+            interval: 3s
+            timeout: 1s
+            retries: 60
+            start_period: 2s
+        ulimits:
+            nproc: ${ULIMIT_NPROC-65535}
+            nofile:
+                soft: ${ULIMIT_NPROC-65535}
+                hard: ${ULIMIT_NPROC-65535}
+        extends:
+            file: common-settings.yml
+            service: common-settings
+        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/nginx-${CONTEXT}/ping/data/db:/usr/lib/ping
+            # - /opt/docker-data/nginx-${CONTEXT}/ping/data/logs:/var/log/ping
+            # - /opt/docker-data/nginx-${CONTEXT}/ping/config:/etc/ping
+        environment:
+            # PING_USER: ${PING_USER}
+            # PING_PASSWORD: ${PING_PASSWORD}
+networks:
+    nginx-default:
+        name: nginx-${CONTEXT}
+        driver: bridge
+        driver_opts:
+            com.docker.network.enable_ipv6: "false"
+        ipam:
+            driver: default
+            config:
+                - subnet: ${SUBNET}

env/fqdn_context.env.example

@@ -0,0 +1,33 @@
+CONTEXT=ux_vilnius
+
+
+
+# Set something sensible here and uncomment
+# ---
+# NGINX_VERSION=x.y.z
+# PING_VERSION=x.y.z
+# NGINX_VIP=10.1.1.2
+
+
+
+# Feel free to leave defaults. They apply while these vars are commented out
+# ---
+# RESTARTPOLICY=unless-stopped
+# TIMEZONE=Etc/UTC
+
+
+
+# Subnet to use for this Docker Compose project. Docker defaults to
+# container networks in prefix 172.16.0.0/12 which is 1 million addresses in
+# the range from 172.16.0.0 to 172.31.255.255. Docker uses 172.17.0.0/16 for
+# itself. Use any sensible prefix in 172.16.0.0/12 here except for Docker's
+# own 172.17.0.0/16.
+# ---
+SUBNET=172.30.95.0/24
+
+
+
+# See 'compose.override.yaml' for how to make a variable available in
+# a Dockerfile
+# ---
+# EXAMPLE_ARG_FROM_ENV_FILE=must_be_available_in_dockerfile