Files

Joakim 4f8da38ca6 Add Nextcloud cloud storage role with split Redis caching strategy

## New Features

- **Nextcloud Role**: Complete cloud storage deployment using Podman Quadlet
  - FPM variant with Caddy reverse proxy and FastCGI
  - PostgreSQL database via Unix socket
  - Valkey/Redis for app-level caching and file locking
  - Automatic HTTPS with Let's Encrypt via Caddy
  - Dual-root pattern: Caddy serves static assets, FPM handles PHP

- **Split Caching Strategy**: Redis caching WITHOUT Redis sessions
  - Custom redis.config.php template for app-level caching only
  - File-based PHP sessions for stability (avoids session lock issues)
  - Prevents cascading failures from session lock contention
  - Documented in role README with detailed rationale

## Infrastructure Updates

- **Socket Permissions**: Update PostgreSQL and Valkey to mode 777
  - Required for containers that switch users (root → www-data)
  - Nextcloud container loses supplementary groups on user switch
  - Security maintained via password authentication (scram-sha-256, requirepass)
  - Documented socket permission architecture in docs/

- **PostgreSQL**: Export client group GID as fact for dependent roles
- **Valkey**: Export client group GID as fact, update socket fix service

## Documentation

- New: docs/socket-permissions-architecture.md
  - Explains 777 vs 770 socket permission trade-offs
  - Documents why group-based access doesn't work for user-switching containers
  - Provides TCP alternative for stricter security requirements

- Updated: All role READMEs with socket permission notes
- New: Nextcloud README with comprehensive deployment, troubleshooting, and Redis architecture documentation

## Configuration

- host_vars: Add Nextcloud vault variables and configuration
- site.yml: Include Nextcloud role in main playbook

## Technical Details

**Why disable Redis sessions?**

The official Nextcloud container enables Redis session handling via REDIS_HOST env var,
which causes severe performance issues:

1. Session lock contention under high concurrency (browser parallel asset requests)
2. Infinite lock retries (default lock_retries=-1) blocking FPM workers
3. Timeout orphaning: reverse proxy kills connection, worker keeps lock
4. Worker pool exhaustion: all 5 default workers blocked on same session lock
5. Cascading failure: new requests queue, more timeouts, more orphaned locks

Solution: Use file-based sessions (reliable, fast for single-server) while keeping
Redis for distributed cache and transactional file locking via custom config file.

This provides optimal performance without the complexity of Redis session debugging.

Tested: Fresh deployment on arch-vps (69.62.119.31)
Domain: https://cloud.jnss.me/

2025-12-14 22:07:08 +01:00

2.5 KiB

Raw Blame History

Nextcloud Role - Required Vault Variables

This role requires the following encrypted variables to be defined in your vault file (typically host_vars/<hostname>/vault.yml).

Required Variables

Add these to your encrypted vault file:

# Nextcloud database password
vault_nextcloud_db_password: "CHANGE_ME_secure_database_password"

# Nextcloud admin account password
vault_nextcloud_admin_password: "CHANGE_ME_secure_admin_password"

# Valkey/Redis password (shared infrastructure)
vault_valkey_password: "CHANGE_ME_secure_valkey_password"

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

Password Generation

Generate secure passwords:

# Generate 32-character passwords
openssl rand -base64 32

# Or using pwgen
pwgen -s 32 1

Example Vault File

Your host_vars/arch-vps/vault.yml should include:

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

# Deploy with vault password prompt
ansible-playbook -i inventory/hosts.yml site.yml --tags nextcloud --ask-vault-pass

# Or use a password file
ansible-playbook -i inventory/hosts.yml site.yml --tags nextcloud --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

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

2.5 KiB Raw Blame History