MILE: All current services confirmed working on a fresh arch vps

roles/nextcloud/README.md

@@ -78,6 +78,40 @@ 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: Custom Configuration (automatic)
+8. Ansible waits for `occ status` to report `installed: true`
+9. Ansible deploys custom `redis.config.php` (overwrites default)
+10. Container restart applies custom configuration
+
+**Why this order?**
+
+The Nextcloud container's entrypoint uses `version.php` as a marker to determine if installation is needed. If you deploy any files into `/opt/nextcloud/config/` before the container starts, the initialization process fails:
+
+- Container copies files including `version.php`
+- Entrypoint sees `version.php` exists → assumes already installed
+- Skips running `occ maintenance:install`
+- Result: Empty `config.php`, 503 errors
+
+By deploying custom configs **after** installation completes, we:
+- ✅ Allow the container's auto-installation to run properly
+- ✅ Override specific configs (like Redis) after the fact
+- ✅ Maintain idempotency (subsequent runs just update configs)
+
+See the official [Nextcloud Docker documentation](https://github.com/nextcloud/docker#auto-configuration-via-environment-variables) for more details on the auto-configuration process.
+
 ## Usage
 
 ### Include in Playbook
@@ -232,11 +266,13 @@ This role disables Redis sessions by **not setting** `REDIS_HOST` in the environ
 
 **If you need Redis sessions** (e.g., multi-server setup with session sharing), you must:
 1. Enable `REDIS_HOST` in `nextcloud.env.j2`
-2. Set proper lock parameters in a custom PHP ini file
-3. Increase FPM workers significantly (15-20+)
-4. Monitor for orphaned session locks
-
-See `templates/redis-session-override.ini.j2` for an example of session lock tuning.
+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