rick-infra/roles/nextcloud/VAULT_VARIABLES.md

# Nextcloud Role - Vault Variables

This document describes all vault-encrypted variables used by the Nextcloud role.

## Required Variables

These variables **must** be defined in your vault file for the role to function:

```yaml
# =================================================================
# Core Credentials (REQUIRED)
# =================================================================

# PostgreSQL database password for Nextcloud user
vault_nextcloud_db_password: "CHANGE_ME_secure_database_password"

# Nextcloud admin user password
vault_nextcloud_admin_password: "CHANGE_ME_secure_admin_password"

# Valkey (Redis) password for caching (shared infrastructure)
vault_valkey_password: "CHANGE_ME_secure_valkey_password"
```

## Optional Variables

These variables are only required if you enable the corresponding features:

### Email/SMTP Configuration

Only required if `nextcloud_email_enabled: true`:

```yaml
# =================================================================
# Email/SMTP Credentials (OPTIONAL)
# =================================================================

# SMTP server password for sending emails
# Used with nextcloud_smtp_username for authentication
vault_nextcloud_smtp_password: "your-smtp-password-or-app-password"
```

**Example for Gmail:**
- Use an [App Password](https://support.google.com/accounts/answer/185833)
- Do NOT use your main Google account password

**Example for Fastmail:**
- Use an [App Password](https://www.fastmail.help/hc/en-us/articles/360058752854)

### OIDC/SSO Configuration

Only required if `nextcloud_oidc_enabled: true`:

```yaml
# =================================================================
# OIDC/SSO Credentials (OPTIONAL)
# =================================================================

# OAuth2/OIDC Client ID from your identity provider
vault_nextcloud_oidc_client_id: "nextcloud"

# OAuth2/OIDC Client Secret from your identity provider
# IMPORTANT: Keep this secret! Anyone with this can impersonate your app
vault_nextcloud_oidc_client_secret: "very-long-random-secret-from-authentik"
```

## Complete Vault File Example

Here's a complete example of a vault file with all possible variables:

```yaml
---
# =================================================================
# Example Vault File
# =================================================================
# File: host_vars/arch-vps/vault.yml
# Encrypted with: ansible-vault encrypt host_vars/arch-vps/vault.yml

# Caddy TLS
vault_caddy_tls_email: "admin@jnss.me"
vault_cloudflare_api_token: "your-cloudflare-token"

# Authentik
vault_authentik_db_password: "authentik-db-password"
vault_authentik_secret_key: "authentik-secret-key"
vault_authentik_admin_password: "authentik-admin-password"

# Valkey (shared infrastructure)
vault_valkey_password: "V4lk3y!P@ssw0rd#R3d1s"

# Nextcloud - Core (always required)
vault_nextcloud_db_password: "XkN8vQ2mP9wR5tY7uI0oP3sA6dF8gH1j"
vault_nextcloud_admin_password: "AdminP@ssw0rd!SecureAndL0ng"

# Nextcloud - Email (optional)
vault_nextcloud_smtp_password: "fastmail-app-password-xyz123"

# Nextcloud - OIDC (optional)
vault_nextcloud_oidc_client_id: "nextcloud"
vault_nextcloud_oidc_client_secret: "aksk_authentik_secret_very_long_random_string"
```

## Creating/Editing Vault File

### First Time Setup

```bash
# Create encrypted vault file
ansible-vault create host_vars/arch-vps/vault.yml

# Add the variables above, then save and exit
```

### Edit Existing Vault

```bash
# Edit encrypted vault file
ansible-vault edit host_vars/arch-vps/vault.yml

# Add the Nextcloud variables, then save and exit
```

### View Vault Contents

```bash
# View vault file contents
ansible-vault view host_vars/arch-vps/vault.yml
```

### Password Generation

Generate secure passwords:

```bash
# Generate 32-character passwords
openssl rand -base64 32

# Or using pwgen
pwgen -s 32 1
```

## Running Playbooks with Vault

### Interactive Password Prompt

```bash
ansible-playbook -i inventory/hosts.yml site.yml --ask-vault-pass
```

### Using a Password File

```bash
# Create password file (DO NOT COMMIT THIS!)
echo 'your-vault-password' > .vault_pass
chmod 600 .vault_pass

# Add to .gitignore
echo '.vault_pass' >> .gitignore

# Run playbook
ansible-playbook -i inventory/hosts.yml site.yml --vault-password-file .vault_pass
```

## Security Notes

- **Never commit unencrypted vault files** to git
- Use strong, randomly generated passwords (at least 32 characters)
- Each service should have unique database passwords
- Store vault password securely (password manager, encrypted file, etc.)
- Consider using `ansible-vault rekey` to change vault password periodically

## Troubleshooting

### "Vault password incorrect"

**Problem:** Wrong vault password entered

**Solution:** Verify you're using the correct vault password

### "vault_nextcloud_db_password is undefined"

**Problem:** Variable not defined in vault file or vault file not loaded

**Solution:**
1. Verify variable exists in vault file:
   ```bash
   ansible-vault view host_vars/arch-vps/vault.yml | grep vault_nextcloud
   ```

2. Ensure you're using `--ask-vault-pass`:
   ```bash
   ansible-playbook -i inventory/hosts.yml site.yml --ask-vault-pass
   ```

## Verification

Check that variables are properly encrypted:

```bash
# View encrypted file (should show encrypted content)
cat host_vars/arch-vps/vault.yml

# Decrypt and view (requires password)
ansible-vault view host_vars/arch-vps/vault.yml
```

## Reference

- [Ansible Vault Documentation](https://docs.ansible.com/ansible/latest/user_guide/vault.html)
- [Best Practices for Variables and Vaults](https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html#variables-and-vaults)