Development
How to set up Foresi on your own machine, build its assets, run the worker and the tests. To run it on a server, see operations.md.
Requirements
Section titled “Requirements”- PHP 8.4 or newer with the
ctype,dom,gd,iconv,intl,sodium,zipandpdo_sqliteextensions (pdo_pgsqlfor PostgreSQL) max_input_varsof at least1000, the PHP default, so an invoice of 100 lines arrives whole (a form cut off by a lower limit is refused and nothing is saved)upload_max_filesizeandpost_max_sizeof at least50Min php.ini, so imports can take files up to the 50 MB the application allows (a lower server limit is reported as such on the upload screen)- Composer 2
- SQLite 3.35 or newer for development, or PostgreSQL 17 (both are covered by the tests)
Quick start
Section titled “Quick start”composer installbin/console aboutcomposer isdoc:schema # the ISDOC schema for the tests, fetched and checked by SHA-256, never committedcomposer qaStyles are built by Tailwind CSS (standalone binary, downloaded by the bundle into var/tailwind/ on first use; no Node needed). Build them before opening the app in a browser:
bin/console tailwind:build # oncebin/console tailwind:build --watch # while developingbin/console tailwind:build --minify # before deploying, then bin/console asset-map:compileFor a production build run, in this order and with APP_ENV=prod: bin/console importmap:install, bin/console tailwind:build --minify, bin/console asset-map:compile. Missing imports are an error in this build (strict missing_import_mode), and CI fails on any warning in the output. Icons are never fetched at runtime; add them with bin/console ux:icons:import lucide:<name> and commit them.
The built CSS is not committed, and tests and composer qa do not need it. Inter fonts (SIL OFL 1.1) and Lucide icons (ISC) are self-hosted in assets/; nothing is loaded from a CDN. All UI text lives in translations/ (Czech default, English).
The default configuration in .env uses a local SQLite database in var/data.db. Put local overrides, including APP_SECRET, in .env.local, which is never committed.
Firm logos and stamps are stored in <APP_SHARE_DIR>/<environment>/firm-images, which is var/share/prod/firm-images by default, outside the web root. Keep that directory on persistent storage and include it in backups: documents refer to these files.
Background worker
Section titled “Background worker”Long-running work (imports, register re-checks, sending e-mail, timed jobs) runs in a worker, not in the web request. Messages are stored in the database (messenger_messages, created by a migration) Run migrations, then start one worker; it consumes the schedule’s ticks (scheduler_foresi) and the outgoing mail (mail) first, then the domain events (events: their relay and the delivery to listeners), then async, then the outbound webhooks (webhooks: one attempt per message, after async so a slow receiver never holds up imports or timed jobs), and registry (low priority) last. An installation with many webhook endpoints also runs a second worker, messenger:consume webhooks (see operations). The first worker:
php bin/console messenger:consume scheduler_foresi mail events async webhooks registry --memory-limit=256M --time-limit=3600The worker exits after an hour or at the memory limit, so run it under a supervisor that restarts it. With systemd:
[Service]WorkingDirectory=/var/www/foresiExecStart=/usr/bin/php bin/console messenger:consume scheduler_foresi mail events async webhooks registry --memory-limit=256M --time-limit=3600Restart=alwaysRestartSec=5User=www-dataWith supervisor, use the same command with autorestart=true and stopwaitsecs=3600. On SQLite run exactly one worker (SQLite allows a single writer). Failed messages are retried three times (2 s, 8 s, 32 s) and then kept in the failed queue: inspect them with bin/console messenger:failed:show and retry with messenger:failed:retry. A message is redelivered if its handler runs longer than two hours (redeliver_timeout: 7200). The e2e environment has no worker and handles messages inline. Imports need the worker and two scheduled commands (app:import:purge, app:import:health); see docs/import.md. Sending invoices needs the mail and scheduler_foresi transports in the worker and MAIL_SECRET_KEYS; see docs/sending.md.
End-to-end tests
Section titled “End-to-end tests”Playwright tests in tests/e2e drive the real application in a browser: sign-in, the address book, keyboard use, accessibility (axe, WCAG 2.2 AA, zero serious or critical violations) and layout on a desktop (1440 px) and a mobile (390 px) viewport. They run in their own e2e environment with separate SQLite databases, one per world of tests/e2e/seed.php with one organisation each (var/e2e/<world>.db, recreated and seeded with example data by tests/e2e/serve.sh; a spec reaches its world through the sign-in helpers of tests/e2e/support/session.ts), and the registers (ARES, VIES, the unreliable payer register) are replaced by the same fixture-backed fakes the PHPUnit suite uses, so nothing calls the network. Your development database is never touched.
bin/console importmap:install # Stimulus and Turbo, git-ignored under assets/vendorbin/console tailwind:build # styles must be built oncecd tests/e2enpm cinpx playwright install chromiumnpx playwright test # everything, including the screenshot specsnpx playwright test --grep-invert @visual # what CI runs until the baselines are approvedScreenshot specs carry @visual in their title. A screen is captured as the viewport (the shell as a user sees it) and, for long pages, a second image of the main content only. The UI is shown in the default language (Czech). Candidates are written to tests/e2e/screenshots/<project>-<platform>/ (for example desktop-darwin, mobile-linux); the platform is part of the folder name. Only the Linux baselines are committed and checked; they are generated on Linux by the E2E workflow (update-snapshots). macOS images are local review candidates and are ignored by git. A screen’s baseline image is committed only after its look is approved; until then a run writes the candidates and reports “missing snapshot”. After approval, run npx playwright test --update-snapshots and commit the images.