Using Vault#

Connecting Vault (internal and external)#

The project supports two configurations:

• Internal Vault: the orchestrator-vault container in the current docker-compose setup.
• External Vault: a separate Vault server or cluster outside compose.

The sequence is the same in both cases: configure env, start the services, then migrate and verify.

Common .env requirements#

Set at least the following values:

VAULT_ADDR=http://<vault-host>:8200
VAULT_TOKEN=<token-with-kv-access>
ORCHESTRATOR_ENCRYPTION_KEY=<your-encryption-key>

Requirements:

• VAULT_ADDR must be reachable from the orchestrator container.
• VAULT_TOKEN must have create/read/update/delete/list permissions for kv/*.
• ORCHESTRATOR_ENCRYPTION_KEY is required for rollback and encryption.
• The kv/ mount in Vault must use KV v2.

Option 1: internal Vault (docker compose profile)#

1. Configure .env#

VAULT_ADDR=http://orchestrator-vault:8200
VAULT_TOKEN=root-token
ORCHESTRATOR_ENCRYPTION_KEY=change_me

2. Start the services with the vault profile#

# MariaDB + Vault
docker compose --profile mariadb --profile vault up -d

# or PostgreSQL + Vault
docker compose --profile pg --profile vault up -d

3. Initialize and unseal Vault#

docker compose exec orchestrator-vault sh

# inside the container
vault operator init
vault operator unseal
exit

If kv/ was not created, enable it manually as KV v2:

docker compose exec orchestrator-vault sh

# inside the container
export VAULT_TOKEN='your-root-token'
vault secrets list -detailed
vault secrets enable -path=kv -version=2 kv
vault secrets list -detailed
exit

4. Apply settings to the backend#

After changing .env, the orchestrator container must be recreated. A normal restart does not apply new environment variables. Run the command from the installation directory during an agreed maintenance window: the backend will be briefly unavailable. The database and Vault services must already be running; --no-deps leaves them unchanged.

docker compose up -d --no-deps --force-recreate orchestrator

Option 2: external Vault (separate server or cluster)#

1. Configure .env#

VAULT_ADDR=https://vault.company.local:8200
VAULT_TOKEN=s.xxxxxxxx
ORCHESTRATOR_ENCRYPTION_KEY=change_me

2. Prepare the external Vault (once)#

Vault must be initialized and unsealed.

Check or enable kv/ as KV v2:

export VAULT_ADDR='https://vault.company.local:8200'
export VAULT_TOKEN='s.xxxxxxxx'

vault secrets list -detailed
vault secrets enable -path=kv -version=2 kv
vault secrets list -detailed

3. Start Orchestrator and apply settings#

After changing .env, the orchestrator container must be recreated. A normal restart does not apply new environment variables. Run the command from the installation directory during an agreed maintenance window: the backend will be briefly unavailable. The database and Vault services must already be running; --no-deps leaves them unchanged.

docker compose up -d --no-deps --force-recreate orchestrator

Migration and verification (both options)#

1. Check the Orchestrator logs#

docker compose logs -f orchestrator

The following errors should not appear:

• Vault is not available
• VAULT_TOKEN environment variable is required

2. Migrate secrets to Vault#

docker compose exec orchestrator php backend/bin/vault-migrate.php

Expected result:

• passwords in the DB are replaced with VAULT_MIGRATED;
• secrets are written to Vault under kv/orchestrator/....

3. Roll back from Vault to the DB (optional)#

# Option 1: directly
docker compose exec orchestrator php backend/bin/vault-rollback.php

# Option 2: using Makefile
make vault-rollback

Rollback restores values from Vault to the DB and encrypts them using ORCHESTRATOR_ENCRYPTION_KEY.

Common problems#