Refactor Nextcloud configuration to use OCC script approach and add email/OIDC support
Major architectural changes: - Replace config file templating with unified OCC command script - Remove custom_apps mount overlay that caused Caddy serving issues - Implement script-based configuration for idempotency and clarity Configuration improvements: - Add email/SMTP support with master switch (nextcloud_email_enabled) - Add OIDC/SSO integration with Authentik support - Add apps installation (user_oidc, calendar, contacts) - Enable group provisioning and quota management from OIDC - Set nextcloud_oidc_unique_uid to false per Authentik docs Files removed: - nextcloud.config.php.j2 (replaced by OCC commands) - redis.config.php.j2 (replaced by OCC commands) - optimization.yml (merged into configure.yml) Files added: - configure-nextcloud.sh.j2 (single source of truth for config) - configure.yml (deploys and runs configuration script) Documentation: - Add comprehensive OIDC setup guide with Authentik integration - Document custom scope mapping and group provisioning - Add email configuration examples for common providers - Update vault variables documentation - Explain two-phase deployment approach Host configuration: - Change admin user from 'admin' to 'joakim' - Add admin email configuration
This commit is contained in:
@@ -1,22 +1,104 @@
|
||||
# Nextcloud Role - Required Vault Variables
|
||||
# Nextcloud Role - Vault Variables
|
||||
|
||||
This role requires the following encrypted variables to be defined in your vault file (typically `host_vars/<hostname>/vault.yml`).
|
||||
This document describes all vault-encrypted variables used by the Nextcloud role.
|
||||
|
||||
## Required Variables
|
||||
|
||||
Add these to your encrypted vault file:
|
||||
These variables **must** be defined in your vault file for the role to function:
|
||||
|
||||
```yaml
|
||||
# Nextcloud database password
|
||||
# =================================================================
|
||||
# Core Credentials (REQUIRED)
|
||||
# =================================================================
|
||||
|
||||
# PostgreSQL database password for Nextcloud user
|
||||
vault_nextcloud_db_password: "CHANGE_ME_secure_database_password"
|
||||
|
||||
# Nextcloud admin account password
|
||||
# Nextcloud admin user password
|
||||
vault_nextcloud_admin_password: "CHANGE_ME_secure_admin_password"
|
||||
|
||||
# Valkey/Redis password (shared infrastructure)
|
||||
# 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
|
||||
@@ -37,6 +119,13 @@ 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:
|
||||
@@ -49,39 +138,26 @@ openssl rand -base64 32
|
||||
pwgen -s 32 1
|
||||
```
|
||||
|
||||
## Example Vault File
|
||||
## Running Playbooks with Vault
|
||||
|
||||
Your `host_vars/arch-vps/vault.yml` should include:
|
||||
|
||||
```yaml
|
||||
---
|
||||
# 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"
|
||||
|
||||
# Nextcloud (ADD THESE)
|
||||
vault_nextcloud_db_password: "generated-password-1"
|
||||
vault_nextcloud_admin_password: "generated-password-2"
|
||||
|
||||
# Valkey (shared infrastructure)
|
||||
vault_valkey_password: "valkey-password"
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
When deploying, you'll need to provide the vault password:
|
||||
### Interactive Password Prompt
|
||||
|
||||
```bash
|
||||
# Deploy with vault password prompt
|
||||
ansible-playbook -i inventory/hosts.yml site.yml --tags nextcloud --ask-vault-pass
|
||||
ansible-playbook -i inventory/hosts.yml site.yml --ask-vault-pass
|
||||
```
|
||||
|
||||
# Or use a password file
|
||||
ansible-playbook -i inventory/hosts.yml site.yml --tags nextcloud --vault-password-file ~/.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
|
||||
@@ -92,6 +168,29 @@ ansible-playbook -i inventory/hosts.yml site.yml --tags nextcloud --vault-passwo
|
||||
- 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:
|
||||
@@ -103,3 +202,8 @@ 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)
|
||||
|
||||
Reference in New Issue
Block a user