Getting Started

Requires Linux: OpenSwoole has no maintained FreeBSD/other-BSD port (openswoole/ext-openswoole#233).

Quick start (production-ish)

curl -O https://raw.githubusercontent.com/mbolli/nfsen-ng/master/deploy/docker-compose.yml
# edit NFSEN_SOURCES, NFSEN_NFDUMP_PROFILES, etc. in the compose file
docker compose --profile proxy up -d   # bundled Caddy, ports 80/443
# or: docker compose up -d             # app only, port 9000, behind your own proxy

Development

git clone https://github.com/mbolli/nfsen-ng
cd nfsen-ng
docker compose -f deploy/docker-compose.dev.yml up -d
docker compose -f deploy/docker-compose.dev.yml logs -f nfsen

The dev container runs the app under entr: any .php/.twig/.js/.css change under the mounted source stops the server, waits for its shutdown and starts it again: no manual restart, no build step. Its entrypoint, deploy/docker-entrypoint-dev.sh, also runs from the mounted source, so a change to it takes effect when docker compose up -d recreates the container, without an image rebuild. The dev state (preferences, alert rules and the SQLite store nfsen-ng.sqlite) lives in backend/settings/, next to the code, and is ignored by git.

The compose file’s commented-out nfcapd/nfcapd-test services can inject real (or softflowd-generated) traffic on ports 9995/9996 for local testing; without them the app still runs, just against whatever nfcapd files already exist under the mounted profiles-data volume.

Useful commands

composer install        # PHP deps
composer test            # Pest test suite
composer test-phpstan    # static analysis, level 8
composer fix              # auto-format PHP (php-cs-fixer)
composer before-commit   # fix + phpstan; run this before every PHP commit

pnpm install              # JS deps; copies ECharts
pnpm run lint             # Biome lint of frontend/js/components and frontend/css
pnpm run format           # Biome format --write
pnpm run test-e2e         # the browser suite against a running instance (BASE, CHROME)

php-via serves the Datastar bundle, so it is no npm dependency. ECharts, the Starbase components under frontend/js/starbase/ and the licence files are committed, so a checkout runs without pnpm install; see Project Structure and AGENTS.md for updating them.

See Project Structure for where things live, Testing for the test suite in more depth, and Environment Notes for sandbox-specific gotchas that have nothing to do with the app itself but will otherwise cost you an hour.