Skip to content

The Plex appliance moves to Ubuntu 26.04 and asks for its folders over virtiofs - #24

Merged
eschultz merged 2 commits into
stagingfrom
feature/plex-virtiofs
Oct 9, 2026
Merged

eschultz merged 2 commits into
stagingfrom
feature/plex-virtiofs

Conversation

@eschultz

@eschultz eschultz commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

Not for catalog prod until a platform prod release carries eshtek/hexos-platform#2043. Staging is fine now: #2043 is merged there.

Summary

eshtek/hexos-platform#2043 adds a second way for the Plex appliance to read its folders. With virtiofs, the box hands each folder straight into the guest, with no network, shim or SMB password in the path. A blueprint asks for it with firstBoot.shareTransport: "virtiofs".

The platform chooses virtiofs only when all of these hold:

  • the box can run it (TrueNAS 25.04.2.6 or later);
  • the restricted vm-virtiofs feature is open for that server;
  • the profile is one that supports it (only plex-appliance today).

Otherwise it mounts over SMB as before. The capability the box reports, firstBootVirtiofs, is never required, so a platform that predates the field ignores it and installs over SMB.

Changes:

  • plex-server.json:
    • Moves Plex to Canonical's Ubuntu 26.04 cloud image (release-20260927, sha256 from that release's SHA256SUMS). Its stock 7.0 kernel lists large directories quickly over FUSE, which 24.04's 6.8 kernel does not, so the guest needs no newer kernel.
    • Sets shareTransport: "virtiofs".
  • _lib/contract.ts (tests in contract.test.ts): refuses shareTransport in three cases:
    • without a share list;
    • virtiofs on a profile the platform would quietly mount over SMB;
    • virtiofs with more than seven shares, the platform's limit of one QEMU device each.
  • Vendored schemas: re-vendored from platform staging@5af11a0d0 with bun run sync-schema. This also brings staging's app widget grammar (widgetsSchema 3, eshtek/hexos-platform#2058) into _lib/surface-grammar.ts, which nothing in this PR uses.
  • README and plex_setup.ts comments: updated for the new field.

What changes for users once this syncs: every new Plex install runs Ubuntu 26.04. Installs keep using SMB until vm-virtiofs is granted, and existing Plex VMs are not touched.

Test plan

  • bun run validate: 29 blueprints and 32 apps, 0 errors.
  • Hook and contract tests (bun run test-hooks): 81 pass.
  • bun run typecheck: the same 5 errors in the vendored vm-surfaces.ts as on staging, none from this PR.
  • Older platform, this catalog (TrueNAS 26.0.0-BETA.3 lab box): Plex on 26.04 installed over SMB end to end. The field was ignored, the CIFS mounts were read-only and readable, and 26.04's uutils coreutils ran the first-boot script and Plex's package scripts without trouble.
  • New platform, gate open: 15-vms/26-vm-virtiofs passed 9/9, including a host reboot, on TrueNAS 26.0.0-BETA.3, 25.10.7 and 25.04.2.6. It covers the virtiofs install of this blueprint, the guest mounting every folder, guest reboot, restart, folder guards, and the reboot-then-unlock path.
  • New platform, gate closed: the same spec's first test records the install over SMB.
  • After merge: sync to staging and install Plex once on a staging box with the gate closed.

…r virtiofs

The image is Canonical's 26.04 cloud image, release-20260927, with the sha256 from that release's
SHA256SUMS. Its stock kernel lists directories quickly over virtiofs, so the guest needs no newer
kernel installed at first boot.

firstBoot.shareTransport: "virtiofs" asks the box to share the folders straight into the guest.
A platform that cannot (or predates the field) ignores it and mounts over SMB, so the blueprint
requires no new capability. The contract refuses the field without a share list, virtiofs on a
profile that cannot take it, and more than seven shares over virtiofs.

The vendored schema was synced from the platform branch that adds the field; re-vendor from
staging once that lands.
@eschultz
eschultz merged commit 0cec737 into staging Oct 9, 2026
3 checks passed
@eschultz
eschultz deleted the feature/plex-virtiofs branch October 9, 2026 10:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant