The serve.zone test harness qualifies native NoSQLDB persistence and provides a real SmartVPN networking scenario for an isolated Linux VM. Cross-repository Swarm and BaseOS scenarios remain separate migration coverage while Pallet/containerd execution is implemented.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Purpose

Component repositories own their unit tests; this repository owns cross-component and privileged qualification. Missing prerequisites fail the modern qualification run. Passing the storage and network suites does not certify the complete platform or a Pallet workload executor.

Modern Qualification

Install the harness dependencies and run the unprivileged checks with Node.js 22 or newer:

pnpm install
pnpm build
pnpm test

pnpm build strictly type-checks the modern harness and its tests, then bundles a standalone Node executable in dist/network.cjs. The Node-specific artifact uses esbuild because tsbundle targets browsers. Dependencies and MIT notices are bundled; no host workspace or node_modules tree is copied to the VM.

pnpm test runs tstest with inspectable logs under .nogit/testlogs/. It starts a real native NoSQLDB 8.0.0 server on loopback with an OS-assigned port and disposable file-backed state. Application access uses SmartData 11.12.0; no MongoDB server or direct driver operations are used. Tests write state, close the client, restart the engine, reopen through a fresh client, verify recovery, and assert that state is removed only after confirmed native stop. A failed stop retains its exact root for diagnosis.

Real Linux Network Scenario

The privileged scenario requires the dedicated servezone-testing VM, root, a full KVM/QEMU/VirtualBox guest, /dev/net/tun, ip, sysctl, curl, and Node.js 22. On the host, Vagrant, a configured provider, and OpenSSH scp must be available. Select an explicit, regular executable SmartVPN Linux binary and its SHA-256; no local package linking or unpublished consumer dependency is involved.

pnpm vagrant:up
pnpm vagrant:test /absolute/path/to/smartvpn_daemon_linux_amd64 <sha256>
# Both unprivileged and privileged modern suites:
pnpm test:full /absolute/path/to/smartvpn_daemon_linux_amd64 <sha256>
vagrant halt

The runner checks the candidate digest on both sides, transfers only two individual artifacts into a unique VM /tmp directory, and waits for scenario cleanup. Successful runs remove those exact artifacts. Failed runs retain staging and print its location; namespace failures identify the exact owned szn-<run>- prefix. Inspect retained owners before deleting anything. The runner never starts or provisions a VM implicitly.

Four network namespaces represent a hub and three nodes. Each node can reach only the hub; the hub kernel cannot forward packets. Real native SmartVPN daemons, WebSocket/Noise transport, TUN devices, and HTTP probes verify:

Explicit workload-domain grants permit traffic; missing grants deny it.
Only remote workload prefixes are routed, never the node's own prefixes or a replacement default route.
Disconnect/reconnect recovers traffic; revocation naturally clears the assignment and releases client routes without an explicit disconnect. Server-driven WS retirement may report a terminal transport error rather than a graceful disconnected state; both require actual kernel cleanup.
A conflicting later route fails partial setup, preserves the conflicting route, and releases earlier routes and the TUN.
Authority restart starts empty and rejects clients until its caller reapplies a snapshot.
Confirmed child termination releases the TUN and routes; cleanup joins owned children before deleting namespaces.
VM DNS and IPv4/IPv6 default routes remain unchanged. Exact route restoration covers IPv4, the managed runtime's current address family; unrelated IPv6 link-local autoconfiguration is not treated as a managed route.

This is WS/Noise, not WSS qualification. The current candidate trusts public WebPKI roots and does not expose private-CA configuration. Genuine WSS testing needs an upstream trust capability or a genuinely trusted isolated endpoint; this harness does not disable TLS verification. IPv6 workload transport, Pallet containerd execution, scheduling, ingress, and full rollout/recovery are not qualified here yet. Add assertions against their real implementations, not success-reporting substitutes.

Clients launch directly with an inherited network namespace descriptor; the candidate must support --network-namespace-fd in stdio client mode. Namespace handles remain caller-owned until the joined child shutdown. Parent links, IPv4 and IPv6 routes, and DNS are checked after cleanup.

