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

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 — not used directly, present transitively (image handling 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*

4.6 KiB Raw Blame History