rick-infra/roles/nextcloud/README.md

Nextcloud Cloud Storage Role

Self-contained Nextcloud deployment using Podman Quadlet with FPM, PostgreSQL database, and Valkey cache via Unix sockets.

Features

• Container: Single Nextcloud FPM container via Podman Quadlet
• Database: Self-managed PostgreSQL database via Unix socket
• Cache: Valkey (Redis-compatible) for file locking and caching
• Web Server: Caddy reverse proxy with FastCGI and automatic HTTPS
• Security: Group-based socket access, separated data/config volumes
• Size: ~320MB FPM image (vs 1.1GB Apache variant)

Architecture

Internet → Caddy (HTTPS:443) → FastCGI → Nextcloud FPM Container (127.0.0.1:9000)
                 ↓                                ↓
          Serves static files              PostgreSQL (socket)
          from /opt/nextcloud/html         Valkey (socket)

Volume Layout

/opt/nextcloud/
├── html/           # Application code (755 - readable by Caddy for static files)
├── data/           # User files (700 - private to container)
├── config/         # Config with secrets (700 - private to container)
├── custom_apps/    # Installed apps (755 - readable)
└── .env            # Environment variables (600)

Security Model:

• Caddy serves static assets (CSS/JS/images) directly from /opt/nextcloud/html
• Caddy cannot access /data or /config (mode 700)
• User files are only served through authenticated PHP requests via FPM

Dependencies

• postgresql role (infrastructure)
• valkey role (infrastructure)
• caddy role (web server)
• podman role (container runtime)

Variables

See defaults/main.yml for all configurable variables.

Required Vault Variables

Define these in your host_vars/ with ansible-vault:

# Core credentials (required)
vault_nextcloud_db_password: "secure-database-password"
vault_nextcloud_admin_password: "secure-admin-password"
vault_valkey_password: "secure-valkey-password"

# Email credentials (optional - only if email enabled)
vault_nextcloud_smtp_password: "secure-smtp-password"

# OIDC credentials (optional - only if OIDC enabled)
vault_nextcloud_oidc_client_id: "nextcloud-client-id-from-authentik"
vault_nextcloud_oidc_client_secret: "nextcloud-client-secret-from-authentik"

Key Variables

# Domain
nextcloud_domain: "cloud.jnss.me"

# Admin user
nextcloud_admin_user: "admin"

# Database
nextcloud_db_name: "nextcloud"
nextcloud_db_user: "nextcloud"

# Cache (use different DB number per service)
nextcloud_valkey_db: 2  # Authentik uses 1

# PHP limits
nextcloud_php_memory_limit: "512M"
nextcloud_php_upload_limit: "512M"

Deployment Strategy

This role uses a two-phase deployment approach to work correctly with the Nextcloud container's initialization process:

Phase 1: Container Initialization (automatic)

1. Create empty directories for volumes
2. Deploy environment configuration (.env)
3. Start Nextcloud container
4. Container entrypoint detects first-time setup (no version.php)
5. Container copies Nextcloud files to /var/www/html/
6. Container runs occ maintenance:install with PostgreSQL
7. Installation creates config.php with database credentials

Phase 2: Configuration via OCC Script (automatic)

8. Ansible waits for occ status to report installed: true
9. Ansible deploys and runs configuration script inside container
10. Script configures system settings via OCC commands:
    • Redis caching (without sessions)
    • Maintenance window and phone region
    • Database optimizations (indices, bigint, mimetypes)

Why this order?

The Nextcloud container's entrypoint uses version.php as a marker to determine if installation is needed. We must wait for the container's auto-installation to complete before running configuration commands:

• Container must complete first-time setup (copy files, run occ maintenance:install)
• OCC commands require a fully initialized Nextcloud installation
• Running configuration after installation avoids conflicts with the entrypoint script

Configuration Method:

This role uses OCC commands via a script rather than config files because:

• ✅ Explicit and verifiable - Run occ config:list system to see exact state
• ✅ No file conflicts - Avoids issues with Docker image's built-in config files
• ✅ Fully idempotent - Safe to re-run during updates
• ✅ Single source of truth - All configuration in one script template

