From 0e0a6ff1ebd66947aecdcaf91caef83ef89e4819 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20Gra=CC=88fenstein?= Date: Sun, 22 Mar 2026 16:33:40 +0100 Subject: [PATCH] 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 --- README.md | 16 +++ nextcloud-review.md | 174 +++++++++++++++++++++++++++ nextcloud/docker-compose.yml | 3 + nextcloud/hooks/post-installation.sh | 16 +++ nextcloud/hooks/post-upgrade.sh | 10 ++ 5 files changed, 219 insertions(+) create mode 100644 nextcloud-review.md create mode 100755 nextcloud/hooks/post-installation.sh create mode 100755 nextcloud/hooks/post-upgrade.sh diff --git a/README.md b/README.md index b467d2d..fbd5174 100644 --- a/README.md +++ b/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 + +# 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/` diff --git a/nextcloud-review.md b/nextcloud-review.md new file mode 100644 index 0000000..aa708de --- /dev/null +++ b/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" +``` diff --git a/nextcloud/docker-compose.yml b/nextcloud/docker-compose.yml index f6b76b7..882d26f 100644 --- a/nextcloud/docker-compose.yml +++ b/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 diff --git a/nextcloud/hooks/post-installation.sh b/nextcloud/hooks/post-installation.sh new file mode 100755 index 0000000..0705174 --- /dev/null +++ b/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." diff --git a/nextcloud/hooks/post-upgrade.sh b/nextcloud/hooks/post-upgrade.sh new file mode 100755 index 0000000..a02a729 --- /dev/null +++ b/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."