package.nix: updated invoiceninja to v5.13.53

push-cache was only printing the main invoiceninja package's out path, so
the ui derivation (exposed via passthru.ui) never actually reached the
cachix cache even though it gets built as a dependency.

The new update target (scripts/update-versions.sh) checks GitHub for the
latest invoiceninja release and the latest invoiceninja/ui tag, bumps
whichever changed in package.nix, and iteratively rebuilds -- parsing
each hash-mismatch error Nix reports for a fixed-output derivation -- to
fill in the correct src/npmDeps/vendor hashes automatically.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

CLAUDE.md

@@ -34,23 +34,27 @@ This project uses `just` (see `justfile`) and Nix directly.
 - `default.nix` — the interactive VM config (`nixosConfigurations.test-nginx`/`test-caddy` in `flake.nix`), used
   for manual, click-around verification via `just build-vm [proxy]` / `just boot-vm`. It's also a function taking
   `{ proxyServer ? "nginx" }`, forwarded straight through to `common.nix`, so `flake.nix` can instantiate one
-  `nixosConfigurations` entry per proxy backend. Adds the qemu-guest profile, a root login, and
+  `nixosConfigurations` entry per proxy backend. Adds the qemu-guest profile and a root login. It also sets a
-  `nixpkgs.config.allowUnfree = true` (required to build `pkgs.chromium`). It also sets a dummy `fileSystems."/"`
+  dummy `fileSystems."/"` and disables `boot.loader.grub` purely to satisfy NixOS's built-in assertions when
-  and disables `boot.loader.grub` purely to satisfy NixOS's built-in assertions when `nix flake check` evaluates
+  `nix flake check` evaluates
   `config.system.build.toplevel` directly — the qemu-vm module overrides both with a tmpfs root and direct kernel
   boot when actually building `config.system.build.vm` (what `just build-vm` uses), so these values are otherwise
-  unused.
+  unused. Also raises `virtualisation.cores`/`memorySize` to 2/2560 (qemu-vm's defaults, 1 core/1024MB, are too
+  tight for real interactive use — see the module architecture notes below on PDF generation's memory cost).
 - `nixos-test.nix` — the automated test (`pkgs.testers.nixosTest`, exposed as `checks.<system>.invoiceninja` in
-  `flake.nix`). Builds its own `pkgs` (with `allowUnfree` baked in — `nixosTest` forbids setting `nixpkgs.config`
+  `flake.nix`). Builds its own `pkgs` externally (needed regardless of config, since `nixosTest` itself is called
-  on a node once `pkgs` is externally supplied) and boots two nodes from `common.nix` — one with
+  as `pkgs.testers.nixosTest`) and boots two nodes from `common.nix` — one with `proxyServer = "nginx"`, one with
-  `proxyServer = "nginx"`, one with `proxyServer = "caddy"` — so both proxy backends get exercised. The shared
+  `proxyServer = "caddy"` — so both proxy backends get exercised. The shared
   assertion suite (factored into a `check_invoiceninja(machine, proxy_unit)` function in the test script) runs
   against each node: waits for mysql/redis/phpfpm/queue-worker/proxy to be active, checks the
-  `invoiceninja-data-setup` marker files (`.initial-migration`, `.db-seeded`, `.admin-created`) to confirm the
+  `invoiceninja-data-setup` marker files (`.db-seeded`, `.admin-created`) to confirm the
   one-time setup actually completed (not just that the oneshot unit exited), curls `/` for the app shell, exercises
-  the `invoiceninja-manage` wrapper, and logs in via `/api/v1/login` using the test admin credentials as an
+  the `invoiceninja-manage` wrapper, logs in via `/api/v1/login` using the test admin credentials as an
-  end-to-end check that migrations/seeding/account creation all worked. This is the only automated test in the
+  end-to-end check that migrations/seeding/account creation all worked, checks the full language list is
-  repo — there is no separate unit-test suite.
+  available (see the `cache:forget languages` note above), and exercises PDF generation end-to-end (POSTs to
+  `/api/v1/preview` with no entity, which falls back to a self-contained mock PDF built via the same
+  chromium/snappdf pipeline real invoices use, and checks for the `%PDF` magic bytes — no client/invoice setup
+  needed). This is the only automated test in the repo — there is no separate unit-test suite.
 
 ## Architecture
 
