tilde.club/docs/web.md

# Web publishing

The collected tilde.club configuration uses nginx, PHP-FPM, and fcgiwrap.
Apache's `mod_userdir`, `.htaccess`, and `a2enmod` do not configure this stack.

## Production layout

The main site's document root is `/usr/share/nginx/html`. Its server block
serves HTTP and HTTPS. Several separate service vhosts redirect HTTP to HTTPS,
but the main host's block serves both. The main nginx config includes
`/etc/nginx/sites-enabled/*`; this is a local layout to reproduce explicitly,
not an assumption about the distribution default.

| Request | Backend or directory |
| --- | --- |
| Main site | `/usr/share/nginx/html` |
| `/~USER/` and `/u/USER/` | `/home/USER/public_html/` |
| User PHP | `/run/php-fpm/php-fpm-php-user.sock`, pool UID `php-user`, group `club` |
| Main site PHP | `/run/php-fpm/www.sock`, pool UID/group `nginx` |
| User CGI | `/run/fcgiwrap/fcgiwrap-cgi.sock`; service runs as `cgiwrap` |
| `/~USER/git` | Local cgit wrapper through fcgiwrap |
| `/~USER/myplant` | Central Botany PHP application |
| WeeChat relay beneath a user page | A socket beneath the user's `.weechat` directory |
| Webmail | SnappyMail in a separate vhost |

The user-page location enables directory listings and SSI, and uses a per-user
HTML 404 page. Account for those features when replacing a running config.

The collected pool generator can create per-user FPM sockets, but the main
user-page route uses the **shared** pool. `makeuser` does not call the pool
generator. Do not describe this as per-user PHP execution.

The CGI unit has UID/GID-changing capabilities. Those capabilities do not, by
themselves, establish that each script is switched to its owner. That needs the
wrapper implementation and a runtime identity test. Likewise, the collected
CGI `SCRIPT_FILENAME` expression prepends a home path to `$request_filename`
inside an alias location. Verify the expanded path before using it in a new
config. The new-host examples below use explicit per-account paths instead.

## Start with static pages

Use [tilde-static.conf](../examples/nginx/tilde-static.conf) inside nginx's
`http` context and replace the example domain. It provides both user URL forms,
blocks dotfiles and script-source downloads, and disables symlinks in public
user content. The example leaves directory listings and SSI off; enable those
features deliberately if your community wants them.

A 0711 home can be traversed without being listed. Public directories need
0755 and public files 0644. Keep the user's other files private. Check every
path component with `namei -l`, not just the page's final mode.

For a new SELinux-enforcing host, use the installed policy's home publishing
support. A common Fedora layout is:

```bash
setsebool -P httpd_enable_homedirs on
semanage fcontext -a -t httpd_user_content_t '/home/[^/]+/public_html(/.*)?'
restorecon -RFv /home/member/public_html
```

If a matching custom rule already exists, review it and use `semanage fcontext
-m` to modify it instead of adding a duplicate. Test access as the service and
inspect AVC denials. Policy versions and service domains can require additional
booleans or labels for writing or connecting to other services; enable only the
access actually needed. The production snapshot with SELinux disabled cannot
validate those policy rules for a new enforcing installation.

Useful checks:

```bash
nginx -t
namei -l /home/member/public_html/index.html
ls -Zd /home/member /home/member/public_html
ausearch -m AVC,USER_AVC -ts recent
journalctl -u nginx --since today
```

The production host sends nginx logs to syslog; do not assume every nginx error
will be in `/var/log/nginx/error.log`. Check the effective `error_log` setting.

## Add HTTPS

After obtaining a certificate, retain the HTTP challenge location and decide
whether other HTTP requests should be served or redirected. For an HTTPS-only
policy, redirect the non-challenge requests to a fixed configured hostname,
rather than constructing a redirect from an unvalidated Host header.

Copy the publishing locations into an HTTPS server block with these settings,
using the certificate paths returned by Certbot:

```nginx
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name tilde.example.net;
ssl_certificate /etc/letsencrypt/live/tilde.example.net/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/tilde.example.net/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
```

Keep shared locations in one root-owned include if both server blocks use them.
Set response headers in the context where they are intended to apply. Test
headers on error responses and nested locations; inheritance is version-specific.
A blanket CSP, frame policy, or cross-origin isolation policy on every member's
page can break the projects you are hosting. Keep the operator application and
member publishing policies separate. Add HSTS only after deciding that all of
its affected names will continue to support HTTPS.

