Oracle Cloud Vault Integration

Overview

Oracle Cloud Vault is a managed service for storing and retrieving secrets (API keys, passwords, certificates). This guide shows how to:

Store your secrets in OCI Vault
Retrieve them at runtime on your Oracle Cloud instance
Remove the need to copy .env files to your server

Prerequisites

Oracle Cloud account with access to OCI Vault
Oracle Cloud Infrastructure CLI (OCI CLI) installed on your server
Existing Oracle Cloud compute instance running your EchOS deployment

Step 1: Create a Vault (One-time Setup)

Via OCI Console

Log in to Oracle Cloud Console
Navigate to Identity & Security → Vault
Select your Compartment (or create a new one)
Click Create Vault
- Name: echos-vault
- Click Create Vault

Via OCI CLI (Optional)

# Create vault
oci vault vault create --compartment-id <YOUR_COMPARTMENT_OCID> --display-name "echos-vault" --vault-type DEFAULT

# Get vault OCID (note the id from output)
oci vault vault list --compartment-id <YOUR_COMPARTMENT_OCID> --all

Step 2: Create Secrets

Create a secret for each sensitive value:

Via OCI Console

Go to your vault → Secrets
Click Create Secret
Fill in:
- Name: echos-telegram-bot-token
- Secret Contents: Your Telegram bot token
- Encryption Key: Use the default key or create one
Repeat for:
- echos-anthropic-api-key
- echos-allowed-user-ids
- echos-openai-api-key (if used)

Via OCI CLI

# Get your vault OCID
VAULT_OCID=$(oci vault vault list --compartment-id <YOUR_COMPARTMENT_OCID> --query "data[0].id" --raw-output)

# Get the master encryption key OCID
KEY_OCID=$(oci vault key list --compartment-id <YOUR_COMPARTMENT_OCID> --vault-id $VAULT_OCID --query "data[0].id" --raw-output)

# Create secrets
oci vault secret create-base64 \
  --compartment-id <YOUR_COMPARTMENT_OCID> \
  --vault-id $VAULT_OCID \
  --encryption-key-id $KEY_OCID \
  --secret-name "echos-telegram-bot-token" \
  --secret-contents "$(echo -n 'YOUR_TELEGRAM_BOT_TOKEN' | base64)"

oci vault secret create-base64 \
  --compartment-id <YOUR_COMPARTMENT_OCID> \
  --vault-id $VAULT_OCID \
  --encryption-key-id $KEY_OCID \
  --secret-name "echos-anthropic-api-key" \
  --secret-contents "$(echo -n 'YOUR_ANTHROPIC_API_KEY' | base64)"

oci vault secret create-base64 \
  --compartment-id <YOUR_COMPARTMENT_OCID> \
  --vault-id $VAULT_OCID \
  --encryption-key-id $KEY_OCID \
  --secret-name "echos-allowed-user-ids" \
  --secret-contents "$(echo -n 'YOUR_USER_IDS' | base64)"

Step 3: Set Up OCI CLI on Your Server

Install OCI CLI

# SSH to your Oracle Cloud instance
ssh your-server

# Install OCI CLI
bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"

Configure OCI CLI

# Configure with your credentials
oci setup config

# This will prompt for:
# - User OCID: Get from Oracle Cloud Console → User Settings → OCID
# - Tenancy OCID: Get from Oracle Cloud Console → Tenancy Details
# - Region: Your region (e.g., uk-london-1)
# - Enter path to PEM private key: /home/opc/.oci/oci_api_key.pem

Authenticate

The OCI CLI can authenticate using Instance Principal (recommended for compute instances):

# Enable instance principal authentication
oci auth instance-principal auth invoke --all-verbs --resource-type all --secret-name "test" 2>&1 || true

# If you get a permission error, you need to add a policy (see Step 4)

Step 4: Grant Access to Secrets (IAM Policy)

Create an IAM policy to allow your compute instance to read secrets:

Via OCI Console

Go to Identity & Security → Policies
Select your compartment
Click Create Policy
Configure:
- Name: echos-vault-access
- Policy Versioning: Static
- Policy Statements:

Allow dynamic-group <YOUR_INSTANCE_DYNAMIC_GROUP> to read secret-family in compartment <YOUR_COMPARTMENT_NAME>

You may need to create a Dynamic Group for your compute instance: go to Identity & Security → Dynamic Groups and create: All instances in compartment <YOUR_COMPARTMENT_NAME>.