@@ -95,8 +99,11 @@ expect Nix to report the correct hash on a failed build (or use `nix-prefetch`/`
     contents directly on disk in `dataDir`.
   - `invoiceninja-data-setup.service` (oneshot, runs on every activation) does all first-run and idempotent setup:
     clears bootstrap/opcode cache, rebuilds `.env`, rsyncs static storage into `dataDir`, symlinks the runtime
-    `app.php`, and guards one-time actions (`migrate`, `db:seed`, admin account creation) behind marker files
+    `app.php`, runs `migrate --force` unconditionally on every activation (safe/idempotent — Laravel tracks
-    (`.initial-migration`, `.db-seeded`, `.admin-created`) in `dataDir`. `phpfpm-invoiceninja.service` and
+    applied migrations in the DB and only runs new ones; this must NOT be marker-gated, since a later invoiceninja
+    version upgrade can ship new migrations that need to run on an already-migrated install), and guards the
+    remaining one-time actions (`db:seed`, admin account creation) behind marker files (`.db-seeded`,
+    `.admin-created`) in `dataDir`. `phpfpm-invoiceninja.service` and
     `invoiceninja-queue-worker.service` both depend on it. It also unconditionally runs
     `invoiceninja-manage cache:forget languages` on every activation, working around an upstream bug: migration
     `2025_08_31_224356_additional_languages_af_ca_id.php` runs during `migrate` (before `db:seed`'s
@@ -122,8 +129,17 @@ expect Nix to report the correct hash on a failed build (or use `nix-prefetch`/`
     regardless of `Host`). When `hostname == "localhost"`, the caddy vhost adds `serverAliases` for
     `127.0.0.1:80`/`[::1]:80` too — otherwise visiting the VM via the IP literal instead of `localhost` matches no
     vhost and Caddy silently returns an empty `200 OK` (a blank page with no error anywhere).
-  - Chromium is required at runtime for PDF generation (`PDF_GENERATOR=snappdf`, `SNAPPDF_CHROMIUM_PATH`) and is
+  - A headless browser is required at runtime for PDF generation (`PDF_GENERATOR=snappdf`,
-    added to the PHP-FPM and data-setup services' `path`.
+    `SNAPPDF_CHROMIUM_PATH`) and is added to the PHP-FPM and data-setup services' `path`. This is
+    `nixpkgs.playwright-driver`'s `chromium-headless-shell` component (Google's official "Chrome for Testing"
+    headless-only build, selected via `playwright-driver.browsers.override { ... }` with every other
+    browser/ffmpeg disabled) rather than `pkgs.chromium` — snappdf only ever shells out to
+    `$SNAPPDF_CHROMIUM_PATH --headless --print-to-pdf=...`, so the full browser UI/GPU stack `pkgs.chromium` ships
+    is dead weight; the headless-shell closure is ~1.45GB smaller and needs no `allowUnfree`. Each PDF request
+    still launches a full instance of the underlying browser engine (not a lightweight renderer), and PHP-FPM's
+    default `pm.max_children = 8` means up to 8 of these can run concurrently — on a memory-constrained deployment
+    this can exhaust RAM (confirmed: even a couple of concurrent PDF requests OOM-killed a 1024MB VM). Size
+    deployments accordingly, or lower `phpfpm.settings."pm.max_children"`.
 
 ### `flake.nix`
 

flake.nix

