add trusted proxy, post-install/upgrade hooks, occ docs and admin review

- Add TRUSTED_PROXIES=caddy to fix reverse proxy header warning
- Add post-installation hook: maintenance window, phone region, DB indices, MIME migrations
- Add post-upgrade hook: DB indices and MIME migrations
- Add occ commands section to README
- Add nextcloud-review.md with admin warning fixes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -180,6 +180,22 @@ docker compose --env-file .env -f nextcloud/docker-compose.yml up -d
 docker compose --env-file .env -f gitea/docker-compose.yml logs -f
 ```
 
+## Running Nextcloud OCC Commands
+
+Nextcloud's `occ` command-line tool must run as the `www-data` user inside the container:
+
+```bash
+# General syntax
+sudo docker exec -u www-data nextcloud php occ <command>
+
+# Examples
+sudo docker exec -u www-data nextcloud php occ status
+sudo docker exec -u www-data nextcloud php occ config:list
+sudo docker exec -u www-data nextcloud php occ app:list
+sudo docker exec -u www-data nextcloud php occ db:add-missing-indices
+sudo docker exec -u www-data nextcloud php occ maintenance:repair --include-expensive
+```
+
 ## Adding a New Service
 
 1. Create a new directory: `mkdir myapp/`

nextcloud-review.md

@@ -0,0 +1,174 @@
+# Nextcloud Admin Warnings Review
+
+## 1. Reverse Proxy Forwarded Headers
+
+**Problem:** Nextcloud doesn't see the correct client IP because Caddy isn't sending the required forwarded headers, or Nextcloud isn't configured to trust them.
+
+**Fix:** Two changes needed:
+
+**a) Caddyfile** — Caddy already sets `X-Forwarded-For` and `X-Forwarded-Proto` by default, so no Caddyfile changes are strictly needed. However, verify Caddy is on the `proxy` network and connects to `nextcloud:80`.
+
+**b) Nextcloud config** — Add trusted proxy config. Run inside the Nextcloud container:
+
+```bash
+sudo docker exec -u www-data nextcloud php occ config:system:set trusted_proxies 0 --value="caddy"
+sudo docker exec -u www-data nextcloud php occ config:system:set forwarded_for_headers 0 --value="HTTP_X_FORWARDED_FOR"
+```
+
+Alternatively, add these environment variables to `nextcloud/.env`:
+
+```
+TRUSTED_PROXIES=caddy
+```
+
+---
+
+## 2. Log Errors (16 errors since March 15)
+
+**Problem:** 16 errors logged. These need to be inspected to determine the cause.
+
+**Fix:** Check the logs:
+
+```bash
+sudo docker exec -u www-data nextcloud php occ log:watch
+# or
+sudo docker exec -u www-data nextcloud php occ log:list
+# or read the log file directly
+sudo docker exec nextcloud cat /var/www/html/data/nextcloud.log | tail -50
+```
+
+Review and address the specific errors. Common causes after a fresh install include missing config values (several of which are listed below).
+
+---
+
+## 3. Maintenance Window Start Time
+
+**Problem:** No maintenance window configured, so heavy background jobs run at any time.
+
+**Fix:**
+
+```bash
+sudo docker exec -u www-data nextcloud php occ config:system:set maintenance_window_start --type=integer --value=1
+```
+
+This sets the maintenance window to start at 1:00 UTC (3:00 AM CEST). Adjust the value (0-23) to match your low-usage hours.
+
+---
+
+## 4. MIME Type Migrations
+
+**Problem:** New MIME types are available but not yet applied.
+
+**Fix:**
+
+```bash
+sudo docker exec -u www-data nextcloud php occ maintenance:repair --include-expensive
+```
+
+This may take a while on large instances but is fine on a fresh install.
+
+---
+
+## 5. Missing Database Indices
+
+**Problem:** Missing optional indices on `filecache` and `properties` tables that improve query performance.
+
+**Fix:**
+
+```bash
+sudo docker exec -u www-data nextcloud php occ db:add-missing-indices
+```
+
+---
+
+## 6. AppAPI Deploy Daemon
+
+**Problem:** No default deploy daemon configured for external apps (ExApps).
+
+**Fix:** This is only needed if you plan to use ExApps (like the AI assistant apps). If not, this warning can be ignored.
+
+If you want to set it up, it requires a Docker Socket Proxy or direct Docker access from Nextcloud. This is a more involved setup — see the [AppAPI documentation](https://cloud-py-api.github.io/app_api/).
+
+**Recommendation:** Ignore unless you need ExApps.
+
+---
+
+## 7. Two-Factor Authentication Not Enforced
+
+**Problem:** 2FA providers are available but not mandatory for all users.
+
+**Fix:** To enforce 2FA for all users:
+
+```bash
+sudo docker exec -u www-data nextcloud php occ twofactorauth:enforce --on
+```
+
+Make sure you have a 2FA provider app installed and configured (e.g., TOTP) **before** enforcing, or you may lock yourself out. Install TOTP first:
+
+```bash
+sudo docker exec -u www-data nextcloud php occ app:install twofactor_totp
+```
+
+Then set up 2FA for your admin account via the web UI before enforcing.
+
+---
+
+## 8. Default Phone Region
+
+**Problem:** No default phone region set for validating phone numbers without country code.
+
+**Fix:**
+
+```bash
+sudo docker exec -u www-data nextcloud php occ config:system:set default_phone_region --value="DE"
+```
+
+Use the appropriate ISO 3166-1 code for your region (DE = Germany).
+
+---
+
+## 9. Server ID Not Configured
+
+**Problem:** No server ID set. Only matters for multi-server setups.
+
+**Fix:** Even on a single server, setting it avoids the warning:
+
+```bash
+sudo docker exec -u www-data nextcloud php occ config:system:set instanceid --value="$(openssl rand -hex 5)"
+```
+
+**Note:** Only do this on a fresh install. On an existing instance, `instanceid` is already set automatically — check first:
+
+```bash
+sudo docker exec -u www-data nextcloud php occ config:system:get instanceid
+```
+
+If it returns a value, this warning may be about a different server-id config. In that case, set `server_id` instead:
+
+```bash
+sudo docker exec -u www-data nextcloud php occ config:system:set server_id --value="nextcloud-1"
+```
+
+---
+
+## Quick-Fix Summary (run in order)
+
+```bash
+# 1. Trusted proxy
+sudo docker exec -u www-data nextcloud php occ config:system:set trusted_proxies 0 --value="caddy"
+
+# 3. Maintenance window (1:00 UTC)
+sudo docker exec -u www-data nextcloud php occ config:system:set maintenance_window_start --type=integer --value=1
+
+# 4. MIME type migrations
+sudo docker exec -u www-data nextcloud php occ maintenance:repair --include-expensive
+
+# 5. Missing DB indices
+sudo docker exec -u www-data nextcloud php occ db:add-missing-indices
+
+# 8. Phone region
+sudo docker exec -u www-data nextcloud php occ config:system:set default_phone_region --value="DE"
+
+# 9. Server ID
+sudo docker exec -u www-data nextcloud php occ config:system:set server_id --value="nextcloud-1"
+```

nextcloud/docker-compose.yml

@@ -13,9 +13,12 @@ services:
       - POSTGRES_HOST=postgres
       - REDIS_HOST=redis
       - REDIS_HOST_PASSWORD=${REDIS_PASSWORD}
+      - TRUSTED_PROXIES=caddy
     volumes:
       - ${DATA_ROOT}/nextcloud/html:/var/www/html
       - ${DATA_ROOT}/nextcloud/data:/var/www/html/data
+      - ./hooks/post-installation.sh:/docker-entrypoint-hooks.d/post-installation/post-installation.sh:ro
+      - ./hooks/post-upgrade.sh:/docker-entrypoint-hooks.d/post-upgrade/post-upgrade.sh:ro
     networks:
       - proxy
       - nextcloud-internal

nextcloud/hooks/post-installation.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+set -eu
+
+echo "==> Post-installation: setting maintenance window start to 01:00 UTC..."
+php occ config:system:set maintenance_window_start --type=integer --value=1
+
+echo "==> Post-installation: setting default phone region to DE..."
+php occ config:system:set default_phone_region --value="DE"
+
+echo "==> Post-installation: adding missing DB indices..."
+php occ db:add-missing-indices
+
+echo "==> Post-installation: running MIME type migrations..."
+php occ maintenance:repair --include-expensive
+
+echo "==> Post-installation: done."

nextcloud/hooks/post-upgrade.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -eu
+
+echo "==> Post-upgrade: adding missing DB indices..."
+php occ db:add-missing-indices
+
+echo "==> Post-upgrade: running MIME type migrations..."
+php occ maintenance:repair --include-expensive
+
+echo "==> Post-upgrade: done."