Offline QEMU network qualification

test/native/offline-network.py runs the same scenario in a disposable Linux 6.18.35-0-virt initramfs with no NIC, disks or host mounts. It needs local matching kernel, veth.ko and tun.ko, static BusyBox, Node 22, a built dist/network.cjs, and the explicit SmartVPN candidate. The Linux amd64 host supplies QEMU/KVM, cpio, iproute2 and the listed shared-library closure. No guest download is performed.

python3 test/native/offline-network.py \
  --kernel /absolute/vmlinuz-virt --busybox /absolute/busybox \
  --node /absolute/node --veth-module /absolute/veth.ko --tun-module /absolute/tun.ko \
  --bundle dist/network.cjs --native-binary /absolute/smartvpn_daemon \
  --work-root /tmp/servezone-network-qualification-run

The launcher records and checks asset hashes, bounds guest execution, joins QEMU shutdown and writes inputs.json, qualification.log and result.json beneath the requested temporary directory. The offline preflight requires the exact kernel, boot marker, environment mode and dedicated hostname. It uses a bounded Node HTTP probe; the Vagrant path keeps its existing virtualization and curl checks. A passing result establishes the tested binary and kernel combination.

When archiving or distributing a SmartVPN candidate, retain its source revision, checksum, upstream license.md, third-party-notices.md, notices/ and assets/third-party-licenses.md alongside the binary. A local candidate pass is not a published release.

Explicit Swarm and BaseOS Migration Scenarios

These existing scenarios are retained, not included in the modern default suite, and not certified by a modern qualification pass. They still depend on sibling source repositories and historical runtime contracts. In particular, the App Store and QEMU enrollment scenarios need further contract updates before they can certify the current platform. Do not use them as a clean-state or Pallet readiness claim.

Scenario	Command	What it validates
`codebase-regressions`	`pnpm scenario:codebase-regressions`	Static cross-package regression checks for security defaults, registry/image stream fixes, app catalog schema/templates, deployment runtime hooks, package metadata, and ContainerArchive prune safety.
`corestore-volume-driver`	`pnpm scenario:corestore-volume-driver`	Corestore control API, Docker VolumeDriver protocol, snapshot/restore through `containerarchive`, Coreflow volume mount generation, backup/restore orchestration, and remote replication against a fake Cloudly API.
`registry-deploy-on-push`	`pnpm scenario:registry-deploy-on-push`	Cloudly startup with native NoSQLDB/S3 fixtures, cluster and registry setup, Docker image push, Cloudly metadata update, Coreflow workload provisioning, Coretraffic HTTPS routing, and same-tag redeploy after digest changes. The NoSQLDB fixture is qualified separately; this complete Swarm flow has not been requalified.
`onebox-basic-lifecycle`	`pnpm scenario:onebox-basic-lifecycle`	Onebox startup in dev mode, SmartProxy ingress, local registry status, workload deploy/remove, persisted service volumes, raw published ports, HTTP route check, and HTTPS route check with a temporary certificate.
`onebox-backup-restore`	`pnpm scenario:onebox-backup-restore`	Onebox service backup creation through ContainerArchive, image-in-backup metadata, clone restore, environment and volume preservation, and cleanup.
`onebox-cloudly-appstore-worker`	`pnpm scenario:onebox-cloudly-appstore-worker`	Historical Cloudly App Store installation, env template resolution, worker bootstrap route, and platform-resource backup/restore assertions. Resource names/contracts still require modernization; never provision an actual MongoDB server to satisfy old assertions.
`baseos-image-pipeline`	`pnpm scenario:baseos-image-pipeline`	CoreBuild BaseOS raw-image job API, S3 artifact upload, Raspberry Pi image customization, WiFi config, SSH key injection, and baserunner environment generation.
`baseos-qemu-enrollment`	`pnpm scenario:baseos-qemu-enrollment`	Historical BaseOS registration smoke against a mock Cloudly endpoint; requires `BASEOS_QEMU_IMAGE`. Its existing missing-image skip is not qualification.