@@ -1,6 +1,13 @@
 {
   description = "An Invoice Ninja package and module.";
 
+  nixConfig = {
+    extra-substituters = [ "https://invoiceninja-nixos.cachix.org" ];
+    extra-trusted-public-keys = [
+      "invoiceninja-nixos.cachix.org-1:TmRZaji8FFVjjIw9KZmvLrxMxfP+JDThOyOX04z526A="
+    ];
+  };
+
   inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
 
   outputs =

justfile

@@ -36,3 +36,17 @@ boot-vm:
 test:
     nix flake check -L
 
+[doc('Update invoiceninja and ui to their latest upstream versions, recomputing hashes')]
+[group('maintenance')]
+update:
+    ./scripts/update-versions.sh
+
+[doc('Build the package and automated test, then push results to the invoiceninja-nixos cachix cache')]
+[group('maintenance')]
+push-cache:
+    nix build --print-out-paths --no-link \
+        ".#invoiceninja" \
+        ".#invoiceninja.ui" \
+        ".#checks.x86_64-linux.invoiceninja" \
+        | cachix push invoiceninja-nixos
+

nixos-module/invoiceninja.nix

@@ -47,8 +47,22 @@ let
     extraConfig = "memory_limit = 1024M";
   };
 
-  # Chromium is required for PDF invoice generation
+  # A headless browser is required for PDF invoice generation (PDF_GENERATOR=snappdf). snappdf
-  chromium = pkgs.chromium;
+  # just shells out to `$SNAPPDF_CHROMIUM_PATH --headless --print-to-pdf=... <url>`, so a full
+  # browser UI/GPU stack isn't needed -- Google's own "Chrome for Testing" headless-only build
+  # (as packaged by nixpkgs' playwright-driver) does the same job for a ~1.45GB smaller closure
+  # than pkgs.chromium, with no allowUnfree requirement.
+  chromiumHeadlessShellBrowsers = pkgs.playwright-driver.browsers.override {
+    withChromium = false;
+    withFirefox = false;
+    withWebkit = false;
+    withFfmpeg = false;
+    withChromiumHeadlessShell = true;
+  };
+  chromium = pkgs.runCommand "chromium-headless-shell" { } ''
+    mkdir -p $out/bin
+    ln -s ${chromiumHeadlessShellBrowsers}/chromium_headless_shell-*/chrome-headless-shell-linux64/chrome-headless-shell $out/bin/chromium
+  '';
   extraPrograms = [ chromium ];
 
   # Management script
@@ -486,7 +500,6 @@ in
 
       recommendedTlsSettings = (if (cfg.hostname == "localhost") then false else true);
       recommendedGzipSettings = true;
-      recommendedProxySettings = true;
       recommendedOptimisation = true;
 
       clientMaxBodySize = cfg.maxUploadSize;
@@ -689,8 +702,11 @@ in
         # We cannot link the cache folder only because bootstrap folder needs to be writeable.
         ln -sf ${invoiceninja}/bootstrap-static/app.php ${cfg.runtimeDir}/app.php
 
-        # Perform the first migration
+        # Run migrations on every activation, not just the first: `migrate` is idempotent
-        [[ ! -f ${cfg.dataDir}/.initial-migration ]] && invoiceninja-manage migrate --force && touch ${cfg.dataDir}/.initial-migration
+        # (Laravel tracks applied migrations in the DB and only runs new ones), and gating this
+        # behind a marker file meant migrations shipped by a later invoiceninja version upgrade
+        # would never run.
+        invoiceninja-manage migrate --force
 
         # Seed database with records
         # Necessary for languages, currencies, countries, etc.

package.nix

