Robert Helewka
b4d60f2f38
Replaces the minimal project description with a comprehensive README including a component overview table, quick start instructions, common Ansible operations, and links to detailed documentation. Aligns with Red Panda Approval™ standards.
95 lines
2.7 KiB
Markdown
95 lines
2.7 KiB
Markdown
# 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)
|