pnpm test:swarm explicitly selects the six non-BaseOS migration scenarios, including the App Store worker scenario. It mutates Docker resources and must run only in an intentionally prepared disposable environment.

Migration Suite Prerequisites

Node.js 22-compatible runtime and pnpm.
Deno where required by the selected sibling revision and BaseOS scenarios.
Docker with Swarm already active for Docker-backed scenarios.
openssl and curl for routing and certificate smoke checks.
qemu-img, guestfish, and xz for baseos-image-pipeline.

Prepare a separate checkout of the sibling repositories inside the disposable VM at /serve.zone before using the migration wrappers. No workspace synchronization is configured. Review the selected scenario and install its dependencies explicitly; bootstrap:components remains an opt-in cross-repository install command, never part of a modern qualification run.

pnpm bootstrap:components

Run the migration suite only in that prepared environment:

pnpm test:swarm

Run a single scenario:

pnpm scenario:corestore-volume-driver
pnpm scenario:registry-deploy-on-push
pnpm scenario:onebox-basic-lifecycle

Vagrant Provisioning

The included Vagrantfile creates an Ubuntu 24.04 VM with Node.js, Deno, pnpm, and network tools. All synced folders are disabled. Default provisioning does not install Docker, initialize Swarm, pull workload images, or modify sibling repositories. For an already prepared VM, vagrant up --no-provision boots without package changes.

# Only when explicitly preparing migration suites:
vagrant provision --provision-with swarm
vagrant provision --provision-with baseos
# Requires the independently prepared /serve.zone checkout:
pnpm vagrant:test:swarm
pnpm vagrant:test:baseos

The named Swarm provisioner installs Docker and initializes a local Swarm only when inactive. The named BaseOS provisioner adds image tooling and grants read access to this VM's running kernel for libguestfs. Neither runs automatically. vagrant:test:full aliases the modern test:full command and requires the same candidate arguments. pnpm vagrant:destroy deletes the VM; use vagrant halt to preserve it.

Useful environment variables:

Variable	Default	Purpose
`SERVEZONE_VAGRANT_BOX`	`bento/ubuntu-24.04`	Base VM image.
`SERVEZONE_VAGRANT_CPUS`	`4`	VM CPU count.
`SERVEZONE_VAGRANT_MEMORY`	`8192`	VM memory in MB.
`SERVEZONE_KEEP_TEST_ARTIFACTS`	unset	Keeps BaseOS image pipeline artifacts when set.

Safety Notes

Never run privileged or Docker-backed scenarios against production or a developer's active runtime. The VM/hostname preflight is accident prevention, not a security boundary against malicious artifacts.
Modern network mutations are confined to uniquely owned namespaces inside the VM. No host DNS or route edits are made.
Migration scenarios refuse selected known service collisions, but that is not comprehensive isolation. Their old cleanup behavior is not a substitute for the modern owned-resource checks.
Docker artifacts are labeled or named with scenario-specific smoke IDs where practical, then cleaned up in finally blocks.
Several scenarios change process environment variables temporarily and restore them afterward.
The harness is intentionally integration-heavy. A failing scenario often prints Docker service logs, task state, route responses, or artifact details before rethrowing.

Project Map

testing/
├── package.json
├── tsconfig.json
├── Vagrantfile
├── scripts/
│   ├── build-network.ts
│   ├── vagrant-network.ts
│   └── provision-{vm,swarm,baseos}.sh
├── ts/
│   ├── network.{cli,preflight,scenario}.ts
│   ├── classes.cleanup.ts
│   └── storage/classes.nosqldbfixture.ts
├── test/
│   ├── test.harness.node.ts
│   └── test.nosqldbfixture.node.ts
└── scenarios/
    ├── baseos-image-pipeline/
    ├── corestore-volume-driver/
    ├── onebox-backup-restore/
    ├── onebox-basic-lifecycle/
    ├── onebox-cloudly-appstore-worker/
    └── registry-deploy-on-push/

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@serve.zone/testing