Via OCI CLI

# Create dynamic group
oci iam dynamic-group create \
  --compartment-id <YOUR_COMPARTMENT_OCID> \
  --matching-rule 'Any {instance.compartment.id = "<YOUR_COMPARTMENT_OCID>"}' \
  --description "EchOS compute instances" \
  --display-name "echos-instances"

# Create policy
oci iam policy create \
  --compartment-id <YOUR_COMPARTMENT_OCID> \
  --name "echos-vault-access" \
  --description "Allow EchOS instances to read vault secrets" \
  --statements '["Allow dynamic-group echos-instances to read secret-family in compartment id <YOUR_COMPARTMENT_OCID>"]'

Step 5: Create a Secret Retrieval Script

Create a script on your server to fetch secrets at startup:

# SSH to your Oracle Cloud instance
ssh your-server

# Create the secret fetcher script
mkdir -p ~/echos/scripts
cat > ~/echos/scripts/fetch-secrets.sh << 'EOF'
#!/bin/bash
set -e

# Configuration
VAULT_SECRET_NAMES=(
  "echos-telegram-bot-token"
  "echos-anthropic-api-key"
  "echos-allowed-user-ids"
  "echos-openai-api-key"
)

SECRETS_DIR="/home/opc/echos/secrets"
mkdir -p "$SECRETS_DIR"

echo "Fetching secrets from OCI Vault..."

for secret_name in "${VAULT_SECRET_NAMES[@]}"; do
  # Try to get secret, skip if doesn't exist
  secret_content=$(oci vault secret get-secret-content \
    --secret-name "$secret_name" \
    2>/dev/null | head -1) || continue
  
  if [ -n "$secret_content" ]; then
    # Convert to env variable format
    env_name=$(echo "$secret_name" | sed 's/echos-//' | tr '[:lower:]' '[:upper:]')
    echo "${env_name}=${secret_content}" > "$SECRETS_DIR/${secret_name}.env"
    echo "✓ Retrieved: $secret_name"
  fi
done