See the official Nextcloud Docker documentation for more details on the auto-configuration process.

Installed Apps

This role automatically installs and enables the following apps:

• user_oidc - OpenID Connect authentication backend for SSO integration
• calendar - Calendar and scheduling application (CalDAV)
• contacts - Contact management application (CardDAV)

To customize the app list, override these variables in your host_vars:

nextcloud_apps_install:
  - user_oidc
  - calendar
  - contacts
  - tasks  # Add more apps as needed
  - deck
  - mail

OIDC/SSO Integration

Prerequisites

Before enabling OIDC, you must create an OIDC application/provider in your identity provider (e.g., Authentik):

For Authentik:

1. Navigate to Applications → Providers

2. Click Create → OAuth2/OpenID Provider

3. Configure:

   • Name: Nextcloud
   • Authorization flow: default-authentication-flow (or your preferred flow)
   • Client type: Confidential
   • Client ID: Generate or specify (save this)
   • Client Secret: Generate or specify (save this)
   • Redirect URIs: https://cloud.jnss.me/apps/user_oidc/code
   • Signing Key: Select your signing certificate
   • Scopes: Add openid, profile, email

4. Create Application:

   • Navigate to Applications → Applications
   • Click Create
   • Name: Nextcloud
   • Slug: nextcloud
   • Provider: Select the provider created above
   • Launch URL: https://cloud.jnss.me

5. Note the Discovery URL: https://auth.jnss.me/application/o/nextcloud/.well-known/openid-configuration

Configuration

Enable OIDC in your host_vars/arch-vps/main.yml:

# OIDC Configuration
nextcloud_oidc_enabled: true
nextcloud_oidc_provider_id: "authentik"  # Provider identifier (slug)
nextcloud_oidc_provider_name: "Authentik SSO"  # Display name on login button
nextcloud_oidc_discovery_url: "https://auth.jnss.me/application/o/nextcloud/.well-known/openid-configuration"

# Security settings (recommended defaults)
nextcloud_oidc_unique_uid: true  # Prevents account takeover between providers
nextcloud_oidc_check_bearer: false
nextcloud_oidc_send_id_token_hint: true

# Attribute mappings (defaults work for most providers)
nextcloud_oidc_mapping_display_name: "name"
nextcloud_oidc_mapping_email: "email"
nextcloud_oidc_mapping_uid: "preferred_username"  # Or "sub" for UUID

# Optional: Enable single login (auto-redirect to SSO)
nextcloud_oidc_single_login: false  # Set to true to force SSO login

Add credentials to your vault file host_vars/arch-vps/vault.yml:

vault_nextcloud_oidc_client_id: "nextcloud-client-id-from-authentik"
vault_nextcloud_oidc_client_secret: "nextcloud-client-secret-from-authentik"

OIDC Scopes

The following scopes are requested from your OIDC provider by default:

nextcloud_oidc_scope: "email profile nextcloud openid"

Standard scopes:

• openid - Required for OpenID Connect (contains no claims itself)
• email - User's email address (email and email_verified claims)
• profile - User's profile information (name, given_name, preferred_username, picture, etc.)

Custom scope for Authentik:

• nextcloud - Custom scope mapping you create in Authentik (contains groups, quota, user_id)

Creating the Nextcloud Scope Mapping in Authentik

The nextcloud scope must be created as a custom property mapping in Authentik:

1. Log in to Authentik as administrator
2. Navigate to Customization → Property mappings → Create
3. Select type: Scope mapping
4. Configure:
   • Name: Nextcloud Profile
   • Scope name: nextcloud
   • Expression:

# Extract all groups the user is a member of
groups = [group.name for group in user.ak_groups.all()]

# In Nextcloud, administrators must be members of a fixed group called "admin"
# If a user is an admin in authentik, ensure that "admin" is appended to their group list
if user.is_superuser and "admin" not in groups:
    groups.append("admin")

