py-cookiecutter-templates/docker-compose/examples/hashicorpvault/README.md

FIXME

Search and replace all mentions of FIXME with sensible content in this file and in compose.yaml.

Vault Docker Compose files

Docker Compose files to spin up an instance of Vault FIXME capitalization FIXME.

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

When everything's ready start Vault with Docker Compose, otherwise head down to Initial setup first.

Environment

export COMPOSE_DIR='/opt/containers/hashicorpvault'
export COMPOSE_CTX='ux_vilnius'
export COMPOSE_PROJECT='vault-'"${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

Skip to Pull if you already have images in your private registry ready to use. Otherwise read on to build them now.

FIXME We build the vault image locally. Our adjustment to the official image is simply adding /tmp/vault to it. See build-context/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' build

Push

Push to Docker Hub or your private registry. Setting up a private registry is out of scope of this repo.

source "${COMPOSE_ENV}"
docker push "registry.example.com/project/vault:${VAULT_BUILD_DATE}-${VAULT_VERSION}"

Pull

Skip this step if you just built images that still exist locally on your build host.

FIXME Rewrite either Build or this paragraph for which images are built and which ones pulled, --profile 'full' may not make sense.

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 or your private registry of choice. 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
copy-docker 'vault:'"${VAULT_VERSION}" fully.qualified.domain.name

Start

docker --context 'fully.qualified.domain.name' 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'
  

  FIXME When changing bind mount locations to real ones remember to also update volumes: in compose.yaml FIXME

• Create subdirs

  mkdir -p '/opt/docker-data/vault-'"${COMPOSE_CTX}"'/vault/'{'.ssh','config','data','projects'}
  

• Change ownership

  chown -R 1000:1000 '/opt/docker-data/vault-'"${COMPOSE_CTX}"'/vault/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/
├── docker-data
│   └── config
│       └── vault.cfg
├── ...
└── ...

When done head back up to How to run.

Development

Conventional commits

This project uses Conventional Commits 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:

• vault: A change to how the vault 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.