nixos-module: run db migrations on every activation, not just once

The .initial-migration marker file prevented `migrate --force` from ever
running again after the first activation, so migrations shipped by a later
invoiceninja version upgrade would never apply to an already-deployed
instance. `migrate` is idempotent (Laravel tracks applied migrations in the
DB), so just run it unconditionally on every activation instead.

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
-  `nixpkgs.config.allowUnfree = true` (required to build `pkgs.chromium`). It also sets a dummy `fileSystems."/"`
-  and disables `boot.loader.grub` purely to satisfy NixOS's built-in assertions when `nix flake check` evaluates
+  `nixosConfigurations` entry per proxy backend. Adds the qemu-guest profile and a root login. It also sets a
+  dummy `fileSystems."/"` and disables `boot.loader.grub` purely to satisfy NixOS's built-in assertions when
+  `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`
-  on a node once `pkgs` is externally supplied) and boots two nodes from `common.nix` — one with
-  `proxyServer = "nginx"`, one with `proxyServer = "caddy"` — so both proxy backends get exercised. The shared
+  `flake.nix`). Builds its own `pkgs` externally (needed regardless of config, since `nixosTest` itself is called
+  as `pkgs.testers.nixosTest`) and boots two nodes from `common.nix` — one with `proxyServer = "nginx"`, one with
+  `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
-  end-to-end check that migrations/seeding/account creation all worked. This is the only automated test in the
-  repo — there is no separate unit-test suite.
+  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, checks the full language list is
+  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
-    (`.initial-migration`, `.db-seeded`, `.admin-created`) in `dataDir`. `phpfpm-invoiceninja.service` and
+    `app.php`, runs `migrate --force` unconditionally on every activation (safe/idempotent — Laravel tracks
+    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
-    added to the PHP-FPM and data-setup services' `path`.
+  - A headless browser is required at runtime for PDF generation (`PDF_GENERATOR=snappdf`,
+    `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`
 

nixos-module/invoiceninja.nix

@@ -47,8 +47,22 @@ let
     extraConfig = "memory_limit = 1024M";
   };
 
-  # Chromium is required for PDF invoice generation
-  chromium = pkgs.chromium;
+  # A headless browser is required for PDF invoice generation (PDF_GENERATOR=snappdf). snappdf
+  # 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
-        [[ ! -f ${cfg.dataDir}/.initial-migration ]] && invoiceninja-manage migrate --force && touch ${cfg.dataDir}/.initial-migration
+        # Run migrations on every activation, not just the first: `migrate` is idempotent
+        # (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.43";
   src = fetchFromGitHub {
     name = "${pname}";
     owner = pname;
     repo = pname;
     rev = "v${version}";
-    hash = "sha256-pvZNTiGGX6OqOEqcDrDqqpLD1Ohc/TA4nIRjm2jEp74=";
+    hash = "sha256-F8lEyVi2EFRnkxWSDRIqsqrKmtCEUEee8lDDUZXoo0c=";
 
     postFetch = ''
       # add missing integrity fields to lockfile
@@ -26,13 +28,13 @@ let
     '';
   };
 
-  uiVersion = "03.05.2026.1";
+  uiVersion = "28.09.2026.1";
   uiSrc = fetchFromGitHub {
     name = "${pname}-ui";
     owner = pname;
     repo = "ui";
     tag = uiVersion;
-    hash = "sha256-BTaWNHTE+9NvavUYs56DdJHmqXy36N5k/crj3rU2Npg=";
+    hash = "sha256-RLirh0Q5lhH2O7AEwoR4MdlELAgB00f9w6FfiBNhoho=";
 
     postFetch = ''
       # add missing integrity fields to lockfile
@@ -48,7 +50,7 @@ let
 
     nodejs = nodejs_22;
   
-    npmDepsHash = "sha256-JA5TfXeg7iHVjQdjeU6SSD2JFSLISad8hPowaR1roQw=";
+    npmDepsHash = "sha256-7Boz+o4pQkPNMJREWgUMeKQa7avChqd+GpZoaXO0LqE=";
 
     preConfigure = ''
       sed -i 's/VITE_IS_TEST=true/VITE_IS_TEST=false/' .env.example
@@ -73,12 +75,13 @@ php82.buildComposerProject (finalAttrs: {
   pname = "${pname}-composer";
 
   nativeBuildInputs = [
+    jq
     nodejs_22
     npmHooks.npmConfigHook
     npmHooks.npmBuildHook
   ];
 
-  vendorHash = "sha256-2CyWKlyCyoCt/WdY7Ta0oEXW2KIkGwhilHtzpBJ5Wnk=";
+  vendorHash = "sha256-zTo+unMIsv2XObjwiFpxTdUxVfZoXbMNviDrLMVMJI0=";
 
   # 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 +92,7 @@ php82.buildComposerProject (finalAttrs: {
   npmDeps = fetchNpmDeps {
     name = "${pname}-${version}-npm-deps";
     inherit src;
-    hash = "sha256-WCadsQVj9eusYWJEOaEp5DIkVcbmPFGe6bmKi9NZDDg=";
+    hash = "sha256-uHbvhf8EWOBiyPQ9ieA4ynIUkIXWJEXZ7ZVsr4NXWtU=";
   };
 
   preConfigure = ''
@@ -103,6 +106,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
 

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,
-  # 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;
-  };
+  pkgs = import nixpkgsPath { inherit system; };
 
   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.
-        with subtest("one-time setup (migrate, seed, admin account) completed"):
-            machine.succeed("test -f /var/lib/invoiceninja/.initial-migration")
+        # it guards actually completed, rather than just that the unit exited. (Migrations run
+        # unconditionally on every activation rather than being marker-gated, so there's no
+        # 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(
-                "curl -sf -X POST http://localhost/api/v1/login "
-                + "-H 'Content-Type: application/json' "
-                + "-d '{\"email\":\"${adminEmail}\",\"password\":\"${adminPassword}\"}'"
-            )
-            assert "${adminEmail}" in login_response, f"login did not succeed: {login_response}"
+            login_response = api_post(machine, "/api/v1/login", {"email": "${adminEmail}", "password": "${adminPassword}"})
+            assert "${adminEmail}" in json.dumps(login_response), f"login did not succeed: {login_response}"
+            token = login_response["data"][0]["token"]["token"]
 
         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"]
-            statics = machine.succeed(
-                f"curl -sf http://localhost/api/v1/statics -H 'X-API-TOKEN: {token}'"
-            )
-            language_count = len(json.loads(statics)["languages"])
+            language_count = len(api_get(machine, "/api/v1/statics", token)["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()