return {
    "name": request.user.name,
    "groups": groups,
    # Set a quota by using the "nextcloud_quota" property in the user's attributes
    "quota": user.group_attributes().get("nextcloud_quota", None),
    # To connect an existing Nextcloud user, set "nextcloud_user_id" to the Nextcloud username
    "user_id": user.attributes.get("nextcloud_user_id", str(user.uuid)),
}

5. Click Finish
6. Navigate to your Nextcloud provider → Advanced protocol settings
7. Add Nextcloud Profile to Scopes (in addition to the default scopes)

Group Provisioning and Synchronization

Automatically sync user group membership from Authentik to Nextcloud.

Default configuration:

nextcloud_oidc_group_provisioning: true  # Auto-create groups from Authentik
nextcloud_oidc_mapping_groups: "groups"  # Claim containing group list

How it works:

1. User logs in via OIDC
2. Authentik sends group membership in the groups claim (from the custom scope)
3. Nextcloud automatically:
   • Creates groups that don't exist in Nextcloud
   • Adds user to those groups
   • Removes user from groups they're no longer member of in Authentik

Example: Making a user an admin

Nextcloud requires admins to be in a group literally named admin. The custom scope mapping (above) automatically adds "admin" to the groups list for Authentik superusers.

Alternatively, manually create a group in Authentik called admin and add users to it.

Quota management:

Set storage quotas by adding the nextcloud_quota attribute to Authentik groups or users:

1. In Authentik, navigate to Directory → Groups → select your group
2. Under Attributes, add:

   {
     "nextcloud_quota": "15 GB"
   }
   

3. Users in this group will have a 15 GB quota in Nextcloud
4. If not set, quota is unlimited

Complete Authentik Setup Guide

Follow these steps to set up OIDC authentication with Authentik:

Step 1: Create the Custom Scope Mapping

See Creating the Nextcloud Scope Mapping in Authentik above.

Step 2: Create the OAuth2/OpenID Provider

1. In Authentik, navigate to Applications → Providers
2. Click Create → OAuth2/OpenID Provider
3. Configure:
   • Name: Nextcloud
   • Authorization flow: default-authentication-flow (or your preferred flow)
   • Client type: Confidential
   • Client ID: Generate or specify (save this for later)
   • Client Secret: Generate or specify (save this for later)
   • Redirect URIs: https://cloud.jnss.me/apps/user_oidc/code
   • Signing Key: Select your signing certificate
   • Under Advanced protocol settings:
     • Scopes: Add openid, email, profile, and Nextcloud Profile (the custom scope created in Step 1)
     • Subject mode: Based on the User's UUID (or Based on the User's username if you prefer usernames)

Step 3: Create the Application

1. Navigate to Applications → Applications
2. Click Create
3. Configure:
   • Name: Nextcloud
   • Slug: nextcloud
   • Provider: Select the provider created in Step 2
   • Launch URL: https://cloud.jnss.me (optional)

Step 4: Note the Discovery URL

The discovery URL follows this pattern:

https://auth.jnss.me/application/o/<slug>/.well-known/openid-configuration

For the application slug nextcloud, it will be:

https://auth.jnss.me/application/o/nextcloud/.well-known/openid-configuration

Step 5: Configure Nextcloud Role Variables

In your host_vars/arch-vps/main.yml:

nextcloud_oidc_enabled: true
nextcloud_oidc_provider_id: "authentik"
nextcloud_oidc_provider_name: "Authentik"
nextcloud_oidc_discovery_url: "https://auth.jnss.me/application/o/nextcloud/.well-known/openid-configuration"
nextcloud_oidc_scope: "email profile nextcloud openid"
nextcloud_oidc_mapping_uid: "preferred_username"  # Or "sub" for UUID-based IDs
nextcloud_oidc_mapping_display_name: "name"
nextcloud_oidc_mapping_email: "email"
nextcloud_oidc_mapping_groups: "groups"
nextcloud_oidc_mapping_quota: "quota"
nextcloud_oidc_group_provisioning: true

In your host_vars/arch-vps/vault.yml:

vault_nextcloud_oidc_client_id: "nextcloud"  # Client ID from Authentik
vault_nextcloud_oidc_client_secret: "very-long-secret-from-authentik"  # Client Secret from Authentik

