xamxam/docs/environment.md

Environment / runtime requirements

The software stack and server environment required to run XAMXAM. This is the machine-facing counterpart to the original product spec (fiche technique, archived at spec-sheet.md).

Production server (xamxam)

Item	Value
OS	Debian 13 (trixie), x86_64
Web server	nginx 1.26 (config: nginx/xamxam.conf)
PHP	PHP-FPM 8.4 (pool www, master config /etc/php/8.4/fpm/)
Database	SQLite 3 (WAL mode), /var/www/xamxam/storage/xamxam.db
App root	/var/www/xamxam/ (DocumentRoot → app/public/)
App user	www-data, group xamxam
Node.js	Not required on the server — assets are built locally and rsync'd

Image transcoding tooling (installed 2026-08-31)

Installed on the production server to generate lightweight WebP/AVIF cover thumbnails (home-page cover grid — up to ~95% payload reduction):

• php-gd — PHP GD extension (WebP/AVIF encode/resize for on-the-fly serving)
• webp — provides the cwebp CLI (WebP conversion)
• libavif-bin — provides the avifenc CLI (AVIF conversion)

Install on any environment that must serve cover thumbnails:

sudo apt-get install php-gd webp libavif-bin

Consumed by the cover-thumbnail pipeline (see docs/... once implemented).

PHP (≥ 8.4)

Declared in composer.json ("php": ">=8.4", platform lock 8.4).

Required extensions (composer.json require)

• ext-json
• ext-openssl
• ext-pdo

Implicitly required (used by the code or transitive deps)

Verified present in the production php -m output and on the FPM pool:

• pdo_sqlite / sqlite3 — the primary datastore
• curl — PeerTube/Nextcloud/HTTP integrations (Guzzle uses it)
• mbstring / iconv / intl — string handling, Markdown, translations
• session — admin auth + CSRF (see security.md)
• sodium — Crypto (libsodium) for encrypted fields (SMTP password)
• zlib / phar — Composer autoload + PHAR-based tooling
• gd — intentionally installed (php-gd, 2026-08-31) for cover-image transcoding to WebP/AVIF; resize/encode derivations for the home-page cover grid. Not used for MIME validation (that is finfo).
• fileinfo — upload MIME validation (finfo)
• calendar, ctype, filter, hash, tokenizer, xml, libxml — PHP core extensions, present by default

Recommended (production)

• opcache (+ opcache.preload optional) — bytecode cache
• xdebug — disabled/not loaded in production (dev only)

PHP — other runtime settings

• Session GC — tuned in /etc/php/8.4/fpm/conf.d/zz-xamxam-session.ini (see security.md): gc_maxlifetime = 43200, gc_probability = 1, gc_divisor = 100. Must stay ≥ the app's ABSOLUTE_TIMEOUT_SECONDS (12 h).
• Upload limits — storage partition temp dir at /var/www/xamxam/storage/tmp/php-uploads/ (not /tmp tmpfs); see file-uploads.md.
• Logs — Monolog writes to /var/log/xamxam/ (provisioned by the deploy script).

Composer dependencies

From composer.json:

Package	Purpose
guzzlehttp/guzzle ^7.9	HTTP client (PeerTube, Nextcloud, integrations)
league/commonmark ^2.4	Markdown rendering (pages, help blocks)
monolog/monolog ^3.10	Logging
phpmailer/phpmailer ^6.9	SMTP (STARTTLS/SMTPS/plain)

Dev-only: phpunit/phpunit ^11, phpstan/phpstan ^2.1, friendsofphp/php-cs-fixer ^3.95, symfony/polyfill-iconv ^1.31.

Node.js / npm (build-time only)

Used locally to build frontend assets — not needed on the production server. Build tooling is pinned in package.json devDependencies:

Package	Purpose
rolldown	JS bundling
lightningcss	CSS minification
@biomejs/biome	lint/format
chokidar-cli	dev watch mode

Run npm ci (not npm install) to install; npm run build (or just build) to produce app/public/assets/.

nginx

• Config source: nginx/xamxam.conf; installed to /etc/nginx/sites-available/xamxam (symlinked from sites-enabled/).
• PHP handled via fastcgi_pass to the php8.4-fpm pool www.
• Security headers enforced here (HSTS, CSP, etc.) — see security.md and nginx/docs/SECURITY_HEADERS.md.
• Static assets served from app/public/; /storage, /src, /templates, DB/env hidden files are blocked.

Database

• SQLite 3 file DB (app/storage/xamxam.db) in WAL mode.
• Schema + migrations: app/src/DatabaseMigrations.php; see database.md.
• Backups: WAL-safe sqlite3 .backup (see deployment.md).
• sqlite3 CLI required on the server for backup/query helpers.

Toolchain / CLI

Required on the dev machine (and just on deploy-from-local):

• PHP ≥ 8.4 (same extensions as above, plus sqlite3 for local DB)
• Composer 2.x
• Node.js + npm (for the JS build)
• just (command runner; see justfile)
• ssh access to xamxam for just deploy*

See also

• development.md — local dev workflow, structure, builds
• deployment.md — server setup, deploy, backups, rollback
• security.md — security posture, session GC tuning