homelab-blueprint/docker-compose-files/vault

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

1. Create .env if it does not exist:

   cp -n .env.sample .env
   

2. Set the shared values in .env:

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

3. 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
   

4. 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
   

5. 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.