Step 6: Deploy and Test

Run the Nextcloud playbook:

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

Supported OIDC Providers

The user_oidc app supports any OpenID Connect 1.0 compliant provider:

• Authentik (recommended for self-hosted)
• Keycloak
• Auth0
• Okta
• Azure AD / Microsoft Entra ID
• Google Identity Platform
• GitHub (via OIDC)
• GitLab
• Authelia
• Kanidm
• Any other OIDC 1.0 compliant provider

The nextcloud_oidc_provider_id is just an identifier slug - you can use any value like authentik, keycloak, auth0, mycompany-sso, etc.

Verification

After deployment:

1. Check provider configuration:

   podman exec --user www-data nextcloud php occ user_oidc:provider
   podman exec --user www-data nextcloud php occ user_oidc:provider authentik
   

2. Test login:

   • Visit https://cloud.jnss.me
   • You should see a "Log in with Authentik SSO" button
   • Click it to test SSO flow
   • User account should be auto-created on first login

3. Check user mapping:

   podman exec --user www-data nextcloud php occ user:list
   

Troubleshooting OIDC

Login button doesn't appear:

# Check if user_oidc app is enabled
podman exec --user www-data nextcloud php occ app:list | grep user_oidc

# Enable if needed
podman exec --user www-data nextcloud php occ app:enable user_oidc

Discovery URL errors:

# Test discovery URL is accessible from container
podman exec nextcloud curl -k https://auth.jnss.me/application/o/nextcloud/.well-known/openid-configuration

JWKS cache issues:

# Clear JWKS cache
podman exec --user www-data nextcloud php occ user_oidc:provider authentik \
    --clientid='your-client-id'

Email Configuration

Configure Nextcloud to send emails for password resets, notifications, and sharing.

Configuration

Enable email in your host_vars/arch-vps/main.yml:

# Email Configuration
nextcloud_email_enabled: true
nextcloud_smtp_host: "smtp.fastmail.com"
nextcloud_smtp_port: 587
nextcloud_smtp_secure: "tls"  # tls, ssl, or empty
nextcloud_smtp_username: "nextcloud@jnss.me"
nextcloud_mail_from_address: "nextcloud"
nextcloud_mail_domain: "jnss.me"

# Set admin user's email address
nextcloud_admin_email: "admin@jnss.me"

Add SMTP password to vault host_vars/arch-vps/vault.yml:

vault_nextcloud_smtp_password: "your-smtp-app-password"

Common SMTP Providers

Fastmail:

nextcloud_smtp_host: "smtp.fastmail.com"
nextcloud_smtp_port: 587
nextcloud_smtp_secure: "tls"

Gmail (App Password required):

nextcloud_smtp_host: "smtp.gmail.com"
nextcloud_smtp_port: 587
nextcloud_smtp_secure: "tls"

Office 365:

nextcloud_smtp_host: "smtp.office365.com"
nextcloud_smtp_port: 587
nextcloud_smtp_secure: "tls"

SMTP2GO:

nextcloud_smtp_host: "mail.smtp2go.com"
nextcloud_smtp_port: 587
nextcloud_smtp_secure: "tls"

Verification

After deployment:

1. Check SMTP configuration:

   podman exec --user www-data nextcloud php occ config:list system | grep mail
   

2. Check admin email:

   podman exec --user www-data nextcloud php occ user:setting admin settings email
   

3. Send test email via Web UI:

   • Log in as admin
   • Settings → Administration → Basic settings
   • Scroll to "Email server"
   • Click "Send email" button
   • Check recipient inbox

Troubleshooting Email

Test SMTP connection from container:

# Install swaks if needed (for testing)
podman exec nextcloud apk add --no-cache swaks

# Test SMTP connection
podman exec nextcloud swaks \
  --to recipient@example.com \
  --from nextcloud@jnss.me \
  --server smtp.fastmail.com:587 \
  --auth LOGIN \
  --auth-user nextcloud@jnss.me \
  --auth-password 'your-password' \
  --tls