@@ -1,7 +1,9 @@
-{ buildNpmPackage
+{ lib
+, buildNpmPackage
 , npmHooks
 , fetchFromGitHub
 , fetchNpmDeps
+, jq
 , php82
 , nodejs_22
 , npm-lockfile-fix
@@ -12,13 +14,13 @@
 let
   pname = "invoiceninja";
 
-  version = "5.13.19";
+  version = "5.13.53";
   src = fetchFromGitHub {
     name = "${pname}";
     owner = pname;
     repo = pname;
     rev = "v${version}";
-    hash = "sha256-pvZNTiGGX6OqOEqcDrDqqpLD1Ohc/TA4nIRjm2jEp74=";
+    hash = "sha256-KQMb1W2S1YrRZOgjV3NPDpQaz5BbF/xtziNFd34wvxo=";
 
     postFetch = ''
       # add missing integrity fields to lockfile
@@ -26,13 +28,13 @@ let
     '';
   };
 
-  uiVersion = "03.05.2026.1";
+  uiVersion = "18.10.2026.1";
   uiSrc = fetchFromGitHub {
     name = "${pname}-ui";
     owner = pname;
     repo = "ui";
     tag = uiVersion;
-    hash = "sha256-BTaWNHTE+9NvavUYs56DdJHmqXy36N5k/crj3rU2Npg=";
+    hash = "sha256-56szHmIWU9De04Orykp2RxrW0RV87JxB7Y1yvdrSJm4=";
 
     postFetch = ''
       # add missing integrity fields to lockfile
@@ -48,7 +50,7 @@ let
 
     nodejs = nodejs_22;
   
-    npmDepsHash = "sha256-JA5TfXeg7iHVjQdjeU6SSD2JFSLISad8hPowaR1roQw=";
+    npmDepsHash = "sha256-j5XocHvBfMvzNrkaVkTsck2+yPraYWrXQxAbf3EYfIk=";
 
     preConfigure = ''
       sed -i 's/VITE_IS_TEST=true/VITE_IS_TEST=false/' .env.example
@@ -72,13 +74,16 @@ php82.buildComposerProject (finalAttrs: {
   inherit src version;
   pname = "${pname}-composer";
 
+  passthru.ui = ui;
+
   nativeBuildInputs = [
+    jq
     nodejs_22
     npmHooks.npmConfigHook
     npmHooks.npmBuildHook
   ];
 
-  vendorHash = "sha256-2CyWKlyCyoCt/WdY7Ta0oEXW2KIkGwhilHtzpBJ5Wnk=";
+  vendorHash = "sha256-sFpfnCt8jv8z9cLoFE8utPQiGz7q/KkqUXabEhcJP3M=";
 
   # Upstream composer.json has invalid license, webpatser/laravel-countries package is pointing
   # to commit-ref, and php required in require and require-dev
@@ -89,7 +94,7 @@ php82.buildComposerProject (finalAttrs: {
   npmDeps = fetchNpmDeps {
     name = "${pname}-${version}-npm-deps";
     inherit src;
-    hash = "sha256-WCadsQVj9eusYWJEOaEp5DIkVcbmPFGe6bmKi9NZDDg=";
+    hash = "sha256-ditAbluBzs5OV/fCMV5Q4w1amao6ofOlee4YXMpZ37I=";
   };
 
   preConfigure = ''
@@ -103,6 +108,17 @@ php82.buildComposerProject (finalAttrs: {
     # Remove JS/CSS build artifacts
     rm -rf $out/node_modules
 
+    # composer.lock and vendor/composer/installed.json record each package's "dist.url" as the
+    # store path of the composer-repository mirror it was installed from, which otherwise drags
+    # that whole (500+MB) fixed-output derivation into the runtime closure for no reason -- it's
+    # provenance metadata, not something Laravel's package manifest (which only reads
+    # name/extra) or Composer\InstalledVersions (which reads vendor/composer/installed.php, not
+    # this file) consult at runtime.
+    jq '(.packages[]?.dist.url) |= "removed"' $out/vendor/composer/installed.json > $out/vendor/composer/installed.json.tmp
+    mv $out/vendor/composer/installed.json.tmp $out/vendor/composer/installed.json
+    jq '(.packages[]?.dist.url, .["packages-dev"][]?.dist.url) |= "removed"' $out/composer.lock > $out/composer.lock.tmp
+    mv $out/composer.lock.tmp $out/composer.lock
+
     rm -r $out/bootstrap/cache
     rm -rf $out/public/storage
 

scripts/update-versions.sh

@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+# Bumps invoiceninja/package.nix to the latest upstream invoiceninja and
+# invoiceninja/ui versions, then rebuilds repeatedly -- using the
+# "specified vs. got" hash mismatch that Nix reports for each
+# fixed-output derivation -- to fill in the correct src/npmDeps/vendor
+# hashes. Invoked via `just update`.
+set -euo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+
+pkg=package.nix
+
+# Replaces the RHS (between the first "=" and the last ";") of the line
+# immediately following the first line containing $anchor.
+set_after() {
+  local file="$1" anchor="$2" newrhs="$3"
+  awk -v anchor="$anchor" -v newrhs="$newrhs" '
+    {
+      if (found) {
+        sub(/=.*;/, "= " newrhs ";")
+        found = 0
+      }
+      if (index($0, anchor) > 0) found = 1
+      print
+    }
+  ' "$file" > "${file}.tmp"
+  mv "${file}.tmp" "$file"
+}
+
+# Replaces the RHS of the first line assigning to $field. Only the first
+# match is touched -- "version" is assigned twice in package.nix (the
+# top-level invoiceninja version, and buildNpmPackage's own "version"
+# attribute for the ui derivation, which must stay "= uiVersion;") and the
+# top-level one always comes first.
+set_field() {
+  local file="$1" field="$2" newrhs="$3"
+  awk -v field="$field" -v newrhs="$newrhs" '
+    {
+      if (!done && $0 ~ "^[[:space:]]*" field "[[:space:]]*=") {
+        sub(/=.*;/, "= " newrhs ";")
+        done = 1
+      }
+      print
+    }
+  ' "$file" > "${file}.tmp"
+  mv "${file}.tmp" "$file"
+}
+
+current_main_version=$(grep -m1 -E '^\s*version = "' "$pkg" | sed -E 's/.*"([^"]+)".*/\1/')
+current_ui_version=$(grep -m1 -E '^\s*uiVersion = "' "$pkg" | sed -E 's/.*"([^"]+)".*/\1/')
+
+echo "Current: invoiceninja=$current_main_version ui=$current_ui_version"
+
+latest_main_version=$(curl -sf https://api.github.com/repos/invoiceninja/invoiceninja/releases/latest | jq -r '.tag_name' | sed 's/^v//')
+
+# invoiceninja/ui has no GitHub Releases, just date-stamped tags
+# (DD.MM.YYYY.N) -- paginate through all tags and pick the newest by
+# calendar date, ignoring "-release" hotfix tags and other one-off tag
+# names that don't fit that scheme.
+ui_tags=""
+page=1
+while :; do
+  batch=$(curl -sf "https://api.github.com/repos/invoiceninja/ui/tags?per_page=100&page=${page}" | jq -r '.[].name')
+  [ -z "$batch" ] && break
+  ui_tags="${ui_tags}
+${batch}"
+  page=$((page + 1))
+done
+
+latest_ui_version=$(printf '%s\n' "$ui_tags" \
+  | grep -E '^[0-9]{2}\.[0-9]{2}\.[0-9]{4}\.[0-9]+$' \
+  | awk -F. '{printf "%s%02d%02d%s %s\n", $3, $2, $1, $4, $0}' \
+  | sort \
+  | tail -1 \
+  | awk '{print $2}')
+
+if [ -z "$latest_main_version" ] || [ -z "$latest_ui_version" ]; then
+  echo "error: failed to determine latest versions (main=$latest_main_version ui=$latest_ui_version)" >&2
+  exit 1
+fi
+
+echo "Latest:  invoiceninja=$latest_main_version ui=$latest_ui_version"
+
+main_changed=0
+ui_changed=0
+
+if [ "$latest_main_version" != "$current_main_version" ]; then
+  main_changed=1
+  set_field "$pkg" version "\"$latest_main_version\""
+fi
+
+if [ "$latest_ui_version" != "$current_ui_version" ]; then
+  ui_changed=1
+  set_field "$pkg" uiVersion "\"$latest_ui_version\""
+fi
+
+if [ "$main_changed" = 0 ] && [ "$ui_changed" = 0 ]; then
+  echo "Already up to date."
+  exit 0
+fi
+
+# Invalidate every hash that could have changed as a result of the version
+# bump(s) above, so the rebuild loop below reports the real ones.
+if [ "$main_changed" = 1 ]; then
+  set_after "$pkg" 'rev = "v${version}";' 'lib.fakeHash'
+  set_after "$pkg" 'inherit src;' 'lib.fakeHash'
+  set_field "$pkg" vendorHash 'lib.fakeHash'
+fi
+
+if [ "$ui_changed" = 1 ]; then
+  set_after "$pkg" 'tag = uiVersion;' 'lib.fakeHash'
+  set_field "$pkg" npmDepsHash 'lib.fakeHash'
+fi
+
+echo "Rebuilding to discover the correct hashes (this takes a few iterations)..."
+
+max_iterations=10
+for ((i = 1; i <= max_iterations; i++)); do
+  echo "--- build attempt $i/$max_iterations ---"
+  set +e
+  build_output=$(nix build ".#invoiceninja" ".#invoiceninja.ui" --no-link -L 2>&1)
+  status=$?
+  set -e
+
+  if [ "$status" -eq 0 ]; then
+    echo "Build succeeded."
+    exit 0
+  fi
+
+  mismatch_line=$(printf '%s\n' "$build_output" | grep -m1 "hash mismatch in fixed-output derivation" || true)
+  if [ -z "$mismatch_line" ]; then
+    echo "$build_output" | tail -80
+    echo "error: build failed for a reason other than a hash mismatch; see output above" >&2
+    exit 1
+  fi
+
+  drv_path=$(printf '%s\n' "$mismatch_line" | sed -E "s/.*'([^']+)'.*/\1/")
+  # Store paths are "<32-char hash>-<name>"; strip the hash to get the name.
+  name=$(basename "$drv_path" .drv | sed -E 's/^[0-9a-z]{32}-//')
+  got_hash=$(printf '%s\n' "$build_output" | grep -m1 -E '^\s+got: ' | awk '{print $2}')
+
+  if [ -z "$got_hash" ]; then
+    echo "$build_output" | tail -80
+    echo "error: could not parse the correct hash out of the build output above" >&2
+    exit 1
+  fi
+
+  echo "Fixing hash for '$name': $got_hash"
+
+  case "$name" in
+    invoiceninja)
+      set_after "$pkg" 'rev = "v${version}";' "\"$got_hash\""
+      ;;
+    invoiceninja-ui)
+      set_after "$pkg" 'tag = uiVersion;' "\"$got_hash\""
+      ;;
+    invoiceninja-ui-*-npm-deps)
+      set_field "$pkg" npmDepsHash "\"$got_hash\""
+      ;;
+    invoiceninja-composer-composer-repository-*)
+      set_field "$pkg" vendorHash "\"$got_hash\""
+      ;;
+    invoiceninja-*-npm-deps)
+      set_after "$pkg" 'inherit src;' "\"$got_hash\""
+      ;;
+    *)
+      echo "error: unrecognized derivation '$name' in hash mismatch; don't know which field to update" >&2
+      exit 1
+      ;;
+  esac
+done
+
+echo "error: exceeded $max_iterations build attempts without resolving all hash mismatches" >&2
+exit 1

tests/default.nix

@@ -4,12 +4,12 @@
 {
   imports = [
     (modulesPath + "/profiles/qemu-guest.nix")
+    # Not imported by default for a plain nixosSystem in this nixpkgs (only nixosTest nodes get it
+    # automatically) - needed explicitly so virtualisation.cores/memorySize below are real options.
+    (modulesPath + "/virtualisation/qemu-vm.nix")
     (import ./common.nix { inherit proxyServer; })
   ];
 
-  # Required to build pkgs.chromium, which the module pulls in for PDF generation.
-  nixpkgs.config.allowUnfree = true;
-
   # `nix flake check` evaluates config.system.build.toplevel directly, which asserts a real root
   # filesystem and bootloader are configured. `just build-vm` builds config.system.build.vm
   # instead, where the qemu-vm module overrides both of these with a tmpfs root and direct
@@ -26,4 +26,27 @@
   };
 
   services.resolved.enable = true;
+
+  # `just boot-vm` forwards the guest's port 80 to host port 8080 (QEMU_NET_OPTS in the justfile),
+  # but the backend builds absolute URLs (e.g. the stored company logo path) from APP_URL, which
+  # defaults to plain "http://localhost" with no port. The SPA's own relative URLs are fine (they
+  # inherit whatever port the browser is already on), but any backend-generated absolute URL then
+  # points at host port 80 - where nothing is listening - instead of the forwarded 8080, giving a
+  # silent net::ERR_CONNECTION_REFUSED for things like the logo image. Override to match the actual
+  # forwarded port.
+  services.invoiceninja.settings.APP_URL = "http://localhost:8080";
+
+  # The qemu-vm module's defaults (1 core, 1024MB) are too tight for real interactive use: MySQL +
+  # Redis + PHP-FPM + chromium (PDF generation, spawned per request - each is a full multi-process
+  # browser, not a lightweight renderer) running concurrently can exhaust 1GB fast, and this VM
+  # boots with panic_on_oom - so it's not a graceful slowdown, the whole VM goes down. Confirmed by
+  # reproducing a "logo upload hangs" report this way: at the 1024MB default, even a couple of
+  # concurrent PDF-generation requests triggered `redis-server invoked oom-killer` and a kernel
+  # panic. 2 cores / 2560MB comfortably handles 2 concurrent PDF generations alongside normal
+  # traffic (verified: ~1.4GB still free afterward); a deliberate flood of many concurrent PDF
+  # requests can still exhaust even this, since each is a full chromium instance - if that's a
+  # concern for your deployment, consider capping `phpfpm.settings."pm.max_children"` below its
+  # default of 8, or provisioning more RAM.
+  virtualisation.cores = 2;
+  virtualisation.memorySize = 2560;
 }

tests/nixos-test.nix

@@ -1,13 +1,7 @@
 { nixpkgsPath, system }:
 
 let
-  # nixosTest forbids setting `nixpkgs.config` on a node once `pkgs` is externally supplied,
+  pkgs = import nixpkgsPath { inherit system; };
-  # so allowUnfree (required to build pkgs.chromium) has to be baked into this pkgs instance
-  # up front rather than set from within common.nix like the interactive VM does.
-  pkgs = import nixpkgsPath {
-    inherit system;
-    config.allowUnfree = true;
-  };
 
   adminEmail = "admin@email.com";
   adminPassword = pkgs.lib.strings.trim (builtins.readFile ./invoice_ninja_test_password);
@@ -23,6 +17,18 @@ pkgs.testers.nixosTest {
   testScript = ''
     import json
 
+    def api_get(machine, path, token):
+        return json.loads(machine.succeed(f"curl -sf http://localhost{path} -H 'X-API-TOKEN: {token}'"))
+
+    def api_post(machine, path, payload, token=None):
+        auth_header = f"-H 'X-API-TOKEN: {token}' " if token else ""
+        return json.loads(machine.succeed(
+            f"curl -sf -X POST http://localhost{path} "
+            + auth_header
+            + "-H 'Content-Type: application/json' "
+            + f"-d '{json.dumps(payload)}'"
+        ))
+
     def check_invoiceninja(machine, proxy_unit):
         machine.wait_for_unit("mysql.service")
         machine.wait_for_unit("redis-invoiceninja.service")
@@ -33,9 +39,10 @@ pkgs.testers.nixosTest {
 
         # phpfpm-invoiceninja/invoiceninja-queue-worker both Require= invoiceninja-data-setup,
         # so systemd already waited for it to finish above. Confirm the one-time setup steps
-        # it guards actually completed, rather than just that the unit exited.
+        # it guards actually completed, rather than just that the unit exited. (Migrations run
-        with subtest("one-time setup (migrate, seed, admin account) completed"):
+        # unconditionally on every activation rather than being marker-gated, so there's no
-            machine.succeed("test -f /var/lib/invoiceninja/.initial-migration")
+        # marker file to check for them here.)
+        with subtest("one-time setup (seed, admin account) completed"):
             machine.succeed("test -f /var/lib/invoiceninja/.db-seeded")
             machine.succeed("test -f /var/lib/invoiceninja/.admin-created")
 
@@ -60,12 +67,9 @@ pkgs.testers.nixosTest {
             machine.succeed("systemctl start --wait invoiceninja-scheduler.service")
 
         with subtest("admin account can log in via the API"):
-            login_response = machine.succeed(
+            login_response = api_post(machine, "/api/v1/login", {"email": "${adminEmail}", "password": "${adminPassword}"})
-                "curl -sf -X POST http://localhost/api/v1/login "
+            assert "${adminEmail}" in json.dumps(login_response), f"login did not succeed: {login_response}"
-                + "-H 'Content-Type: application/json' "
+            token = login_response["data"][0]["token"]["token"]
-                + "-d '{\"email\":\"${adminEmail}\",\"password\":\"${adminPassword}\"}'"
-            )
-            assert "${adminEmail}" in login_response, f"login did not succeed: {login_response}"
 
         with subtest("full language list is available, not just the af/ca/id migration's 3"):
             # Regression check: migration 2025_08_31_224356_additional_languages_af_ca_id.php runs
@@ -73,13 +77,50 @@ pkgs.testers.nixosTest {
             # does Cache::forever('languages', Language::all()) - permanently caching just the 3
             # languages it sees at that moment. invoiceninja-data-setup works around this with
             # `invoiceninja-manage cache:forget languages`; this confirms the workaround is in place.
-            token = json.loads(login_response)["data"][0]["token"]["token"]
+            language_count = len(api_get(machine, "/api/v1/statics", token)["languages"])
-            statics = machine.succeed(
-                f"curl -sf http://localhost/api/v1/statics -H 'X-API-TOKEN: {token}'"
-            )
-            language_count = len(json.loads(statics)["languages"])
             assert language_count > 40, f"expected ~45 languages, got {language_count}"
 
+        with subtest("PDF generation works (chromium/snappdf)"):
+            # /api/v1/preview with no entity falls back to a self-contained mock PDF (no invoice/client
+            # setup needed), exercising the same chromium/snappdf pipeline real invoice PDFs use.
+            # This fallback only triggers when the company has no invoices/invitations at all yet
+            # (PreviewController::blankEntity), so this must run before the client/invoice/payment
+            # subtest below creates one.
+            machine.succeed(
+                "curl -sf -X POST http://localhost/api/v1/preview "
+                + f"-H 'X-API-TOKEN: {token}' -H 'Content-Type: application/json' "
+                + "-d '{}' -o /tmp/preview.pdf"
+            )
+            magic_bytes = machine.succeed("head -c 4 /tmp/preview.pdf")
+            assert magic_bytes == "%PDF", f"expected a PDF, got: {magic_bytes!r}"
+
+        with subtest("a client can be created, invoiced, and pay that invoice in full"):
+            client = api_post(machine, "/api/v1/clients", {"name": "Test Client"}, token)["data"]
+
+            invoice = api_post(machine, "/api/v1/invoices", {
+                "client_id": client["id"],
+                "line_items": [
+                    {"quantity": 1, "cost": 100, "product_key": "test-product", "notes": "test line item"},
+                ],
+            }, token)["data"]
+            assert invoice["amount"] == 100, f"unexpected invoice amount: {invoice}"
+
+            # Mirrors the normal workflow of sending an invoice to a client before it's paid,
+            # rather than relying on the fact that draft invoices also happen to be payable.
+            api_get(machine, f"/api/v1/invoices/{invoice['id']}/mark_sent", token)
+
+            payment = api_post(machine, "/api/v1/payments", {
+                "client_id": client["id"],
+                "amount": invoice["amount"],
+                "invoices": [{"invoice_id": invoice["id"], "amount": invoice["amount"]}],
+            }, token)["data"]
+            assert payment["applied"] == invoice["amount"], f"payment not fully applied: {payment}"
+
+            paid_invoice = api_get(machine, f"/api/v1/invoices/{invoice['id']}", token)["data"]
+            # status_id 4 == STATUS_PAID
+            assert paid_invoice["status_id"] == "4", f"invoice not marked paid: {paid_invoice}"
+            assert paid_invoice["balance"] == 0, f"invoice balance not zero: {paid_invoice}"
+
 
     nginx.start()
     caddy.start()