ouranos/docs/arke.md

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:

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

# 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:

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:

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:

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

Using OpenAI API

Add to vault:

vault_arke_openai_embedding_api_key: "sk-your-openai-api-key"

Update inventory to:

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:

vault_arke_openai_embedding_api_key: ""

Update inventory to:

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)