60 lines
5.5 KiB
Markdown
60 lines
5.5 KiB
Markdown
# Web Server — static sites, downloads and routing
|
|
|
|
The built-in Web Server serves local files and, optionally, passes PHP scripts to an **external PHP-FPM service**. A reusable **Web Service** is referenced by a Vhost or by a Custom location. Its files and PHP settings are not duplicated in the Vhost.
|
|
|
|
## Create a Web Service
|
|
|
|
1. Open **Web Server → New Web Service**. Choose an ID/name and an absolute document root readable by the RustProxy service account.
|
|
2. Set index files (default `index.html`, `index.htm`), whether directory listing is allowed (off by default), MIME handling and download extensions.
|
|
3. Add `try_files`, rewrites, response headers and cache rules only if your application requires them.
|
|
4. Enable PHP only if you have a reachable, protected PHP-FPM endpoint; otherwise static files do not need any PHP runtime.
|
|
5. Save, create or edit a **Vhost**, select **Web Server** as source and choose the service ID.
|
|
6. Test index files, static assets, missing files, direct directory access, downloads and headers.
|
|
|
|
A Web Service can be shared across several Vhosts. A Vhost may also use ordinary Reverse Proxy as its default and a Web Service for `/assets` or another custom location. Web Server and HTTP reverse proxy use the normal frontend TLS, access, logging and eligible cache pipeline.
|
|
|
|
## File serving options
|
|
|
|
| Feature | Behavior / caution |
|
|
|---|---|
|
|
| **Document root** | Files are served only through the configured root; keep private keys, source secrets and writable control files outside it. |
|
|
| **Indexes / listing** | Configurable index priority; directory listing is disabled by default. |
|
|
| **`try_files`** | Try requested paths, then a fallback such as `/index.html` or the PHP front controller. Useful for SPAs and frameworks. |
|
|
| **Rewrites** | Bounded regex internal rewrites or supported redirect statuses; evaluated in the Web Service routing pipeline. |
|
|
| **MIME / downloads** | Built-in type mapping with extensions and explicit attachment options. |
|
|
| **Headers / cache** | Service-level headers and optional static cache-control rules; later Vhost/location response rules may override. |
|
|
| **Compression** | Dynamic gzip/Brotli/Zstandard/deflate policy and eligible precompressed `.br`/`.gz` sidecars. |
|
|
| **File validators / ranges** | Conditional `ETag`/date checks, HEAD and supported byte ranges for eligible files. |
|
|
| **Symlinks** | `deny` by default; `inside_root` is an explicit less restrictive policy. |
|
|
| **Hardening** | Optional checks for common sensitive/attack paths and removal of selected server-identifying headers; not a full WAF. |
|
|
|
|
### Static delivery (`sendfile`) — 0.34.0
|
|
|
|
In **Web Server → Edit service → Delivery**, `sendfile` supports `off` (default) and `auto`. On **Linux**, eligible full static **GET** responses of at least **64 KiB** over **unencrypted HTTP/1.1** may use a kernel file-transfer path. TLS, HTTP/2, HTTP/3, ranged or transformed content, compressed responses and active object-cache responses keep the normal streaming path. This transport choice should not invalidate otherwise compatible cached objects. It is an **unverified source candidate** in the provided archive: test it on the actual server before use and do not assume a measured speedup.
|
|
|
|
## Rewrites and application presets
|
|
|
|
The editor supports common website presets to fill suggested fields; review their document root, `try_files`, MIME and PHP values before saving. Presets do not install WordPress, Roundcube or other applications. For a single-page app, a fallback similar to `$uri`, `$uri/`, `/index.html` serves the SPA entry for routes without an existing file. For PHP frameworks, use the appropriate front controller; see [PHP-FPM](PHP_FPM.md).
|
|
|
|
## `.htaccess` compatibility
|
|
|
|
An optional bounded Apache-style `.htaccess` compatibility layer supports a **subset** of rules useful for migrations, not arbitrary Apache modules or dynamic directive execution. It can scan configured paths and enforce stricter handling of unsupported expressions. Prefer explicit `try_files`/rewrite/header controls when possible and test migrated sites. A real Apache configuration cannot be pasted unchanged into RustProxy.
|
|
|
|
## PHP and error responses
|
|
|
|
A Web Service may enable PHP via a shared PHP-FPM profile or its own configuration. PHP is executed by the FPM service, not RustProxy, and must not be exposed as a raw Internet port. Use dedicated pools for different applications. See [PHP-FPM](PHP_FPM.md).
|
|
|
|
Vhosts can intercept selected application error bodies in **Pages** and return a configured HTML error page while preserving the status. Internal location `error_fallback` is different: it routes the error to a named internal handler. Error-page replacements are marked uncacheable.
|
|
|
|
## Monitoring and issues
|
|
|
|
A Web Service's dashboard shows request rate, status/error counts, response-header timing, delivered bytes and PHP permit usage (when PHP is configured). These are application observations, not proof of external PHP worker count or final compressed network bytes.
|
|
|
|
- **403 / unexpected block:** inspect document-root permissions, symlink policy, hardening and inherited ACLs.
|
|
- **404 / unwanted SPA rewrite:** check actual files, index list, `try_files`, location matching and rewrite order.
|
|
- **Wrong Content-Type/download:** check MIME override and attachment extensions.
|
|
- **PHP script downloaded instead of executed:** check PHP enablement, script extension and FPM endpoint.
|
|
- **Cache not filling:** inspect both global and Vhost cache, static response headers and cookies.
|
|
|
|
Keep all document roots and external application processes separately patched and secured.
|