# Arke Vault Variables Documentation

This document lists the vault variables that need to be added to `ansible/inventory/group_vars/all/vault.yml` for the Arke deployment.

## Required Vault Variables

### Existing Variables
These should already be present in your vault:

```yaml
vault_arke_db_password: "your_secure_password"
vault_arke_ntth_tokens: '[{"app_id":"your_app_id","app_secret":"your_secret","name":"Production"}]'
```

### New Variables to Add

```yaml
# OpenAI-Compatible Embedding API Key (optional - can be empty string if not using OpenAI provider)
vault_arke_openai_embedding_api_key: ""
```

## Usage Notes

### vault_arke_openai_embedding_api_key
- **Required when**: `arke_embedding_provider` is set to `openai` in the inventory
- **Can be empty**: If using llama-cpp, LocalAI, or other services that don't require authentication
- **Must be set**: If using actual OpenAI API or services requiring authentication
- **Default in inventory**: Empty string (`""`)

### vault_arke_ntth_tokens
- **Format**: JSON array of objects
- **Required fields per object**: 
  - `app_id`: The application ID
  - `app_secret`: The application secret
  - `name`: (optional) A descriptive name for the token

**Example with multiple tokens**:
```yaml
vault_arke_ntth_tokens: '[{"app_id":"id1","app_secret":"secret1","name":"Production-Primary"},{"app_id":"id2","app_secret":"secret2","name":"Production-Backup"}]'
```

## Editing the Vault

To edit the vault file:

```bash
ansible-vault edit ansible/inventory/group_vars/all/vault.yml
```

Make sure you have the vault password available (stored in `ansible/.vault_pass` by default).

## Configuration Examples

### Using Ollama (Current Default)
No additional vault variables needed beyond the existing ones. The following inventory settings are used:

```yaml
arke_embedding_provider: ollama
arke_ollama_host: "pan.helu.ca"
```

### Using OpenAI API
Add to vault:
```yaml
vault_arke_openai_embedding_api_key: "sk-your-openai-api-key"
```

Update inventory to:
```yaml
arke_embedding_provider: openai
arke_openai_embedding_base_url: "https://api.openai.com"
arke_openai_embedding_model: "text-embedding-3-small"
```

### Using llama-cpp or LocalAI (No Auth Required)
Vault variable can remain empty:
```yaml
vault_arke_openai_embedding_api_key: ""
```

Update inventory to:
```yaml
arke_embedding_provider: openai
arke_openai_embedding_base_url: "http://your-server:8080"
arke_openai_embedding_model: "text-embedding-ada-002"
```

## Security Best Practices

1. Always use `ansible-vault` to encrypt sensitive data
2. Never commit unencrypted secrets to version control
3. Keep the vault password secure and separate from the repository
4. Rotate API keys and secrets regularly
5. Use unique tokens for different environments (dev/staging/production)