# Using Vault

## Vault Initialization and Secret Migration

### 1. Make sure the services are running

```bash
# 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

```bash
# 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`.

```bash
# 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
```

<details>

<summary>💡 Notes on Vault initialization</summary>

**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)

</details>

### 3. Set the token in .env

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

### 4. Restart orchestrator

```bash
# Apply the new VAULT_TOKEN value
docker compose restart orchestrator
```

### 5. Migrate secrets to Vault

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

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

```bash
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`.

<details>

<summary>💡 Rollback result verification</summary>

* 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

</details>

<details>

<summary>💡 Result verification</summary>

* `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

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sherparpa.ru/en/sherpa-rpa/sherpa-orchestrator/ustanovka-sherpa-orchestrator/s-ispolzovaniem-docker/ispolzovanie-vault.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.