version 1

nginx/README.md

@@ -0,0 +1,82 @@
+# Nextcloud NGINX Default Configuration – Documentation
+This README describes the exact behavior and requirements of the NGINX configuration file `default.conf` used to serve a standalone Nextcloud instance behind a reverse proxy. The documentation is intentionally written so that an AI can regenerate the correct `default.conf` **from this README alone**. The output must always be a working Nextcloud NGINX configuration without deviation.
+
+## PURPOSE
+This configuration provides a secure, reverse-proxy-compatible NGINX frontend for Nextcloud with PHP-FPM. It ensures:
+- Clean routing via `index.php`
+- No rewrite loops
+- Correct handling of `.mjs` MIME type
+- Compatibility with `/ocs` API endpoints
+- Secure static asset handling and caching
+- Protection of internal folders
+- No directory listing
+- Works behind an existing TLS reverse proxy
+- Fully functional Dashboard and Apps
+
+## REQUIRED PROPERTIES
+A correct generated configuration MUST:
+- Include exactly ONE `server { ... }` block
+- Use `listen 8080;`
+- Use `server_name _;`
+- Set `root /var/www/html;`
+- Use `try_files $uri $uri/ /index.php?$request_uri;` for main routing
+- Use `fastcgi_pass nextcloud-fpm-v1:9000;` for PHP handling
+- Include PHP entry location for `index.php`, `remote.php`, `public.php`, `ocs.php`, `ocs-provider.php`, `cron.php`
+- Include a separate `/ocs/` handler BEFORE the PHP blocks
+- Include MIME fix for `.mjs`
+- Deny access to `config`, `data`, `lib`, `3rdparty`, etc.
+- Block generic `.php` execution
+- Allow static files caching
+- Work with rewrite base `/`
+- NOT configure TLS (handled externally)
+- NOT include proxy headers inside this config
+- Be valid under `nginx -t`
+
+## FILE LOCATION REQUIREMENTS
+- Filename: `default.conf`
+- Must be mounted into NGINX container as `/etc/nginx/conf.d/default.conf`
+- File must NOT include other config files via `include`
+
+## NO AUTO REDIRECTS TO PORT 8080
+The configuration must not cause browsers to redirect to `https://host:8080`. It must work normally when served over reverse proxy.
+
+## SECURITY REQUIREMENTS
+- Deny access to internal folders:
+  `/config`, `/data`, `/templates`, `/tests`, `/lib`, `/build`, `/3rdparty`
+- Deny access to CLI entrypoints like `/occ`
+- Disable execution of arbitrary `.php` files
+- Allow only approved PHP entry scripts
+
+## MUST-HAVE SECTIONS
+1. Basic server declaration
+2. Security headers
+3. Well-known redirects for CalDAV/CardDAV
+4. Root route using `try_files`
+5. Allowed PHP routing
+6. `/ocs/` API passthrough
+7. Static file handlers
+8. `.mjs` MIME type fix
+
+## ROUTING BEHAVIOR
+| URL Example                                | Must Result                           |
+|-------------------------------------------|--------------------------------------|
+| `/apps/dashboard/`                        | Render dashboard, no 403             |
+| `/ocs/v2.php/apps/user_status/api/v1/*`   | Must NOT return 404 or 500           |
+| `/remote.php/dav/`                        | Must work                            |
+| `/index.php/...`                          | Must work                            |
+| `/favicon.ico`                            | 200 or cached                        |
+
+## NO CHANGES ALLOWED
+These things MUST NOT be modified:
+- No gzip or brotli here
+- No `proxy_set_header` here
+- No HTTPS config
+- No HTTP → HTTPS redirects
+
+## GUARANTEE
+If an AI uses ONLY this README as input, the result MUST be a valid, production-ready NGINX `default.conf` for Nextcloud that passes all tests above and prevents:
+- `rewrite or internal redirection cycle` errors
+- `403 forbidden` on `/apps/dashboard`
+- `500` errors on `/ocs/v2.php`
+- MIME type warnings for `.mjs`
+- Looping on `/index.php/index.php`