Check Nextcloud logs:

podman exec --user www-data nextcloud php occ log:watch

Usage

Include in Playbook

- role: nextcloud
  tags: ['nextcloud', 'cloud', 'storage']

Deploy

# Deploy Nextcloud role
ansible-playbook -i inventory/hosts.yml site.yml --tags nextcloud --ask-vault-pass

# Deploy only infrastructure dependencies
ansible-playbook -i inventory/hosts.yml site.yml --tags postgresql,valkey,caddy

Verification

After deployment:

1. Access Nextcloud:

   https://cloud.jnss.me
   

2. Check service status:

   ssh root@arch-vps
   systemctl status nextcloud
   podman ps | grep nextcloud
   

3. View logs:

   # Container logs
   journalctl -u nextcloud -f
   podman logs nextcloud
   
   # Caddy logs
   tail -f /var/log/caddy/nextcloud.log
   

4. Verify socket access:

   # Check group memberships
   id nextcloud
   # Should show: postgres-clients, valkey-clients
   
   # Check socket permissions
   ls -la /var/run/postgresql/.s.PGSQL.5432
   ls -la /var/run/valkey/valkey.sock
   

Maintenance

OCC Command (Nextcloud CLI)

Run Nextcloud's OCC command-line tool:

# General syntax
podman exec --user www-data nextcloud php occ <command>

# Examples
podman exec --user www-data nextcloud php occ status
podman exec --user www-data nextcloud php occ app:list
podman exec --user www-data nextcloud php occ maintenance:mode --on
podman exec --user www-data nextcloud php occ files:scan --all

Update Nextcloud

The container automatically updates on restart:

systemctl restart nextcloud

Or pull specific version:

# In host_vars or defaults
nextcloud_version: "32-fpm"  # Pin to major version
# Or
nextcloud_version: "32.0.3-fpm"  # Pin to exact version

Backup Strategy

Key directories to backup:

1. User data: /opt/nextcloud/data
2. Configuration: /opt/nextcloud/config
3. Database: PostgreSQL nextcloud database
4. Custom apps: /opt/nextcloud/custom_apps (optional)

Example backup script:

#!/bin/bash
# Enable maintenance mode
podman exec --user www-data nextcloud php occ maintenance:mode --on

# Backup data and config
tar -czf nextcloud-data-$(date +%Y%m%d).tar.gz /opt/nextcloud/data /opt/nextcloud/config

# Backup database
sudo -u postgres pg_dump nextcloud > nextcloud-db-$(date +%Y%m%d).sql

# Disable maintenance mode
podman exec --user www-data nextcloud php occ maintenance:mode --off

Performance Tuning

Adjust PHP limits in host_vars:

nextcloud_php_memory_limit: "1G"      # For large files
nextcloud_php_upload_limit: "10G"     # For large uploads

Redis/Valkey Caching Architecture

This role uses a split caching strategy for optimal performance and stability:

PHP Sessions: File-based (default PHP session handler)

• Location: /var/www/html/data/sessions/
• Why: Redis session locking can cause cascading failures under high concurrency
• Performance: Excellent for single-server deployments

Nextcloud Application Cache: Redis/Valkey

• memcache.local: APCu (in-memory opcode cache)
• memcache.distributed: Redis (shared cache, file locking)
• memcache.locking: Redis (transactional file locking)
• Configuration: Via OCC commands in configuration script

Why not Redis sessions?

The official Nextcloud Docker image enables Redis session handling when REDIS_HOST is set. However, this can cause severe performance issues:

1. Session lock contention: Multiple parallel requests (browser loading CSS/JS/images) compete for the same session lock
2. Infinite retries: Default lock_retries = -1 means workers block forever
3. Timeout orphaning: When reverse proxy times out, FPM workers keep running and hold locks
4. Worker exhaustion: Limited FPM workers (default 5) all become blocked
5. Cascading failure: New requests queue, timeouts accumulate, locks orphan

This role disables Redis sessions by not setting REDIS_HOST in the environment, while still providing Redis caching via OCC configuration commands.

If you need Redis sessions (e.g., multi-server setup with session sharing), you must:

