Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

test: add all-25 distro compatibility discovery

Juan Denis9a09a392cf93
diff --git a/.github/workflows/distro-compatibility-discovery.yml b/.github/workflows/distro-compatibility-discovery.yml
new file mode 100644
index 00000000..15a05090
--- /dev/null
+++ b/.github/workflows/distro-compatibility-discovery.yml
@@ -0,0 +1,43 @@
+name: Distro Compatibility Discovery
+
+# Broad, non-gating evidence run. Known incompatibilities must stay visible in
+# the uploaded report without preventing the remaining distro probes from
+# running. Promotion gates belong in Scripts CI once a matrix subset is green.
+on:
+ workflow_dispatch:
+ schedule:
+ - cron: '17 6 * * 1'
+
+jobs:
+ discover:
+ name: all 25 targets (container evidence)
+ runs-on: ubuntu-latest
+ timeout-minutes: 120
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Run exact and proxy image probes
+ run: >-
+ python3 scripts/test/distro-compatibility.py
+ --mode both
+ --jobs 4
+ --remove-images
+
+ - name: Publish report in the run summary
+ if: always()
+ run: |
+ report="$(find scripts/test/output/distro-compatibility -name report.md -type f | sort | tail -1)"
+ if [ -n "$report" ]; then
+ cat "$report" >> "$GITHUB_STEP_SUMMARY"
+ else
+ echo 'No compatibility report was produced.' >> "$GITHUB_STEP_SUMMARY"
+ fi
+
+ - name: Upload detailed evidence
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: distro-compatibility-report
+ path: scripts/test/output/distro-compatibility/
+ if-no-files-found: error
+ retention-days: 30
diff --git a/backend/app/data/distro-catalog.json b/backend/app/data/distro-catalog.json
new file mode 100644
index 00000000..cb9f0980
--- /dev/null
+++ b/backend/app/data/distro-catalog.json
@@ -0,0 +1,337 @@
+{
+ "schema_version": 1,
+ "description": "ServerKit's 25 published platform targets and the container probes that can provide honest evidence for them.",
+ "targets": [
+ {
+ "id": "ubuntu",
+ "label": "Ubuntu",
+ "versions": "22.04 LTS, 24.04 LTS",
+ "family": "debian",
+ "published_status": "tested",
+ "architectures": ["amd64", "arm64"],
+ "windows_strategy": "Exact Docker userland probes; Multipass VMs for full-install evidence.",
+ "probes": [
+ {
+ "key": "ubuntu22",
+ "label": "Ubuntu 22.04",
+ "image": "ubuntu:22.04",
+ "fidelity": "exact",
+ "full_image": "geerlingguy/docker-ubuntu2204-ansible:latest"
+ },
+ {
+ "key": "ubuntu24",
+ "label": "Ubuntu 24.04",
+ "image": "ubuntu:24.04",
+ "fidelity": "exact",
+ "full_image": "geerlingguy/docker-ubuntu2404-ansible:latest"
+ }
+ ]
+ },
+ {
+ "id": "debian",
+ "label": "Debian",
+ "versions": "12 Bookworm, 13 Trixie",
+ "family": "debian",
+ "published_status": "tested",
+ "architectures": ["amd64", "arm64"],
+ "windows_strategy": "Exact Docker userland probes; Debian 12 also has a Vagrant full-install path.",
+ "probes": [
+ {
+ "key": "debian12",
+ "label": "Debian 12",
+ "image": "debian:12",
+ "fidelity": "exact",
+ "full_image": "geerlingguy/docker-debian12-ansible:latest"
+ },
+ {
+ "key": "debian13",
+ "label": "Debian 13",
+ "image": "debian:13",
+ "fidelity": "exact",
+ "full_image": null
+ }
+ ]
+ },
+ {
+ "id": "raspberry-pi-os",
+ "label": "Raspberry Pi OS",
+ "versions": "12 (64-bit)",
+ "family": "debian",
+ "published_status": "supported",
+ "architectures": ["arm64"],
+ "windows_strategy": "Debian 12 is only a userland proxy. Native arm64 CI plus a physical Pi is required for exact evidence.",
+ "proxy_probe_keys": ["debian12"],
+ "probes": []
+ },
+ {
+ "id": "linux-mint",
+ "label": "Linux Mint",
+ "versions": "21, 22",
+ "family": "debian",
+ "published_status": "supported",
+ "architectures": ["amd64"],
+ "windows_strategy": "Ubuntu 22.04/24.04 are base proxies; use Hyper-V with official Mint media for exact full installs.",
+ "proxy_probe_keys": ["ubuntu22", "ubuntu24"],
+ "probes": []
+ },
+ {
+ "id": "pop-os",
+ "label": "Pop!_OS",
+ "versions": "22.04",
+ "family": "debian",
+ "published_status": "supported",
+ "architectures": ["amd64"],
+ "windows_strategy": "Ubuntu 22.04 is a base proxy; use a Hyper-V VM for exact evidence.",
+ "proxy_probe_keys": ["ubuntu22"],
+ "probes": []
+ },
+ {
+ "id": "zorin-os",
+ "label": "Zorin OS",
+ "versions": "17",
+ "family": "debian",
+ "published_status": "community",
+ "architectures": ["amd64"],
+ "windows_strategy": "Ubuntu 22.04 is a base proxy; use a Hyper-V VM for exact evidence.",
+ "proxy_probe_keys": ["ubuntu22"],
+ "probes": []
+ },
+ {
+ "id": "elementary-os",
+ "label": "elementary OS",
+ "versions": "7, 8",
+ "family": "debian",
+ "published_status": "community",
+ "architectures": ["amd64"],
+ "windows_strategy": "Ubuntu LTS probes are base proxies; use Hyper-V VMs for exact evidence.",
+ "proxy_probe_keys": ["ubuntu22", "ubuntu24"],
+ "probes": []
+ },
+ {
+ "id": "proxmox-ve",
+ "label": "Proxmox VE",
+ "versions": "8",
+ "family": "debian",
+ "published_status": "supported",
+ "architectures": ["amd64"],
+ "windows_strategy": "Debian 12 is only a userland proxy. Exact host and nested-container behavior needs a nested Hyper-V Proxmox VM.",
+ "proxy_probe_keys": ["debian12"],
+ "probes": []
+ },
+ {
+ "id": "fedora",
+ "label": "Fedora",
+ "versions": "38, 39, 40, 41",
+ "family": "rhel",
+ "published_status": "tested",
+ "architectures": ["amd64", "arm64"],
+ "windows_strategy": "Exact Docker userland probes; Fedora 40 also has a Vagrant full-install path.",
+ "probes": [
+ {"key": "fedora38", "label": "Fedora 38", "image": "fedora:38", "fidelity": "exact", "full_image": null},
+ {"key": "fedora39", "label": "Fedora 39", "image": "fedora:39", "fidelity": "exact", "full_image": null},
+ {"key": "fedora40", "label": "Fedora 40", "image": "fedora:40", "fidelity": "exact", "full_image": "geerlingguy/docker-fedora40-ansible:latest"},
+ {"key": "fedora41", "label": "Fedora 41", "image": "fedora:41", "fidelity": "exact", "full_image": null}
+ ]
+ },
+ {
+ "id": "rocky-linux",
+ "label": "Rocky Linux",
+ "versions": "9, 10",
+ "family": "rhel",
+ "published_status": "tested",
+ "architectures": ["amd64", "arm64"],
+ "windows_strategy": "Exact Docker userland probes; Rocky 9 also has a Vagrant/systemd-container full-install path.",
+ "probes": [
+ {"key": "rocky9", "label": "Rocky Linux 9", "image": "rockylinux:9", "fidelity": "exact", "full_image": "geerlingguy/docker-rockylinux9-ansible:latest"},
+ {"key": "rocky10", "label": "Rocky Linux 10", "image": "rockylinux/rockylinux:10", "fidelity": "exact", "full_image": null}
+ ]
+ },
+ {
+ "id": "almalinux",
+ "label": "AlmaLinux",
+ "versions": "9, 10",
+ "family": "rhel",
+ "published_status": "tested",
+ "architectures": ["amd64", "arm64"],
+ "windows_strategy": "Exact Docker userland probes; AlmaLinux 9 has an opt-in Vagrant full-install path.",
+ "probes": [
+ {"key": "alma9", "label": "AlmaLinux 9", "image": "almalinux:9", "fidelity": "exact", "full_image": null},
+ {"key": "alma10", "label": "AlmaLinux 10", "image": "almalinux:10", "fidelity": "exact", "full_image": null}
+ ]
+ },
+ {
+ "id": "rhel",
+ "label": "RHEL",
+ "versions": "9, 10",
+ "family": "rhel",
+ "published_status": "supported",
+ "architectures": ["amd64", "arm64"],
+ "windows_strategy": "Red Hat UBI probes cover compatible userland only; exact package/subscription behavior needs subscribed RHEL VMs.",
+ "probes": [
+ {"key": "rhel9ubi", "label": "RHEL 9 (UBI proxy)", "image": "redhat/ubi9:latest", "fidelity": "proxy", "full_image": null},
+ {"key": "rhel10ubi", "label": "RHEL 10 (UBI proxy)", "image": "redhat/ubi10:latest", "fidelity": "proxy", "full_image": null}
+ ]
+ },
+ {
+ "id": "centos-stream",
+ "label": "CentOS Stream",
+ "versions": "9, 10",
+ "family": "rhel",
+ "published_status": "supported",
+ "architectures": ["amd64", "arm64"],
+ "windows_strategy": "Exact Docker userland probes.",
+ "probes": [
+ {"key": "centosstream9", "label": "CentOS Stream 9", "image": "quay.io/centos/centos:stream9", "fidelity": "exact", "full_image": null},
+ {"key": "centosstream10", "label": "CentOS Stream 10", "image": "quay.io/centos/centos:stream10", "fidelity": "exact", "full_image": null}
+ ]
+ },
+ {
+ "id": "oracle-linux",
+ "label": "Oracle Linux",
+ "versions": "9",
+ "family": "rhel",
+ "published_status": "community",
+ "architectures": ["amd64", "arm64"],
+ "windows_strategy": "Exact Docker userland probe; the UEK kernel is not represented by a container.",
+ "probes": [
+ {"key": "oracle9", "label": "Oracle Linux 9", "image": "oraclelinux:9", "fidelity": "exact", "full_image": null}
+ ]
+ },
+ {
+ "id": "amazon-linux",
+ "label": "Amazon Linux",
+ "versions": "2023",
+ "family": "rhel",
+ "published_status": "community",
+ "architectures": ["amd64", "arm64"],
+ "windows_strategy": "Exact Docker userland probe; EC2 metadata, kernel, SELinux, and cloud networking require an EC2 test.",
+ "probes": [
+ {"key": "amazon2023", "label": "Amazon Linux 2023", "image": "amazonlinux:2023", "fidelity": "exact", "full_image": null}
+ ]
+ },
+ {
+ "id": "opensuse-leap",
+ "label": "openSUSE Leap",
+ "versions": "15.5, 15.6",
+ "family": "suse",
+ "published_status": "community",
+ "architectures": ["amd64"],
+ "windows_strategy": "Exact Docker userland probes; Leap 15 has an opt-in Vagrant full-install path.",
+ "probes": [
+ {"key": "opensuse15", "label": "openSUSE Leap 15.5", "image": "opensuse/leap:15.5", "fidelity": "exact", "full_image": null},
+ {"key": "opensuse156", "label": "openSUSE Leap 15.6", "image": "opensuse/leap:15.6", "fidelity": "exact", "full_image": null}
+ ]
+ },
+ {
+ "id": "opensuse-tumbleweed",
+ "label": "openSUSE Tumbleweed",
+ "versions": "rolling",
+ "family": "suse",
+ "published_status": "community",
+ "architectures": ["amd64"],
+ "windows_strategy": "Exact Docker userland probe of the image current at test time.",
+ "probes": [
+ {"key": "opensuse-tumbleweed", "label": "openSUSE Tumbleweed", "image": "opensuse/tumbleweed:latest", "fidelity": "exact", "full_image": null}
+ ]
+ },
+ {
+ "id": "sles",
+ "label": "SUSE Linux Enterprise",
+ "versions": "15 SP5+",
+ "family": "suse",
+ "published_status": "community",
+ "architectures": ["amd64"],
+ "windows_strategy": "SUSE BCI is a userland proxy; exact repository and registration behavior needs a subscribed SLES VM.",
+ "probes": [
+ {"key": "sles15bci", "label": "SLES 15 (BCI proxy)", "image": "registry.suse.com/bci/bci-base:15.7", "fidelity": "proxy", "full_image": null}
+ ]
+ },
+ {
+ "id": "arch-linux",
+ "label": "Arch Linux",
+ "versions": "rolling",
+ "family": "independent",
+ "published_status": "community",
+ "architectures": ["amd64"],
+ "windows_strategy": "Exact Docker userland probe of the image current at test time.",
+ "probes": [
+ {"key": "arch", "label": "Arch Linux", "image": "archlinux:latest", "fidelity": "exact", "full_image": null}
+ ]
+ },
+ {
+ "id": "manjaro",
+ "label": "Manjaro",
+ "versions": "rolling",
+ "family": "independent",
+ "published_status": "community",
+ "architectures": ["amd64"],
+ "windows_strategy": "Exact base-userland Docker probe; a desktop/live VM is needed for full-install evidence.",
+ "probes": [
+ {"key": "manjaro", "label": "Manjaro", "image": "manjarolinux/base:latest", "fidelity": "exact", "full_image": null}
+ ]
+ },
+ {
+ "id": "gentoo",
+ "label": "Gentoo",
+ "versions": "rolling",
+ "family": "independent",
+ "published_status": "community",
+ "architectures": ["amd64"],
+ "windows_strategy": "Exact stage3 Docker userland probe. Expected failures remain visible because emerge is not an installer package-manager path.",
+ "probes": [
+ {"key": "gentoo", "label": "Gentoo stage3", "image": "gentoo/stage3:latest", "fidelity": "exact", "full_image": null}
+ ]
+ },
+ {
+ "id": "docker",
+ "label": "Docker",
+ "versions": "Engine 24.0+, Compose v2",
+ "family": "platform",
+ "published_status": "supported",
+ "architectures": ["amd64", "arm64"],
+ "windows_strategy": "Docker Desktop can run scripts/test/smoke-docker-image.sh; distro userland probes do not validate ServerKit's all-in-one image.",
+ "probes": []
+ },
+ {
+ "id": "lxc-incus",
+ "label": "LXC / Incus container",
+ "versions": "Proxmox 8, Incus 6",
+ "family": "platform",
+ "published_status": "supported",
+ "architectures": ["amd64"],
+ "windows_strategy": "Needs a Linux or nested-Proxmox host with nesting/keyctl controls; Docker Desktop is not an LXC substitute.",
+ "probes": []
+ },
+ {
+ "id": "virtual-machines",
+ "label": "Virtual machines",
+ "versions": "KVM, VMware, Hyper-V, VirtualBox",
+ "family": "platform",
+ "published_status": "supported",
+ "architectures": ["amd64", "arm64"],
+ "windows_strategy": "scripts/test/full-stack-test.ps1 exercises Hyper-V through Multipass and Vagrant; other hypervisors need their own hosts.",
+ "probes": []
+ },
+ {
+ "id": "wsl2",
+ "label": "WSL2",
+ "versions": "Ubuntu 22.04+",
+ "family": "platform",
+ "published_status": "community",
+ "architectures": ["amd64"],
+ "windows_strategy": "Use a disposable wsl --import distribution for install testing. The current developer distro must not be mutated by discovery runs.",
+ "probes": []
+ }
+ ],
+ "legacy_probes": [
+ {
+ "key": "debian11",
+ "target_id": "debian",
+ "label": "Debian 11 (legacy)",
+ "family": "debian",
+ "image": "debian:11",
+ "fidelity": "legacy",
+ "full_image": "geerlingguy/docker-debian11-ansible:latest"
+ }
+ ]
+}
diff --git a/backend/app/services/test_sandbox_service.py b/backend/app/services/test_sandbox_service.py
index 03741371..fc862721 100644
--- a/backend/app/services/test_sandbox_service.py
+++ b/backend/app/services/test_sandbox_service.py
@@ -19,6 +19,7 @@ This is a Docker-based complement to the Multipass/Vagrant E2E harness in
scripts/test/ — it trades VM fidelity (real cloud images, Hyper-V) for
convenience (runs on any host where the panel + Docker already are).
"""
+import json
import subprocess
import threading
import time
@@ -37,50 +38,40 @@ REPO_ROOT = Path(__file__).resolve().parents[3]
QUICK_TIMEOUT_S = 900 # 15 min ceiling for the unit suites
FULL_TIMEOUT_S = 2400 # 40 min ceiling for a full install + health probe
+CATALOG_PATH = Path(__file__).resolve().parents[1] / 'data' / 'distro-catalog.json'
+
+
+def _load_distros():
+ """Flatten the shared 25-target catalog for the Test Sandbox picker."""
+ catalog = json.loads(CATALOG_PATH.read_text(encoding='utf-8'))
+ distros = {}
+ for target in catalog['targets']:
+ for probe in target.get('probes', []):
+ distros[probe['key']] = {
+ 'label': probe['label'],
+ 'family': target['family'],
+ 'target': target['id'],
+ 'fidelity': probe['fidelity'],
+ 'quick_image': probe['image'],
+ 'full_image': probe.get('full_image'),
+ }
+ # Keep explicit legacy probes runnable without counting them among the
+ # published version claims in the compatibility report.
+ for probe in catalog.get('legacy_probes', []):
+ distros[probe['key']] = {
+ 'label': probe['label'],
+ 'family': probe['family'],
+ 'target': probe['target_id'],
+ 'fidelity': probe['fidelity'],
+ 'quick_image': probe['image'],
+ 'full_image': probe.get('full_image'),
+ }
+ return distros
+
+
# quick_image: plain distro container (unit suites).
-# full_image: systemd-capable container for a real install (None = unsupported).
-DISTROS = {
- 'ubuntu22': {
- 'label': 'Ubuntu 22.04', 'family': 'debian',
- 'quick_image': 'ubuntu:22.04',
- 'full_image': 'geerlingguy/docker-ubuntu2204-ansible:latest',
- },
- 'ubuntu24': {
- 'label': 'Ubuntu 24.04', 'family': 'debian',
- 'quick_image': 'ubuntu:24.04',
- 'full_image': 'geerlingguy/docker-ubuntu2404-ansible:latest',
- },
- 'debian12': {
- 'label': 'Debian 12', 'family': 'debian',
- 'quick_image': 'debian:12',
- 'full_image': 'geerlingguy/docker-debian12-ansible:latest',
- },
- 'debian11': {
- 'label': 'Debian 11 (legacy)', 'family': 'debian',
- 'quick_image': 'debian:11',
- 'full_image': 'geerlingguy/docker-debian11-ansible:latest',
- },
- 'rocky9': {
- 'label': 'Rocky Linux 9', 'family': 'rhel',
- 'quick_image': 'rockylinux:9',
- 'full_image': 'geerlingguy/docker-rockylinux9-ansible:latest',
- },
- 'alma9': {
- 'label': 'AlmaLinux 9', 'family': 'rhel',
- 'quick_image': 'almalinux:9',
- 'full_image': None, # no maintained systemd image
- },
- 'fedora40': {
- 'label': 'Fedora 40', 'family': 'rhel',
- 'quick_image': 'fedora:40',
- 'full_image': 'geerlingguy/docker-fedora40-ansible:latest',
- },
- 'opensuse15': {
- 'label': 'openSUSE Leap 15.5', 'family': 'suse',
- 'quick_image': 'opensuse/leap:15.5',
- 'full_image': None, # no maintained systemd image
- },
-}
+# full_image: systemd-capable container for a real install (None = unavailable).
+DISTROS = _load_distros()
# Mirrors the cross-distro job in .github/workflows/scripts-ci.yml.
QUICK_RUNNER = r"""#!/bin/sh
@@ -89,20 +80,15 @@ cd /src || exit 2
if ! command -v bash >/dev/null 2>&1; then
{ command -v apt-get >/dev/null 2>&1 && apt-get update -qq && apt-get install -y -qq bash; } ||
{ command -v dnf >/dev/null 2>&1 && dnf install -y -q bash; } ||
- { command -v zypper >/dev/null 2>&1 && zypper --non-interactive install bash; } || true
+ { command -v yum >/dev/null 2>&1 && yum install -y -q bash; } ||
+ { command -v zypper >/dev/null 2>&1 && zypper --non-interactive install bash; } ||
+ { command -v pacman >/dev/null 2>&1 && pacman -Sy --noconfirm bash; } ||
+ { command -v apk >/dev/null 2>&1 && apk add --no-cache bash; } ||
+ { command -v emerge >/dev/null 2>&1 && emerge --oneshot app-shells/bash; } || true
fi
echo "bash $(bash --version | head -1)"
-fail=0
-for f in serverkit install.sh uninstall.sh scripts/*.sh scripts/lib/*.sh scripts/test/*.sh; do
- [ -f "$f" ] || continue
- if bash -n "$f"; then echo "ok $f"; else echo "FAIL $f"; fail=1; fi
-done
-for s in test_update test_install test_lib test_cli test_agent_install test_stage; do
- echo "=== $s ==="
- bash "scripts/test/$s.sh" || fail=1
-done
-echo "QUICK_RESULT=$([ $fail -eq 0 ] && echo PASS || echo FAIL)"
-exit $fail
+command -v bash >/dev/null 2>&1 || exit 127
+exec bash scripts/test/run-distro-quick.sh
"""
# run_id -> list of container names (for cancel / stale sweeps)
@@ -119,6 +105,8 @@ class TestSandboxService:
'key': key,
'label': spec['label'],
'family': spec['family'],
+ 'target': spec['target'],
+ 'fidelity': spec['fidelity'],
'quick': bool(spec['quick_image']),
'full': bool(spec['full_image']),
}
diff --git a/backend/tests/test_test_sandbox_catalog.py b/backend/tests/test_test_sandbox_catalog.py
new file mode 100644
index 00000000..20c48935
--- /dev/null
+++ b/backend/tests/test_test_sandbox_catalog.py
@@ -0,0 +1,56 @@
+import json
+from pathlib import Path
+
+from app.services.test_sandbox_service import DISTROS, TestSandboxService
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+CATALOG_PATH = REPO_ROOT / 'backend' / 'app' / 'data' / 'distro-catalog.json'
+
+
+def _catalog():
+ return json.loads(CATALOG_PATH.read_text(encoding='utf-8'))
+
+
+def test_catalog_has_all_25_published_targets_and_unique_probes():
+ catalog = _catalog()
+ assert catalog['schema_version'] == 1
+ assert len(catalog['targets']) == 25
+ assert len({target['id'] for target in catalog['targets']}) == 25
+ assert sum(target['published_status'] == 'tested' for target in catalog['targets']) == 5
+ assert sum(target['published_status'] == 'supported' for target in catalog['targets']) == 9
+ assert sum(target['published_status'] == 'community' for target in catalog['targets']) == 11
+
+ probes = [
+ probe
+ for target in catalog['targets']
+ for probe in target.get('probes', [])
+ ]
+ assert len(probes) == 25
+ assert len({probe['key'] for probe in probes}) == 25
+ assert sum(probe['fidelity'] == 'exact' for probe in probes) == 22
+ assert sum(probe['fidelity'] == 'proxy' for probe in probes) == 3
+
+
+def test_sandbox_registry_is_generated_from_catalog_plus_legacy_probes():
+ catalog = _catalog()
+ catalog_keys = {
+ probe['key']
+ for target in catalog['targets']
+ for probe in target.get('probes', [])
+ }
+ legacy_keys = {probe['key'] for probe in catalog['legacy_probes']}
+
+ assert set(DISTROS) == catalog_keys | legacy_keys
+ assert {'debian13', 'rocky10', 'alma10', 'centosstream10', 'arch', 'gentoo'} <= set(DISTROS)
+ assert DISTROS['rhel10ubi']['fidelity'] == 'proxy'
+ assert DISTROS['ubuntu24']['full_image']
+ assert DISTROS['rocky10']['full_image'] is None
+
+
+def test_sandbox_api_metadata_exposes_target_and_fidelity():
+ listed = {item['key']: item for item in TestSandboxService.list_distros()}
+ assert listed['amazon2023']['target'] == 'amazon-linux'
+ assert listed['amazon2023']['fidelity'] == 'exact'
+ assert listed['sles15bci']['fidelity'] == 'proxy'
+ assert listed['debian11']['fidelity'] == 'legacy'
diff --git a/docs/testing/DISTRO_COMPATIBILITY_BASELINE_2026-08-28.md b/docs/testing/DISTRO_COMPATIBILITY_BASELINE_2026-08-28.md
new file mode 100644
index 00000000..a3c0860c
--- /dev/null
+++ b/docs/testing/DISTRO_COMPATIBILITY_BASELINE_2026-08-28.md
@@ -0,0 +1,88 @@
+# Distro compatibility baseline — 2026-08-28
+
+This is the first broad ServerKit compatibility discovery run from Windows 10
+using Docker Desktop 29.7.2 (`linux/amd64`). It records observed evidence; it
+does not change the installer or redefine the published support labels.
+
+Command:
+
+```powershell
+python .\scripts\test\distro-compatibility.py --mode both --jobs 4
+```
+
+## Numbers
+
+- Published catalog: **25/25 targets** — 5 Tested, 9 Supported, 11 Community.
+- Runnable container probes: **25 images** — 22 exact distro/version images
+ and 3 vendor userland proxies.
+- Checks executed: **50** — 44 passed, 6 failed, 0 infrastructure errors.
+- Quick source/syntax checks: **22/25 passed**.
+- Real Python repository provisioning: **22/25 passed**.
+- Published **Tested** group: **5/5 target families passed both available
+ container layers** (Ubuntu, Debian, Fedora, Rocky Linux, AlmaLinux).
+- ServerKit all-in-one Docker artifact: **12/12 smoke assertions passed** after
+ a Windows-native build and boot through Docker Desktop.
+- WSL2 Ubuntu 24.04.2: **non-destructive quick suite passed** with systemd in
+ the `running` state. Package provisioning/full install was intentionally not
+ run against the developer's active WSL distribution.
+
+A quick pass is not an install pass. It covers shell syntax and ServerKit's
+source-level installer/update/lib/CLI suites. A provisioning pass means the
+real repositories supplied a Python in ServerKit's 3.11–3.13 gate, and that it
+created a venv with pip, SSL, SQLite, and ctypes.
+
+## Concrete results
+
+| Image probe | Fidelity | Quick | Python provisioning | What this says |
+|---|---|---:|---:|---|
+| Ubuntu 22.04 | exact | pass | pass | Both container layers pass. |
+| Ubuntu 24.04 | exact | pass | pass | Both container layers pass. |
+| Debian 12 | exact | pass | pass | Both container layers pass. |
+| Debian 13 | exact | pass | pass | Both container layers pass. |
+| Fedora 38 | exact | pass | pass | Both container layers pass; no lifecycle/EOL claim is implied. |
+| Fedora 39 | exact | pass | pass | Both container layers pass; no lifecycle/EOL claim is implied. |
+| Fedora 40 | exact | pass | pass | Both container layers pass; no lifecycle/EOL claim is implied. |
+| Fedora 41 | exact | pass | pass | Both container layers pass; no lifecycle/EOL claim is implied. |
+| Rocky Linux 9 | exact | pass | pass | Both container layers pass. |
+| Rocky Linux 10 | exact | pass | pass | Both container layers pass. |
+| AlmaLinux 9 | exact | pass | pass | Both container layers pass. |
+| AlmaLinux 10 | exact | pass | pass | Both container layers pass. |
+| RHEL 9 UBI | proxy | pass | pass | RHEL-compatible userland only; not subscription/repository proof. |
+| RHEL 10 UBI | proxy | pass | pass | RHEL-compatible userland only; not subscription/repository proof. |
+| CentOS Stream 9 | exact | pass | pass | Both container layers pass. |
+| CentOS Stream 10 | exact | pass | pass | Both container layers pass. |
+| Oracle Linux 9 | exact | pass | pass | Userland passes; the UEK kernel is outside a container. |
+| Amazon Linux 2023 | exact | **fail** | pass | Quick image lacks `find`; five update-suite assertions fail. Python is usable. |
+| openSUSE Leap 15.5 | exact | pass | pass | Both container layers pass. |
+| openSUSE Leap 15.6 | exact | pass | pass | Both container layers pass. |
+| openSUSE Tumbleweed | exact | **fail** | pass | Minimal image lacks `find`/`awk`; the quick suite cannot run cleanly. Python is usable. |
+| SLES 15 SP7 BCI | proxy | **fail** | pass | Minimal BCI lacks `awk`; SLES userland proxy only. Python is usable. |
+| Arch Linux rolling | exact | pass | **fail** | Current repo Python is 3.14.7, outside the 3.11–3.13 gate; fallback package names also do not match Arch. |
+| Manjaro rolling | exact | pass | **fail** | Image Python is 3.14.3, outside the 3.11–3.13 gate; fallback package names also do not match Arch. |
+| Gentoo stage3 | exact | pass | **fail** | Detection exits before provisioning because `emerge` is not a supported installer package-manager path. |
+
+## What remains unproven
+
+The Windows/Docker run gives base-proxy evidence, not exact evidence, for
+Raspberry Pi OS, Linux Mint, Pop!_OS, Zorin OS, elementary OS, and Proxmox VE.
+Those need arm64 hardware/CI or disposable Hyper-V VMs with their actual media.
+
+Docker, LXC/Incus, virtual-machine behavior, and WSL2 are platform targets, not
+plain distro images. They remain separate tracks:
+
+- Docker: **passed in this baseline** — `scripts/test/smoke-docker-image.sh`
+ built the image, booted it, reached health, served the SPA and both agent
+ installers, and passed 12/12 assertions.
+- Hyper-V guests: `scripts/test/full-stack-test.ps1` via Multipass/Vagrant.
+- WSL2: the source-level suite passed on Ubuntu 24.04.2 with a WSL2 kernel and
+ running systemd. A real install still needs a disposable `wsl --import`
+ distribution, not the developer's active WSL installation.
+- LXC/Incus and Proxmox nesting: a Linux/nested-Proxmox host with nesting and
+ keyctl controls.
+- Raspberry Pi OS: native arm64 CI for architecture-sensitive logic plus a
+ physical 64-bit Pi for final evidence.
+
+The generated per-check logs and JSON for this run are under the ignored local
+artifact directory `scripts/test/output/distro-compatibility/20260828-223431/`.
+Future scheduled discovery runs upload the equivalent report as a GitHub
+Actions artifact without turning known failures green.
diff --git a/frontend/src/i18n/locales/en.json b/frontend/src/i18n/locales/en.json
index a74d9b1c..3c01d4a2 100644
--- a/frontend/src/i18n/locales/en.json
+++ b/frontend/src/i18n/locales/en.json
@@ -6506,6 +6506,7 @@
"distros": "Distros",
"dockerIsNotAvailableOnThis": "Docker is not available on this host — test runs cannot start until the Docker daemon is reachable.",
"fullInstall": "Full install",
+ "independent": "Independent",
"loadingLog": "Loading log…",
"loadingRunHistory": "Loading run history…",
"loadingTestSandbox": "Loading test sandbox…",
@@ -6525,7 +6526,8 @@
"started": "Started",
"startedRunAcrossDistroS": "Started {{mode}} run across {{length}} distro(s)",
"testMode": "Test mode",
- "testSandbox": "Test Sandbox"
+ "testSandbox": "Test Sandbox",
+ "userlandProxy": "userland proxy · "
},
"themeBrowseModal": {
"browseThemes": "Browse themes",
diff --git a/frontend/src/pages/TestSandbox.jsx b/frontend/src/pages/TestSandbox.jsx
index b2e0d255..c9e9e98b 100644
--- a/frontend/src/pages/TestSandbox.jsx
+++ b/frontend/src/pages/TestSandbox.jsx
@@ -18,9 +18,16 @@ const POLL_MS = 2500;
const HISTORY_LIMIT = 20;
const FAMILY_META = {
- debian: { labelKey: 'app.testSandbox.debian', label: 'Debian', kind: 'cyan' },
+ debian: { kind: 'cyan' },
rhel: { label: 'RHEL', kind: 'amber' },
suse: { label: 'SUSE', kind: 'violet' },
+ independent: { kind: 'gray' },
+};
+
+const familyLabel = (t, familyKey) => {
+ if (familyKey === 'debian') return t('app.testSandbox.debian', 'Debian');
+ if (familyKey === 'independent') return t('app.testSandbox.independent', 'Independent');
+ return FAMILY_META[familyKey]?.label;
};
const MODES = [
@@ -77,7 +84,9 @@ function RunResults({ run, distroMeta, logs, openLogs, onToggleLog }) {
{open ? <ChevronDown size={14} /> : <ChevronRight size={14} />}
<span className="ts-result__name">{meta.label || key}</span>
{family && (
- <Pill kind={family.kind} dot={false}>{family.label}</Pill>
+ <Pill kind={family.kind} dot={false}>
+ {familyLabel(t, meta.family)}
+ </Pill>
)}
<span className="ts-result__spacer" />
{result.duration_s != null && (
@@ -424,8 +433,13 @@ const TestSandbox = () => {
>
<span className="ts-distro__label">{d.label}</span>
<span className="ts-distro__meta">
- {family && <Pill kind={family.kind} dot={false}>{family.label}</Pill>}
+ {family && (
+ <Pill kind={family.kind} dot={false}>
+ {familyLabel(t, d.family)}
+ </Pill>
+ )}
<span className="ts-distro__hint">
+ {d.fidelity === 'proxy' && t('app.testSandbox.userlandProxy', 'userland proxy · ')}
{disabled ? 'quick only' : (d.full ? 'quick + full' : 'quick')}
</span>
</span>
diff --git a/scripts/test/README.md b/scripts/test/README.md
index e6b1fd83..4c24aaaa 100644
--- a/scripts/test/README.md
+++ b/scripts/test/README.md
@@ -153,6 +153,43 @@ bash scripts/test/test_install.sh
bash scripts/test/test_lib.sh
```
+## All-25 distro compatibility discovery (Windows-friendly)
+
+`distro-compatibility.py` turns the published 25-target list into a repeatable
+evidence report. It runs directly from Windows against Docker Desktop, so it
+does not modify the installed WSL distributions. The shared
+`backend/app/data/distro-catalog.json` records exact images, vendor userland proxies, base-only
+proxies, and targets that require a separate VM/hardware harness.
+
+```powershell
+# Validate and list all 25 targets without running Docker
+python .\scripts\test\distro-compatibility.py --list
+
+# Run source-level suites plus real Python provisioning across every image
+python .\scripts\test\distro-compatibility.py --mode both --jobs 4
+
+# A smaller investigation or a CI-gating run
+python .\scripts\test\distro-compatibility.py --only ubuntu22,debian13,rocky10
+python .\scripts\test\distro-compatibility.py --mode provision --strict
+```
+
+Each run writes `report.md`, `report.json`, image-pull logs, and one log per
+probe/mode under `scripts/test/output/distro-compatibility/<timestamp>/`.
+Failures remain failures by default, but discovery runs exit zero so one known
+incompatibility does not erase the rest of the matrix. Pass `--strict` when the
+selected matrix is intended to gate CI.
+
+The two modes deliberately make narrower claims than a full install:
+
+- **quick** — shell syntax plus the source-level installer/update/lib/CLI suites.
+- **provision** — real repositories through `install.sh`, including supported
+ Python, venv, pip, SSL, SQLite, and ctypes.
+
+Neither mode proves systemd, nginx, firewall behavior, Docker-in-Docker,
+kernel-specific behavior, LXC nesting, a hypervisor, or Raspberry Pi hardware.
+Use the Windows VM harness above and the per-target path in the generated
+report for that evidence.
+
## Probe environment matrix (plan 75 §D)
`scripts/test/probe-matrix.sh` runs `backend/tests/test_probe_env_integration.py`
diff --git a/scripts/test/distro-compatibility.py b/scripts/test/distro-compatibility.py
new file mode 100644
index 00000000..8a9425f7
--- /dev/null
+++ b/scripts/test/distro-compatibility.py
@@ -0,0 +1,641 @@
+#!/usr/bin/env python3
+"""Run evidence-producing ServerKit checks across distro containers.
+
+This is a discovery runner, not a support-claim generator. A passing plain
+container proves only the named mode:
+
+* quick: shell syntax and source-level installer/update test suites
+* provision: the real distro repositories can supply a supported Python,
+ virtualenv, pip, ssl, sqlite3, and ctypes through install.sh
+
+It does not prove systemd, nginx, Docker-in-Docker, firewall behavior, a full
+ServerKit install, a distro-specific kernel, or hardware. The generated report
+keeps exact, proxy, untestable, failed, and infrastructure-error states apart.
+"""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import json
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+import time
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+REPO_ROOT = SCRIPT_DIR.parents[1]
+CATALOG_PATH = REPO_ROOT / "backend" / "app" / "data" / "distro-catalog.json"
+DEFAULT_OUTPUT_ROOT = SCRIPT_DIR / "output" / "distro-compatibility"
+MODES = ("quick", "provision")
+
+BOOTSTRAP_BASH = r"""
+if ! command -v bash >/dev/null 2>&1; then
+ { command -v apt-get >/dev/null 2>&1 && apt-get update -qq && apt-get install -y -qq bash; } ||
+ { command -v dnf >/dev/null 2>&1 && dnf install -y -q bash; } ||
+ { command -v yum >/dev/null 2>&1 && yum install -y -q bash; } ||
+ { command -v zypper >/dev/null 2>&1 && zypper --non-interactive install bash; } ||
+ { command -v pacman >/dev/null 2>&1 && pacman -Sy --noconfirm bash; } ||
+ { command -v apk >/dev/null 2>&1 && apk add --no-cache bash; } ||
+ { command -v emerge >/dev/null 2>&1 && emerge --oneshot app-shells/bash; } || true
+fi
+command -v bash >/dev/null 2>&1 || {
+ echo "COMPAT_HARNESS_ERROR=no bash available" >&2
+ exit 127
+}
+""".strip()
+
+MODE_COMMANDS = {
+ "quick": "exec bash /src/scripts/test/run-distro-quick.sh",
+ "provision": "exec bash /src/scripts/test/test_provision_python.sh",
+}
+MODE_TIMEOUTS = {"quick": 900, "provision": 1500}
+
+
+def utc_now() -> str:
+ return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def load_catalog(path: Path = CATALOG_PATH) -> dict[str, Any]:
+ catalog = json.loads(path.read_text(encoding="utf-8"))
+ targets = catalog.get("targets")
+ if catalog.get("schema_version") != 1 or not isinstance(targets, list):
+ raise ValueError("unsupported or malformed distro catalog")
+ if len(targets) != 25:
+ raise ValueError(f"catalog must describe exactly 25 targets, found {len(targets)}")
+
+ target_ids: set[str] = set()
+ probe_keys: set[str] = set()
+ for target in targets:
+ target_id = target.get("id")
+ if not target_id or target_id in target_ids:
+ raise ValueError(f"missing or duplicate target id: {target_id!r}")
+ target_ids.add(target_id)
+ for probe in target.get("probes", []):
+ key = probe.get("key")
+ if not key or key in probe_keys:
+ raise ValueError(f"missing or duplicate probe key: {key!r}")
+ if probe.get("fidelity") not in ("exact", "proxy"):
+ raise ValueError(f"probe {key} has invalid fidelity")
+ if not probe.get("image"):
+ raise ValueError(f"probe {key} has no container image")
+ probe_keys.add(key)
+
+ for probe in catalog.get("legacy_probes", []):
+ key = probe.get("key")
+ if not key or key in probe_keys:
+ raise ValueError(f"missing or duplicate legacy probe key: {key!r}")
+ if probe.get("target_id") not in target_ids:
+ raise ValueError(f"legacy probe {key} references an unknown target")
+ probe_keys.add(key)
+
+ for target in targets:
+ missing = set(target.get("proxy_probe_keys", [])) - probe_keys
+ if missing:
+ raise ValueError(
+ f"target {target['id']} references unknown proxy probes: {sorted(missing)}"
+ )
+ return catalog
+
+
+def flatten_probes(catalog: dict[str, Any], include_legacy: bool) -> list[dict[str, Any]]:
+ probes: list[dict[str, Any]] = []
+ for target in catalog["targets"]:
+ for position, raw_probe in enumerate(target.get("probes", [])):
+ probe = dict(raw_probe)
+ probe.update(
+ target_id=target["id"],
+ target_label=target["label"],
+ family=target["family"],
+ published_status=target["published_status"],
+ catalog_position=len(probes),
+ target_probe_position=position,
+ )
+ probes.append(probe)
+ if include_legacy:
+ targets = {target["id"]: target for target in catalog["targets"]}
+ for raw_probe in catalog.get("legacy_probes", []):
+ probe = dict(raw_probe)
+ target = targets[probe["target_id"]]
+ probe.update(
+ target_label=target["label"],
+ family=probe.get("family", target["family"]),
+ published_status="legacy",
+ catalog_position=len(probes),
+ target_probe_position=-1,
+ )
+ probes.append(probe)
+ return probes
+
+
+def normalize_only(values: list[str]) -> set[str]:
+ return {
+ value.strip()
+ for item in values
+ for value in item.split(",")
+ if value.strip()
+ }
+
+
+def safe_slug(value: str) -> str:
+ return re.sub(r"[^a-z0-9_.-]+", "-", value.lower()).strip("-.")
+
+
+def run_logged(
+ args: list[str], log_path: Path, timeout_s: int, *, append: bool = False
+) -> tuple[int | None, float, str]:
+ started = time.monotonic()
+ mode = "a" if append else "w"
+ with log_path.open(mode, encoding="utf-8", errors="replace") as log:
+ if append:
+ log.write("\n")
+ log.write("$ " + " ".join(args) + "\n\n")
+ log.flush()
+ try:
+ proc = subprocess.run(
+ args,
+ cwd=REPO_ROOT,
+ stdout=log,
+ stderr=subprocess.STDOUT,
+ text=True,
+ timeout=timeout_s,
+ check=False,
+ )
+ return proc.returncode, time.monotonic() - started, ""
+ except subprocess.TimeoutExpired:
+ log.write(f"\nCOMPAT_HARNESS_TIMEOUT={timeout_s}s\n")
+ return None, time.monotonic() - started, f"timed out after {timeout_s}s"
+ except OSError as exc:
+ log.write(f"\nCOMPAT_HARNESS_OS_ERROR={exc}\n")
+ return None, time.monotonic() - started, str(exc)
+
+
+def docker_output(args: list[str], timeout_s: int = 30) -> str:
+ try:
+ proc = subprocess.run(
+ ["docker", *args],
+ cwd=REPO_ROOT,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.DEVNULL,
+ text=True,
+ timeout=timeout_s,
+ check=False,
+ )
+ except (OSError, subprocess.TimeoutExpired):
+ return ""
+ return proc.stdout.strip() if proc.returncode == 0 else ""
+
+
+def inspect_image(image: str) -> dict[str, str]:
+ image_id = docker_output(["image", "inspect", "--format", "{{.Id}}", image])
+ identity_cmd = (
+ ". /etc/os-release 2>/dev/null || true; "
+ "printf '%s\\t%s\\t%s\\n' \"${ID:-unknown}\" "
+ "\"${VERSION_ID:-unknown}\" \"${PRETTY_NAME:-unknown}\""
+ )
+ identity = docker_output(["run", "--rm", image, "sh", "-c", identity_cmd], 60)
+ parts = identity.split("\t", 2)
+ if len(parts) != 3:
+ parts = ["unknown", "unknown", identity or "unknown"]
+ return {
+ "image_id": image_id,
+ "os_id": parts[0],
+ "version_id": parts[1],
+ "pretty_name": parts[2],
+ }
+
+
+def failure_excerpt(log_path: Path, mode: str) -> str:
+ """Pull the first useful cause from a failed check without parsing pass counts."""
+ text = log_path.read_text(encoding="utf-8", errors="replace")
+ useful: list[str] = []
+ needles = ("✘", "command not found", "No supported package manager")
+ for raw_line in text.splitlines():
+ line = " ".join(raw_line.strip().split())
+ harness_error = line.startswith("COMPAT_HARNESS_")
+ if line and (harness_error or any(needle.lower() in line.lower() for needle in needles)):
+ if line not in useful:
+ useful.append(line)
+ if len(useful) == 3:
+ break
+ if useful:
+ excerpt = "; ".join(useful)
+ return excerpt[:500]
+ if mode == "provision" and " distro:" not in text:
+ return "installer exited during OS/package-manager detection before the provision assertions"
+ return "see log for the failing assertion"
+
+
+def result_for_pull_failure(
+ probe: dict[str, Any], mode: str, exit_code: int | None, duration_s: float, detail: str
+) -> dict[str, Any]:
+ return {
+ **{key: probe[key] for key in (
+ "key", "label", "target_id", "target_label", "family", "image", "fidelity"
+ )},
+ "mode": mode,
+ "status": "infra_error",
+ "exit_code": exit_code,
+ "duration_s": round(duration_s, 1),
+ "detail": detail,
+ "log": f"{probe['key']}/pull.log",
+ "identity": {},
+ "catalog_position": probe["catalog_position"],
+ }
+
+
+def run_probe(
+ probe: dict[str, Any],
+ modes: tuple[str, ...],
+ run_dir: Path,
+ no_pull: bool,
+ remove_images: bool,
+) -> list[dict[str, Any]]:
+ probe_dir = run_dir / probe["key"]
+ probe_dir.mkdir(parents=True, exist_ok=True)
+ image = probe["image"]
+
+ if not no_pull:
+ pull_rc, pull_duration, pull_error = run_logged(
+ ["docker", "pull", image], probe_dir / "pull.log", timeout_s=900
+ )
+ if pull_rc != 0:
+ if pull_rc is None:
+ detail = pull_error or "image pull did not return an exit code"
+ else:
+ detail = f"docker pull failed with exit {pull_rc}"
+ return [
+ result_for_pull_failure(probe, mode, pull_rc, pull_duration, detail)
+ for mode in modes
+ ]
+ else:
+ (probe_dir / "pull.log").write_text(
+ "Pull skipped by --no-pull; Docker may use a cached image.\n",
+ encoding="utf-8",
+ )
+
+ identity = inspect_image(image)
+ results: list[dict[str, Any]] = []
+ mount_source = REPO_ROOT.as_posix()
+ for mode in modes:
+ container_name = safe_slug(
+ f"sk-compat-{probe['key']}-{mode}-{uuid.uuid4().hex[:8]}"
+ )[:120]
+ script = BOOTSTRAP_BASH + "\n" + MODE_COMMANDS[mode]
+ command = [
+ "docker",
+ "run",
+ "--rm",
+ "--name",
+ container_name,
+ "--mount",
+ f"type=bind,source={mount_source},target=/src,readonly",
+ "--workdir",
+ "/src",
+ image,
+ "sh",
+ "-c",
+ script,
+ ]
+ log_path = probe_dir / f"{mode}.log"
+ rc, duration, error = run_logged(
+ command, log_path, timeout_s=MODE_TIMEOUTS[mode]
+ )
+ if rc is None:
+ status = "infra_error"
+ detail = error or "docker run did not return an exit code"
+ docker_output(["rm", "-f", container_name])
+ elif rc == 0:
+ status = "passed"
+ detail = "exit 0"
+ elif rc == 125:
+ status = "infra_error"
+ detail = "docker could not start the test container (exit 125)"
+ else:
+ status = "failed"
+ detail = f"test exited {rc}: {failure_excerpt(log_path, mode)}"
+ results.append(
+ {
+ **{key: probe[key] for key in (
+ "key", "label", "target_id", "target_label", "family", "image", "fidelity"
+ )},
+ "mode": mode,
+ "status": status,
+ "exit_code": rc,
+ "duration_s": round(duration, 1),
+ "detail": detail,
+ "log": f"{probe['key']}/{mode}.log",
+ "identity": identity,
+ "catalog_position": probe["catalog_position"],
+ }
+ )
+
+ if remove_images:
+ docker_output(["image", "rm", image], 120)
+ return results
+
+
+def md_escape(value: Any) -> str:
+ return str(value).replace("|", "\\|").replace("\n", " ")
+
+
+def result_counts(results: list[dict[str, Any]]) -> dict[str, int]:
+ return {
+ status: sum(result["status"] == status for result in results)
+ for status in ("passed", "failed", "infra_error")
+ }
+
+
+def target_evidence(
+ target: dict[str, Any], results: list[dict[str, Any]]
+) -> tuple[str, str]:
+ own_keys = {probe["key"] for probe in target.get("probes", [])}
+ proxy_keys = set(target.get("proxy_probe_keys", []))
+ relevant = [result for result in results if result["key"] in own_keys]
+ evidence_kind = "exact" if any(
+ probe.get("fidelity") == "exact" for probe in target.get("probes", [])
+ ) else "proxy"
+ if not relevant and proxy_keys:
+ relevant = [result for result in results if result["key"] in proxy_keys]
+ evidence_kind = "base proxy"
+ if not relevant:
+ if own_keys or proxy_keys:
+ return "not selected", "No matching probe was selected in this run."
+ return "separate harness", target["windows_strategy"]
+
+ counts = result_counts(relevant)
+ total = len(relevant)
+ if counts["failed"]:
+ state = f"{evidence_kind} failing"
+ elif counts["infra_error"]:
+ state = f"{evidence_kind} infrastructure error"
+ elif counts["passed"] == total:
+ state = f"{evidence_kind} passed"
+ else:
+ state = f"{evidence_kind} incomplete"
+ detail = (
+ f"{counts['passed']}/{total} checks passed; "
+ f"{counts['failed']} failed; {counts['infra_error']} infrastructure errors."
+ )
+ if evidence_kind != "exact":
+ detail += " This is not exact distro/full-install proof."
+ return state, detail
+
+
+def write_markdown(
+ path: Path,
+ catalog: dict[str, Any],
+ probes: list[dict[str, Any]],
+ results: list[dict[str, Any]],
+ metadata: dict[str, Any],
+) -> None:
+ counts = result_counts(results)
+ exact_probes = sum(probe["fidelity"] == "exact" for probe in probes)
+ proxy_probes = sum(probe["fidelity"] == "proxy" for probe in probes)
+ lines = [
+ "# ServerKit distro compatibility discovery",
+ "",
+ f"Generated: `{metadata['finished_at']}` ",
+ f"Host: `{md_escape(metadata['host'])}` ",
+ f"Docker: `{md_escape(metadata['docker_version'] or 'unavailable')}` ",
+ f"Modes: `{', '.join(metadata['modes'])}`",
+ "",
+ "## Result summary",
+ "",
+ f"- Published targets cataloged: **{len(catalog['targets'])}/25**",
+ f"- Concrete images selected: **{len(probes)}** "
+ f"({exact_probes} exact, {proxy_probes} vendor userland proxies)",
+ f"- Checks: **{len(results)}** — {counts['passed']} passed, "
+ f"{counts['failed']} failed, {counts['infra_error']} infrastructure errors",
+ "",
+ "> A quick pass proves shell syntax and source-level suites only. A provision pass proves",
+ "> that install.sh obtained a usable supported Python from real repositories. Neither is a",
+ "> full ServerKit install, systemd, nginx, firewall, kernel, hardware, LXC, or hypervisor pass.",
+ "",
+ "## All 25 published targets",
+ "",
+ "| Target | Published claim | Container evidence | Detail | Windows test path |",
+ "|---|---:|---|---|---|",
+ ]
+ for target in catalog["targets"]:
+ state, detail = target_evidence(target, results)
+ lines.append(
+ "| "
+ + " | ".join(
+ md_escape(value)
+ for value in (
+ f"{target['label']} {target['versions']}",
+ target["published_status"],
+ state,
+ detail,
+ target["windows_strategy"],
+ )
+ )
+ + " |"
+ )
+
+ lines.extend(
+ [
+ "",
+ "## Concrete probe results",
+ "",
+ "| Probe | Fidelity | Pulled identity | Mode | Result | Duration | Log |",
+ "|---|---|---|---|---:|---:|---|",
+ ]
+ )
+ for result in sorted(results, key=lambda item: (item["catalog_position"], MODES.index(item["mode"]))):
+ identity = result.get("identity", {})
+ pretty = identity.get("pretty_name") or "identity unavailable"
+ lines.append(
+ "| "
+ + " | ".join(
+ (
+ md_escape(f"{result['label']} (`{result['image']}`)"),
+ md_escape(result["fidelity"]),
+ md_escape(pretty),
+ md_escape(result["mode"]),
+ md_escape(result["status"]),
+ md_escape(f"{result['duration_s']:.1f}s"),
+ f"[log]({result['log']})",
+ )
+ )
+ + " |"
+ )
+ lines.extend(
+ [
+ "",
+ "## Interpretation",
+ "",
+ "- `failed` means the image ran and the ServerKit check returned non-zero. It is product evidence, not hidden as an expected failure.",
+ "- `infra_error` means the image could not be pulled/run or the harness timed out; it is not evidence that ServerKit failed.",
+ "- `base proxy` means only a related base distro ran. It must never be promoted to an exact distro support result.",
+ "- Full support numbers require the existing VM/systemd harnesses and special hosts listed in the target table.",
+ "",
+ ]
+ )
+ failed = [result for result in results if result["status"] == "failed"]
+ if failed:
+ lines.extend(
+ [
+ "## Failed-check details",
+ "",
+ "| Probe | Mode | First useful evidence |",
+ "|---|---|---|",
+ ]
+ )
+ for result in failed:
+ lines.append(
+ "| "
+ + " | ".join(
+ md_escape(value)
+ for value in (result["label"], result["mode"], result["detail"])
+ )
+ + " |"
+ )
+ lines.append("")
+ path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def parse_args() -> argparse.Namespace:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--mode", choices=("quick", "provision", "both"), default="both")
+ parser.add_argument(
+ "--only",
+ nargs="*",
+ default=[],
+ metavar="KEY",
+ help="probe keys, separated by spaces or commas",
+ )
+ parser.add_argument("--jobs", type=int, default=4, help="parallel image workers")
+ parser.add_argument("--include-legacy", action="store_true")
+ parser.add_argument("--no-pull", action="store_true", help="use cached images when present")
+ parser.add_argument("--remove-images", action="store_true", help="remove tested images after each probe")
+ parser.add_argument("--strict", action="store_true", help="exit non-zero for failed/infra checks")
+ parser.add_argument("--list", action="store_true", help="validate and list the catalog without Docker")
+ parser.add_argument("--output", type=Path, help="report directory (default: timestamped output)")
+ return parser.parse_args()
+
+
+def main() -> int:
+ args = parse_args()
+ catalog = load_catalog()
+ all_probes = flatten_probes(catalog, args.include_legacy)
+ selected_keys = normalize_only(args.only)
+ known_keys = {probe["key"] for probe in all_probes}
+ unknown = selected_keys - known_keys
+ if unknown:
+ print(f"Unknown probe key(s): {', '.join(sorted(unknown))}", file=sys.stderr)
+ return 2
+ probes = [
+ probe for probe in all_probes if not selected_keys or probe["key"] in selected_keys
+ ]
+
+ if args.list:
+ for target in catalog["targets"]:
+ keys = ", ".join(probe["key"] for probe in target.get("probes", [])) or "separate harness"
+ print(
+ f"{target['id']:<22} {target['published_status']:<10} "
+ f"{target['label']} {target['versions']}: {keys}"
+ )
+ print(f"\n25 targets; {len(all_probes)} runnable image probes")
+ return 0
+
+ if shutil.which("docker") is None:
+ print("Docker CLI is not on PATH", file=sys.stderr)
+ return 2
+ docker_version = docker_output(["version", "--format", "{{.Server.Version}} {{.Server.Os}}/{{.Server.Arch}}"])
+ if not docker_version:
+ print("Docker daemon is unavailable", file=sys.stderr)
+ return 2
+
+ modes = MODES if args.mode == "both" else (args.mode,)
+ run_stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+ run_dir = (args.output or (DEFAULT_OUTPUT_ROOT / run_stamp)).resolve()
+ run_dir.mkdir(parents=True, exist_ok=True)
+ metadata = {
+ "started_at": utc_now(),
+ "finished_at": None,
+ "host": f"{platform.system()} {platform.release()} {platform.machine()}",
+ "python": sys.version.split()[0],
+ "docker_version": docker_version,
+ "modes": list(modes),
+ "selected_probe_keys": [probe["key"] for probe in probes],
+ "jobs": max(1, args.jobs),
+ }
+ print(
+ f"ServerKit distro discovery: {len(probes)} images x {len(modes)} mode(s), "
+ f"{max(1, args.jobs)} workers",
+ flush=True,
+ )
+ print(f"Output: {run_dir}", flush=True)
+
+ results: list[dict[str, Any]] = []
+ with concurrent.futures.ThreadPoolExecutor(max_workers=max(1, args.jobs)) as pool:
+ future_to_probe = {
+ pool.submit(
+ run_probe,
+ probe,
+ modes,
+ run_dir,
+ args.no_pull,
+ args.remove_images,
+ ): probe
+ for probe in probes
+ }
+ for future in concurrent.futures.as_completed(future_to_probe):
+ probe = future_to_probe[future]
+ try:
+ probe_results = future.result()
+ except Exception as exc: # keep one harness bug from erasing the run
+ probe_results = [
+ result_for_pull_failure(
+ probe, mode, None, 0.0, f"unhandled harness error: {exc}"
+ )
+ for mode in modes
+ ]
+ results.extend(probe_results)
+ summary = ", ".join(
+ f"{result['mode']}={result['status']}" for result in probe_results
+ )
+ print(
+ f"[{len(results):>3}/{len(probes) * len(modes)}] "
+ f"{probe['label']}: {summary}",
+ flush=True,
+ )
+
+ results.sort(key=lambda item: (item["catalog_position"], MODES.index(item["mode"])))
+ metadata["finished_at"] = utc_now()
+ payload = {
+ "schema_version": 1,
+ "metadata": metadata,
+ "summary": result_counts(results),
+ "targets": catalog["targets"],
+ "results": results,
+ }
+ (run_dir / "report.json").write_text(
+ json.dumps(payload, indent=2) + "\n", encoding="utf-8"
+ )
+ write_markdown(run_dir / "report.md", catalog, probes, results, metadata)
+
+ counts = payload["summary"]
+ print(
+ f"Done: {counts['passed']} passed, {counts['failed']} failed, "
+ f"{counts['infra_error']} infrastructure errors",
+ flush=True,
+ )
+ print(f"Report: {run_dir / 'report.md'}", flush=True)
+ if args.strict and (counts["failed"] or counts["infra_error"]):
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/scripts/test/run-distro-quick.sh b/scripts/test/run-distro-quick.sh
new file mode 100644
index 00000000..01907f98
--- /dev/null
+++ b/scripts/test/run-distro-quick.sh
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Syntax + source-level installer suites. This deliberately avoids systemd,
+# nginx, Docker-in-Docker, and real host mutation; those belong to the VM and
+# full-container harnesses.
+set -uo pipefail
+
+SOURCE_DIR="${SERVERKIT_SOURCE_DIR:-/src}"
+cd "$SOURCE_DIR" || exit 2
+
+fail=0
+for file in serverkit install.sh uninstall.sh scripts/*.sh scripts/lib/*.sh scripts/test/*.sh; do
+ [ -f "$file" ] || continue
+ if bash -n "$file"; then
+ printf 'ok %s\n' "$file"
+ else
+ printf 'FAIL %s\n' "$file"
+ fail=1
+ fi
+done
+
+for suite in \
+ test_update \
+ test_install \
+ test_lib \
+ test_cli \
+ test_agent_install \
+ test_stage \
+ test_release_workflow; do
+ printf '=== %s ===\n' "$suite"
+ bash "scripts/test/$suite.sh" || fail=1
+done
+
+if [ "$fail" -eq 0 ]; then
+ printf 'QUICK_RESULT=PASS\n'
+else
+ printf 'QUICK_RESULT=FAIL\n'
+fi
+exit "$fail"