A Certbot deploy hook for nginx can be a root-owned executable file in
`/etc/letsencrypt/renewal-hooks/deploy/`:

```bash
#!/usr/bin/env bash
set -euo pipefail
/usr/sbin/nginx -t
/usr/bin/systemctl reload nginx
```

Enable the packaged renewal timer and test renewal. The collected production
service instead invokes `/usr/local/bin/certbot renew --standalone`, with hooks
to stop and start nginx. Its timer checks at 06:09 and 18:09 in the host's local
time, with `Persistent=true`. That produces a different availability profile
from webroot renewal. Verify all certificate consumers after renewal, including
Dovecot and Postfix if they share the certificate.

## Add PHP with a deliberate execution identity

A new host can give an enabled member a dedicated pool. Install maintained
packages, including the process extension if you use the identity test below:

```bash
dnf install php-fpm php-cli php-process
```

Review [member.conf](../examples/php-fpm/member.conf), then install it as
`/etc/php-fpm.d/member.conf`. The Unix account and group must already exist.
Create the private session directory named in that file:

```bash
sudo -u member -- install -d -m 0700 /home/member/.local/state/php/sessions
php-fpm -t
systemctl enable --now php-fpm
```

If PHP-FPM is already running, reload it after successful validation. Ensure the
nginx worker can connect to the new socket. With SELinux enabled, directory
labels, FPM's domain, and socket policy need to be checked on the target system.

Insert [member-php.inc](../examples/nginx/member-php.inc) into the site's server
block **after** the dotfile-denial location but **before** the generic script
source-denial and static userdir locations. Keep both HTTP and HTTPS policy
consistent. The example supports `.php` endpoints for this named member; it
does not implement PATH_INFO routing for arbitrary frameworks. If you want PHP
index files, add `index.php` to the userdir index list after enabling its handler.

Validate and reload nginx. Use this temporary test in the member's public
directory, then remove it:

```php
<?php

declare(strict_types=1);

header('Content-Type: text/plain; charset=utf-8');
echo 'sapi=', PHP_SAPI, "\n";
echo 'uid=', posix_geteuid(), "\n";
```

Compare the response UID with `id -u member`. Do not use `get_current_user()` as
an execution-identity test: it reports the script file's owner. Also test that
the backend cannot read a second member's private file. FPM running as the member
still has all the access that member has; it is not a container or a separate
security identity from their shell.

Tune `pm.max_children`, process lifetime, memory, uploads, and logging to the
machine. Avoid eagerly starting several workers for every dormant account.
The collected shared pool uses 20 maximum children and a 120-second request
limit; those are production settings for that pool, not universal defaults.

## CGI

A new installation can use Fedora's `fcgiwrap@.service` template with a separate
instance for an enabled member. Inspect the installed unit with `systemctl cat`
and confirm the service runs as that member. Override the matching socket's
owner/group so nginx can connect, keeping the socket at 0660. Do not grant a
shared CGI worker UID-changing capabilities merely to imitate the current unit.

Restrict a new CGI handler to the specific member's `public_html/cgi-bin` path.
Use a fixed `SCRIPT_FILENAME` mapping for that account, verify the target is a
real executable, and test the interpreter, UID, environment, and filesystem
access before enabling it. Keep source-file denial for scripts without an
enabled handler. PATH_INFO and executable index support need their own tests.
The existing host's generalized CGI wrapper was not supplied, so this guide
does not claim it can reproduce its owner-switching behavior.

## Publishing tests

Use two disposable members and check response bodies and filesystem effects,
not just status codes:

- Both user URL forms, nested directories, index files, and trailing-slash redirects.
- Missing users and scripts, dotfiles, percent-encoded paths, and traversal attempts.
- A symlink from public content to a nonpublic readable file.
- PHP source denial before enabling PHP, then the correct runtime UID afterward.
- A script under one account trying to read or write the other account's private data.
- User custom error pages, directory listings, SSI, and optional routes where enabled.
- TLS certificate validation and all response headers on successful and error responses.

Remove diagnostics and downloadable configuration archives from the web root
after use. Keep configs root-owned, validate before reload, and keep the previous
config available for rollback.