From 995dfcc099f5a60846368d43df6c79a7137ebb3a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Thomas=20Gra=CC=88fenstein?= <mail@thomas-graefenstein.de>
Date: Sun, 22 Mar 2026 17:07:43 +0100
Subject: [PATCH] add FPM worker tuning and architecture diagram

Increase PHP-FPM max_children from 5 to 12 to handle concurrent
requests without queuing, sized for a ~3GB VPS. Add Mermaid
architecture diagram to README.
---
 README.md                    | 42 ++++++++++++++++++++++++++++++++++++
 nextcloud/docker-compose.yml |  1 +
 nextcloud/fpm-tuning.conf    |  7 ++++++
 3 files changed, 50 insertions(+)
 create mode 100644 nextcloud/fpm-tuning.conf

diff --git a/README.md b/README.md
index fbd5174..e6a489e 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,48 @@
 
 Docker Compose setup for a self-hosted VPS running Nextcloud, Gitea, and monitoring — managed as a GitOps-style repo.
 
+## Architecture
+
+```mermaid
+graph TB
+    Internet([Internet])
+
+    subgraph VPS["VPS (t-gstone.de)"]
+        subgraph proxy_net["proxy network"]
+            Caddy["Caddy<br/>reverse proxy + auto HTTPS"]
+        end
+
+        subgraph nc_stack["Nextcloud Stack"]
+            Nginx["Nginx<br/>static files + FastCGI proxy"]
+            NC["Nextcloud FPM<br/>PHP processing"]
+            Cron["Cron<br/>background jobs"]
+            PG["PostgreSQL 17"]
+            Redis["Redis 8"]
+        end
+
+        subgraph gitea_stack["Gitea Stack"]
+            Gitea["Gitea<br/>rootless, SQLite"]
+        end
+
+        subgraph mon_stack["Monitoring Stack"]
+            Alloy["Grafana Alloy"]
+        end
+    end
+
+    GrafanaCloud([Grafana Cloud])
+
+    Internet -->|":443 HTTPS"| Caddy
+    Internet -->|":2222 SSH"| Gitea
+    Caddy -->|"nextcloud.t-gstone.de"| Nginx
+    Caddy -->|"git.t-gstone.de"| Gitea
+    Nginx -->|":9000 FastCGI"| NC
+    NC --> PG
+    NC --> Redis
+    Cron --> PG
+    Cron --> Redis
+    Alloy -->|"logs + metrics"| GrafanaCloud
+```
+
 ## Prerequisites
 
 - A VPS with SSH access
diff --git a/nextcloud/docker-compose.yml b/nextcloud/docker-compose.yml
index e501a71..00f35f4 100644
--- a/nextcloud/docker-compose.yml
+++ b/nextcloud/docker-compose.yml
@@ -19,6 +19,7 @@ services:
       - ${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
+      - ./fpm-tuning.conf:/usr/local/etc/php-fpm.d/zz-tuning.conf:ro
     networks:
       - nextcloud-internal
     logging:
diff --git a/nextcloud/fpm-tuning.conf b/nextcloud/fpm-tuning.conf
new file mode 100644
index 0000000..3bc6ed0
--- /dev/null
+++ b/nextcloud/fpm-tuning.conf
@@ -0,0 +1,7 @@
+[www]
+pm = dynamic
+pm.max_children = 12
+pm.start_servers = 4
+pm.min_spare_servers = 2
+pm.max_spare_servers = 6
+pm.max_requests = 500