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:

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

# =================================================================
# 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
• Do NOT use your main Google account password

Example for Fastmail:

• Use an App Password

OIDC/SSO Configuration

Only required if nextcloud_oidc_enabled: true:

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

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

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

# Add the variables above, then save and exit

Edit Existing Vault

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

# Add the Nextcloud variables, then save and exit

View Vault Contents

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

Password Generation

Generate secure passwords:

# Generate 32-character passwords
openssl rand -base64 32

# Or using pwgen
pwgen -s 32 1

Running Playbooks with Vault

Interactive Password Prompt

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

Using a Password File

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

   ansible-vault view host_vars/arch-vps/vault.yml | grep vault_nextcloud
   

2. Ensure you're using --ask-vault-pass:

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

Verification

Check that variables are properly encrypted:

# 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
• Best Practices for Variables and Vaults