# OpenApply Deployment - Vault Variables Reference

This document lists the encrypted variables that must be configured in `ansible/group_vars/all/vault.yml` before deploying OpenApply.

## Required Vault Variables

### Proxmox API Authentication

```yaml
# Proxmox API endpoint
vault_proxmox_api_host: "10.0.0.201"

# Proxmox API user (typically root@pam)
vault_proxmox_api_user: "root@pam"

# Proxmox API token ID
vault_proxmox_api_token_id: "automation"

# Proxmox API token secret (encrypted)
vault_proxmox_api_token_secret: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  [encrypted token here]
```

### LXC Container Credentials

```yaml
# Root password for the OpenApply LXC container (encrypted)
vault_openapply_lxc_root_password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  [encrypted password here]
```

### Application Secrets (Optional)

```yaml
# Firebase deployment token (optional, encrypted)
vault_openapply_firebase_token: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  [encrypted token here]
```

## Creating/Editing Vault Variables

### First-time Setup

```bash
# Navigate to ansible directory
cd /home/chester/homelab/ansible

# Edit the encrypted vault file
ansible-vault edit group_vars/all/vault.yml

# Add the variables listed above
```

### Generating a Proxmox API Token

1. Log into Proxmox web UI (https://pve01:8006)
2. Navigate to: Datacenter → Permissions → API Tokens
3. Click "Add" button
4. User: `root@pam`
5. Token ID: `automation` (or custom name)
6. Privilege Separation: **Unchecked** (for full root@pam permissions)
7. Click "Add"
8. **Copy the secret immediately** (only shown once)
9. Add to vault file as shown above

### Required Permissions

If using privilege separation, the token needs:
- `VM.Allocate` - Create new containers
- `VM.Config.Network` - Configure networking
- `VM.PowerMgmt` - Start/stop containers
- `Datastore.AllocateSpace` - Allocate storage

### Security Best Practices

1. **Never commit unencrypted secrets** to Git
2. Rotate API tokens quarterly
3. Use separate tokens for different automation workflows
4. Audit Proxmox API access logs regularly
5. Verify vault encryption: `ansible-vault view group_vars/all/vault.yml`

## Validation

Test that vault variables are correctly configured:

```bash
# Verify vault can be decrypted
ansible-vault view group_vars/all/vault.yml

# Test variable resolution (without execution)
ansible-playbook playbooks/deploy-openapply.yml --check --diff
```

## Troubleshooting

### "vault_proxmox_api_token_secret is undefined"

Ensure the variable is present in `group_vars/all/vault.yml` and the file is properly encrypted.

### "Authentication failed"

1. Verify token ID matches Proxmox configuration
2. Confirm token is not expired
3. Check privilege separation settings
4. Regenerate token if necessary

### "Cannot decrypt vault"

Ensure `ansible/vault/.vault_pass` contains the correct vault password.