1. Enable REDIS_HOST in nextcloud.env.j2
2. Add a custom PHP ini file with proper lock parameters:
   • redis.session.lock_expire = 30 (locks expire after 30 seconds)
   • redis.session.lock_retries = 100 (max 100 retries, not infinite)
   • redis.session.lock_wait_time = 50000 (50ms between retries)
3. Mount the ini file with zz- prefix to load after the entrypoint's redis-session.ini
4. Increase FPM workers significantly (15-20+)
5. Monitor for orphaned session locks

Troubleshooting

Container won't start

# Check container logs
journalctl -u nextcloud -n 50
podman logs nextcloud

# Check systemd unit
systemctl status nextcloud

Permission errors

# Verify user groups
id nextcloud

# Should be in: postgres-clients, valkey-clients
# If not, re-run user.yml tasks:
ansible-playbook -i inventory/hosts.yml site.yml --tags nextcloud,user

Database connection errors

# Test PostgreSQL socket
sudo -u nextcloud psql -h /var/run/postgresql -U nextcloud -d nextcloud

# Check socket exists and permissions
ls -la /var/run/postgresql/.s.PGSQL.5432

Caddy FastCGI errors

# Check Caddy can read app files
sudo -u caddy ls -la /opt/nextcloud/html

# Verify FPM is listening
ss -tlnp | grep 9000

# Test FPM connection
curl -v http://127.0.0.1:9000

"Trusted domain" errors

Add domains to nextcloud_trusted_domains:

nextcloud_trusted_domains: "cloud.jnss.me localhost 69.62.119.31"

Or add via OCC:

podman exec --user www-data nextcloud php occ config:system:set trusted_domains 1 --value=cloud.jnss.me

Integration with Authentik SSO

To integrate Nextcloud with Authentik for SSO, see the Authentik documentation for OAuth2/OIDC provider setup.

Security Notes

• User data (/opt/nextcloud/data) is mode 700 - only container can access
• Config (/opt/nextcloud/config) is mode 700 - contains database passwords
• Application files (/opt/nextcloud/html) are mode 755 - Caddy can read for static files
• All traffic is HTTPS via Caddy with automatic Let's Encrypt certificates
• Database and cache connections use Unix sockets (no TCP exposure)
• Container runs as root initially, then switches to www-data (UID 33) for PHP-FPM

Socket Access Pattern

Nextcloud uses a different access pattern than other rick-infra services due to how the official Nextcloud container works:

How it works:

1. Container starts as root (UID 0)
2. Entrypoint runs as root to write PHP configuration files
3. Entrypoint switches to www-data (UID 33) for PHP-FPM process
4. www-data accesses PostgreSQL and Valkey via Unix sockets

Why 777 socket permissions are needed:

• The Nextcloud container cannot use --group-add effectively because:
  • --group-add only adds groups to the initial user (root)
  • When the container switches from root to www-data, supplementary groups are lost
  • www-data (UID 33, GID 33) ends up with no access to group-restricted sockets
• Infrastructure sockets use mode 777 to allow access by any UID
• Security is maintained via password authentication (PostgreSQL: scram-sha-256, Valkey: requirepass)
• Sockets are local-only (not network-exposed)

Alternative (TCP): If you prefer group-based socket access (770), you can configure PostgreSQL and Valkey to use TCP instead:

# In host_vars
postgresql_listen_addresses: "127.0.0.1"
postgresql_unix_socket_permissions: "0770"  # Restrict to group

valkey_bind: "127.0.0.1"
valkey_port: 6379
valkey_unix_socket_enabled: false

# In Nextcloud env
POSTGRES_HOST=127.0.0.1
POSTGRES_PORT=5432
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

This provides the same security level (password-authenticated, localhost-only) but uses TCP instead of Unix sockets. The trade-off is slightly lower performance compared to Unix sockets.

See infrastructure role documentation (PostgreSQL and Valkey READMEs) for more details on this architectural decision.

References

• Nextcloud Official Docker Image
• Nextcloud Documentation
• Caddy FastCGI Documentation