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 you'll find an example environment file.

When everything's ready start Nginx with Docker Compose, otherwise head down to 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}"'/docker-compose.yml'
export COMPOSE_OVERRIDE="${COMPOSE_DIR%/}"'/docker-compose.override.yml'
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. 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 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 where 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 docker-compose.yml 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 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.