Vault

Docker deployment for HashiCorp Vault. Run all commands from the repository root.

Persistent Data

Vault data and logs are stored in the Docker-managed named volumes vault_data and vault_logs. Host-managed configuration and TLS material remain read-only mounts from appdata/vault/config and appdata/vault/tls. Vault expects its configuration at appdata/vault/config/vault.hcl.

Existing deployments that store data and logs under appdata/vault must copy them into the named volumes before recreating the container.

Installation

Create .env if it does not exist:
```
cp -n .env.sample .env
```

Set the shared values in .env:

TZ=Africa/Johannesburg
DOCKERLOGGING_MAXFILE=3
DOCKERLOGGING_MAXSIZE=10m

Create appdata, provide a production-appropriate vault.hcl, and render the template:

mkdir -p appdata/vault/{config,tls}
./substitute_env.sh docker-compose-files/vault/template.yaml docker-compose.vault.yml .env

Validate and start Vault:

test -f appdata/vault/config/vault.hcl
docker compose -f docker-compose.vault.yml config --quiet
docker compose -f docker-compose.vault.yml up -d

Verify the container:

docker compose -f docker-compose.vault.yml ps
docker compose -f docker-compose.vault.yml logs --tail=100 vault

Apply Configuration Changes

./substitute_env.sh docker-compose-files/vault/template.yaml docker-compose.vault.yml .env
docker compose -f docker-compose.vault.yml up -d

Restart Vault after changing appdata/vault/config/vault.hcl.

Initial Setup

Initialize and unseal Vault according to your chosen storage and seal configuration. Store recovery material outside this repository.

Network Requirements

Vault listens on ports 8200 and 8201.
Restrict both ports to trusted networks.
Configure TLS in vault.hcl; the container expects HTTPS.

Troubleshooting

Check vault.hcl, TLS files, and container logs if Vault does not become healthy. The host-mounted config and TLS files must be readable by the container, but private keys should not be made world-readable.

Useful Commands

docker compose -f docker-compose.vault.yml exec vault vault status

Backup

Back up the vault_data and vault_logs named volumes plus appdata/vault/config and appdata/vault/tls, according to the storage backend configured in vault.hcl.

2.4 KiB Raw Blame History