# Generate combined .env file
> "$SECRETS_DIR/.env"
for file in "$SECRETS_DIR"/*.env; do
  [ -f "$file" ] && cat "$file" >> "$SECRETS_DIR/.env"
done

echo "✓ Secrets saved to $SECRETS_DIR/.env"
EOF

chmod +x ~/echos/scripts/fetch-secrets.sh

Step 6: Modify Docker Compose

Update your docker-compose.yml to use the secrets:

services:
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  echos:
    image: echos:latest
    restart: unless-stopped
    depends_on:
      redis:
        condition: service_healthy
    env_file:
      - /home/opc/echos/secrets/.env
    environment:
      - REDIS_URL=redis://redis:6379
      - NODE_ENV=production
    volumes:
      - ../data/knowledge:/app/data/knowledge
      - ../data/db:/app/data/db
      - ../data/sessions:/app/data/sessions
    ports:
      - "${WEB_PORT:-3000}:3000"

volumes:
  redis-data:

Step 7: Update Deployment Script

Modify scripts/deploy-fast.sh to:

Remove the .env file upload
Add a step to fetch secrets on the server before starting

# In your deploy script, after loading the Docker image but before docker compose up,
# add this SSH command:

# Fetch secrets from Oracle Cloud Vault
ssh your-server << 'EOF'
cd ~/echos
./scripts/fetch-secrets.sh
EOF

Step 8: Test the Setup

# SSH to your server
ssh your-server

# Fetch secrets manually
~/echos/scripts/fetch-secrets.sh

# Verify secrets exist
cat ~/echos/secrets/.env

# Restart the container
cd ~/echos/docker
docker compose restart echos

# Check logs
docker compose logs echos

Updating Secrets

When you need to update a secret (e.g., rotate API key):

Via OCI Console

Go to Vault → Secrets
Click on the secret
Click Create New Version
Enter the new value

Via OCI CLI

# Get secret OCID
SECRET_OCID=$(oci vault secret list \
  --compartment-id <YOUR_COMPARTMENT_OCID> \
  --vault-id $VAULT_OCID \
  --query "data[?\"display-name\"]=='echos-anthropic-api-key'.id" \
  --raw-output)

# Create new version
oci vault secret create-base64 \
  --secret-id $SECRET_OCID \
  --secret-contents "$(echo -n 'NEW_API_KEY' | base64)"

After updating, restart your container:

ssh your-server '~/echos/scripts/fetch-secrets.sh && cd ~/echos/docker && docker compose restart echos'

Troubleshooting

”Permission denied” when reading secrets

Verify the IAM policy is correctly applied
Check your dynamic group matches your instance
Ensure the vault and secrets are in the same compartment as the policy

OCI CLI not authenticated

# Verify authentication
oci iam region list

# If using instance principal, check it's enabled
oci auth instance-principal validate

Secrets not loading

Check the secrets directory permissions: ls -la ~/echos/secrets/
Verify .env file exists and has correct format
Check Docker logs: docker compose logs echos

Security Benefits

No .env files on server - Secrets are fetched at runtime
Centralized management - Update secrets from OCI Console
Audit logging - OCI Vault logs all secret access
Encryption at rest - Secrets are encrypted with master keys
No commit risk - Sensitive values never enter your git repo

Alternative: Simpler Approach

If Oracle Cloud Vault feels like overkill, consider this simpler alternative:

Host Environment Variables

Set environment variables directly on the Oracle Cloud server:

# SSH to server
ssh your-server

# Add to ~/.bashrc or create /etc/environment
echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.bashrc
echo 'export TELEGRAM_BOT_TOKEN="your-token"' >> ~/.bashrc
echo 'export ALLOWED_USER_IDS="your-ids"' >> ~/.bashrc
source ~/.bashrc

# Update docker-compose.yml to use environment instead of env_file
# (See docs/DEPLOYMENT.md)

This approach:

✅ No additional services needed
✅ Simple to set up
❌ Less secure than Vault
❌ Manual updates via SSH

Getting Started

Architecture

Features

Operations

Oracle Cloud Vault

Oracle Cloud Vault Integration

Overview

Prerequisites

Step 1: Create a Vault (One-time Setup)

Via OCI Console

Via OCI CLI (Optional)

Step 2: Create Secrets

Via OCI Console

Via OCI CLI

Step 3: Set Up OCI CLI on Your Server

Install OCI CLI

Configure OCI CLI

Authenticate

Step 4: Grant Access to Secrets (IAM Policy)

Via OCI Console

Via OCI CLI

Step 5: Create a Secret Retrieval Script

Step 6: Modify Docker Compose

Step 7: Update Deployment Script

Step 8: Test the Setup

Updating Secrets

Via OCI Console

Via OCI CLI

Troubleshooting

”Permission denied” when reading secrets

OCI CLI not authenticated

Secrets not loading

Security Benefits

Alternative: Simpler Approach

Host Environment Variables

References

​Oracle Cloud Vault Integration

​Overview

​Prerequisites

​Step 1: Create a Vault (One-time Setup)

​Via OCI Console

​Via OCI CLI (Optional)

​Step 2: Create Secrets

​Via OCI Console

​Via OCI CLI

​Step 3: Set Up OCI CLI on Your Server

​Install OCI CLI

​Configure OCI CLI

​Authenticate

​Step 4: Grant Access to Secrets (IAM Policy)

​Via OCI Console

​Via OCI CLI

​Step 5: Create a Secret Retrieval Script

​Step 6: Modify Docker Compose

​Step 7: Update Deployment Script

​Step 8: Test the Setup

​Updating Secrets

​Via OCI Console

​Via OCI CLI

​Troubleshooting

​”Permission denied” when reading secrets

​OCI CLI not authenticated

​Secrets not loading

​Security Benefits

​Alternative: Simpler Approach

​Host Environment Variables

​References

Oracle Cloud Vault Integration

Overview

Prerequisites

Step 1: Create a Vault (One-time Setup)

Via OCI Console

Via OCI CLI (Optional)

Step 2: Create Secrets

Via OCI Console

Via OCI CLI

Step 3: Set Up OCI CLI on Your Server

Install OCI CLI

Configure OCI CLI

Authenticate

Step 4: Grant Access to Secrets (IAM Policy)

Via OCI Console

Via OCI CLI

Step 5: Create a Secret Retrieval Script

Step 6: Modify Docker Compose

Step 7: Update Deployment Script

Step 8: Test the Setup

Updating Secrets

Via OCI Console

Via OCI CLI

Troubleshooting

”Permission denied” when reading secrets

OCI CLI not authenticated

Secrets not loading

Security Benefits

Alternative: Simpler Approach

Host Environment Variables

References