En

Using Vault#

Vault Initialization and Secret Migration#

1. Make sure the services are running#

# Vault in the configuration is started via an optional vault profile

# Copy the vault configuration (files are replaced with new ones)
cp -af ./vault/config/default/. ./vault/config

# Start the services with the selected DB profile + vault profile
# Option 1: MariaDB + Vault
docker compose --profile mariadb --profile vault up -d

# Option 2: PostgreSQL + Vault
docker compose --profile pg --profile vault up -d

2. Initialize and unseal Vault#

# Open a shell in the Vault container
docker compose exec orchestrator-vault sh

# Inside the container:
vault operator init
# save all keys after the command
vault operator unseal
exit

After unseal, you need to enable kv/ as KV v1.

# Open a shell in the Vault container (if you exited)
docker compose exec orchestrator-vault sh

# Inside the container:
# export the root token
export VAULT_TOKEN='your-root-token'

# Check mounts:
vault secrets list -detailed

# Enable KV v1 at the kv/ mount
vault secrets enable -path=kv -version=1 kv

# Verify that kv/ appears with map[version:1]
vault secrets list -detailed

exit
💡 Notes on Vault initialization

vault operator init - initializes Vault and outputs:

  • Unseal Key
  • Initial Root Token

vault operator unseal - unseals Vault (enter the Unseal Key 3 times from the init step)

3. Set the token in .env#

# Set the root token in the environment variable
sed -i 's/^VAULT_TOKEN=.*/VAULT_TOKEN=root-token/' .env

4. Restart orchestrator#

# Apply the new VAULT_TOKEN value
docker compose restart orchestrator

5. Migrate secrets to Vault#

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

(OPTIONAL) Reverse migration from Vault to DB (rollback)#

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

The script restores robot and asset passwords from Vault back to the DB and encrypts them using ORCHESTRATOR_ENCRYPTION_KEY.

💡 Rollback result verification
  • the command output should contain lines [OK] Robots: ... restored, ... failed and [OK] Assets: ... restored, ... failed
  • in the robots and assets tables, VAULT_MIGRATED values should be replaced with encrypted passwords
  • docker compose logs -f orchestrator should not contain Vault is not available errors
💡 Result verification
  • docker compose ps - the orchestrator and orchestrator-vault containers should be Up
  • docker compose logs -f orchestrator-vault - check Vault logs
  • docker compose logs -f orchestrator - verify that the backend started after restart without Vault errors