83 lines
3.6 KiB
Markdown
83 lines
3.6 KiB
Markdown
# 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`
|