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.

fix(installer): provision native Python build dependencies (#148)

Juan Denisb63427e2a245
diff --git a/.github/workflows/scripts-ci.yml b/.github/workflows/scripts-ci.yml
index ecf9aeb8..5715c4a3 100644
--- a/.github/workflows/scripts-ci.yml
+++ b/.github/workflows/scripts-ci.yml
@@ -110,6 +110,7 @@ jobs:
image:
- 'ubuntu:22.04'
- 'ubuntu:24.04'
+ - 'ubuntu:26.04'
- 'debian:12'
# Debian 13 (trixie) ships ONLY python3.13 — no 3.11, no 3.12. Issue
# #99: the installer's version gate could not be satisfied from its
@@ -232,6 +233,7 @@ jobs:
image:
- 'ubuntu:22.04'
- 'ubuntu:24.04'
+ - 'ubuntu:26.04'
- 'debian:12'
- 'debian:13'
- 'rockylinux:9'
diff --git a/backend/app/data/distro-catalog.json b/backend/app/data/distro-catalog.json
index 8a5ae200..57d9db4f 100644
--- a/backend/app/data/distro-catalog.json
+++ b/backend/app/data/distro-catalog.json
@@ -5,7 +5,7 @@
{
"id": "ubuntu",
"label": "Ubuntu",
- "versions": "22.04 LTS, 24.04 LTS",
+ "versions": "22.04 LTS, 24.04 LTS, 26.04 LTS",
"family": "debian",
"published_status": "tested",
"architectures": ["amd64", "arm64"],
@@ -24,6 +24,13 @@
"image": "ubuntu:24.04",
"fidelity": "exact",
"full_image": "geerlingguy/docker-ubuntu2404-ansible:latest"
+ },
+ {
+ "key": "ubuntu26",
+ "label": "Ubuntu 26.04",
+ "image": "ubuntu:26.04",
+ "fidelity": "exact",
+ "full_image": null
}
]
},
diff --git a/backend/tests/test_test_sandbox_catalog.py b/backend/tests/test_test_sandbox_catalog.py
index 20c48935..873ac74b 100644
--- a/backend/tests/test_test_sandbox_catalog.py
+++ b/backend/tests/test_test_sandbox_catalog.py
@@ -26,9 +26,9 @@ def test_catalog_has_all_25_published_targets_and_unique_probes():
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 len(probes) == 26
+ assert len({probe['key'] for probe in probes}) == 26
+ assert sum(probe['fidelity'] == 'exact' for probe in probes) == 23
assert sum(probe['fidelity'] == 'proxy' for probe in probes) == 3
@@ -45,6 +45,8 @@ def test_sandbox_registry_is_generated_from_catalog_plus_legacy_probes():
assert {'debian13', 'rocky10', 'alma10', 'centosstream10', 'arch', 'gentoo'} <= set(DISTROS)
assert DISTROS['rhel10ubi']['fidelity'] == 'proxy'
assert DISTROS['ubuntu24']['full_image']
+ assert DISTROS['ubuntu26']['quick_image'] == 'ubuntu:26.04'
+ assert DISTROS['ubuntu26']['full_image'] is None
assert DISTROS['rocky10']['full_image'] is None
diff --git a/install.sh b/install.sh
index 66db5279..bab571c2 100644
--- a/install.sh
+++ b/install.sh
@@ -800,12 +800,60 @@ build_python_from_source() {
return 0
}
+python_build_ready() {
+ command -v make >/dev/null 2>&1 || return 1
+ # Compile against THIS interpreter's headers, including pyconfig.h. Merely
+ # finding a Python executable or a different version's -dev package is not
+ # enough for pip's native dependencies (issue #148).
+ "$PYTHON_BIN" - <<'PY' >/dev/null 2>&1
+import pathlib
+import shlex
+import subprocess
+import sysconfig
+import tempfile
+
+with tempfile.TemporaryDirectory(prefix='serverkit-python-build-') as work:
+ source = pathlib.Path(work) / 'probe.c'
+ source.write_text('#include <Python.h>\nint main(void) { return 0; }\n')
+ includes = {sysconfig.get_path('include'), sysconfig.get_path('platinclude')}
+ command = shlex.split(sysconfig.get_config_var('CC') or 'cc')
+ command += ['-I' + path for path in includes if path]
+ command += ['-c', str(source), '-o', str(pathlib.Path(work) / 'probe.o')]
+ subprocess.run(command, check=True)
+PY
+}
+
+ensure_python_build_deps() {
+ python_build_ready && return 0
+ local v
+ v=$("$PYTHON_BIN" -c 'import sys;print(".".join(map(str,sys.version_info[:2])))')
+ step "Installing build tools and headers for Python $v..."
+ refresh_pkg_index
+ case "$OS_FAMILY" in
+ debian) pkg_add build-essential "python${v}-dev" ;;
+ fedora|rhel) pkg_add gcc make "python${v}-devel" ;;
+ suse) pkg_add gcc make "python${v//./}-devel" ;;
+ arch) pkg_add base-devel python ;;
+ alpine) pkg_add build-base python3-dev ;;
+ gentoo) pkg_add sys-devel/gcc sys-devel/make "dev-lang/python:${v}" ;;
+ esac
+ # pkg_add deliberately warns and continues. Probe again so failure is
+ # reported here, rather than much later as an opaque pip build failure.
+ if ! python_build_ready; then
+ halt "Native Python dependencies cannot be built with $PYTHON_BIN (Python $v).
+ Install a C compiler, make, and the matching Python development headers, then re-run.
+ On Debian/Ubuntu: apt-get install build-essential python${v}-dev"
+ return 1
+ fi
+}
+
provision_python() {
phase "Installing Python"
- # Already have a supported interpreter? Nothing to do.
+ # Existing interpreters may have venv support but no development headers.
if locate_python; then
- return
+ ensure_python_build_deps
+ return $?
fi
warn "No supported Python ($PYTHON_MIN–$PYTHON_MAX) found — installing one."
@@ -818,6 +866,12 @@ provision_python() {
# state probe (command -v) to decide whether the next fallback is needed.
if [ "$OS_FAMILY" = "debian" ]; then
if [ "${ID:-}" = "ubuntu" ]; then
+ refresh_pkg_index
+ pkg_add python3 python3-venv python3-dev
+ if locate_python; then
+ ensure_python_build_deps
+ return $?
+ fi
pkg_add python3.12 python3.12-venv python3.12-dev
if ! command -v python3.12 &>/dev/null; then
step "Adding deadsnakes PPA for Python 3.12..."
@@ -870,7 +924,8 @@ provision_python() {
# Did a distro package give us something usable?
if locate_python; then
good "Python ready: $PYTHON_BIN"
- return
+ ensure_python_build_deps
+ return $?
fi
# Last resort: compile from source.
@@ -910,6 +965,7 @@ provision_python() {
command -v "$PYTHON_BIN" &>/dev/null || \
halt "Could not install a supported Python — install Python $PYTHON_MIN-$PYTHON_MAX by hand."
good "Python installed ($PYTHON_BIN)."
+ ensure_python_build_deps
}
# ---------------------------------------------------------------------------
diff --git a/scripts/test/README.md b/scripts/test/README.md
index a5c663a2..3034c681 100644
--- a/scripts/test/README.md
+++ b/scripts/test/README.md
@@ -184,6 +184,9 @@ 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
+
+# Installer #148 regression: includes Ubuntu 26.04's Python 3.14
+python .\scripts\test\distro-compatibility.py --only ubuntu26,ubuntu24,debian13 --mode provision --strict
```
Each run writes `report.md`, `report.json`, image-pull logs, and one log per
@@ -196,7 +199,9 @@ 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.
+ Python, venv, pip, SSL, SQLite, ctypes, and a source build/import of the pinned
+ gevent dependency. Ubuntu 26.04 also installs all backend requirements and
+ runs `pip check`.
Neither mode proves systemd, nginx, firewall behavior, Docker-in-Docker,
kernel-specific behavior, LXC nesting, a hypervisor, or Raspberry Pi hardware.
diff --git a/scripts/test/distro-compatibility.py b/scripts/test/distro-compatibility.py
index 31fd4ae0..178a4e44 100644
--- a/scripts/test/distro-compatibility.py
+++ b/scripts/test/distro-compatibility.py
@@ -6,7 +6,8 @@ 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
+ virtualenv, pip, ssl, sqlite3, ctypes, and native dependency builds through
+ install.sh (Ubuntu 26.04 also verifies the full backend requirements)
It does not prove systemd, nginx, Docker-in-Docker, firewall behavior, a full
ServerKit install, a distro-specific kernel, or hardware. The generated report
diff --git a/scripts/test/test_install.sh b/scripts/test/test_install.sh
index 889b70da..11e14d63 100644
--- a/scripts/test/test_install.sh
+++ b/scripts/test/test_install.sh
@@ -2239,6 +2239,69 @@ else
bad "pkg_add's apt branch can block on a debconf prompt: [$apt_line]"
fi
+# Issue #148: reusing an interpreter must still provision matching headers.
+if ( set -Eeuo pipefail
+ OS_FAMILY=debian; ID=ubuntu
+ locate_python() { PYTHON_BIN=python3.14; return 0; }
+ python3.14() { printf '3.14\n'; }
+ ready=0
+ python_build_ready() { [ "$ready" = 1 ]; }
+ refresh_pkg_index() { :; }
+ pkg_add() {
+ [ "$*" = 'build-essential python3.14-dev' ] || exit 1
+ ready=1
+ }
+ provision_python >/dev/null
+ [ "$ready" = 1 ]
+); then
+ ok "existing Python 3.14 gets matching headers and build tools"
+else
+ bad "existing Python skips native build prerequisites"
+fi
+
+if ( set -Eeuo pipefail
+ OS_FAMILY=debian; PYTHON_BIN=python3.14
+ python3.14() { printf '3.14\n'; }
+ python_build_ready() { return 1; }
+ refresh_pkg_index() { :; }
+ pkg_add() { return 0; } # warn-and-continue package failure
+ halt() { return 1; }
+ ensure_python_build_deps >/dev/null 2>&1
+); then
+ bad "missing headers were accepted after package installation failed"
+else
+ ok "missing build prerequisites fail before pip"
+fi
+
+if ( set -Eeuo pipefail
+ OS_FAMILY=debian; ID=ubuntu; installed=0; checked=0
+ locate_python() { [ "$installed" = 1 ] && { PYTHON_BIN=python3.14; return 0; }; return 1; }
+ refresh_pkg_index() { :; }
+ pkg_add() {
+ [ "$*" = 'python3 python3-venv python3-dev' ] || exit 1
+ installed=1
+ }
+ ensure_python_build_deps() { checked=1; }
+ add-apt-repository() { exit 1; }
+ provision_python >/dev/null
+ [ "$installed" = 1 ] && [ "$checked" = 1 ]
+); then
+ ok "Ubuntu uses its supported default Python without a PPA"
+else
+ bad "Ubuntu did not use its default Python first"
+fi
+
+if ( set -Eeuo pipefail
+ python_build_ready() { return 0; }
+ pkg_add() { exit 1; }
+ refresh_pkg_index() { exit 1; }
+ ensure_python_build_deps
+); then
+ ok "working native build environment needs no package changes"
+else
+ bad "working native build environment tried to install packages"
+fi
+
# -- static guard: the documented insecure site must keep shipping, since both
# the docs and SERVERKIT_EXTERNAL_PROXY point operators straight at it.
if [ -f "$REPO_DIR/nginx/sites-available/serverkit-insecure.conf" ] \
diff --git a/scripts/test/test_provision_python.sh b/scripts/test/test_provision_python.sh
index 84a291b4..c85f5d28 100644
--- a/scripts/test/test_provision_python.sh
+++ b/scripts/test/test_provision_python.sh
@@ -165,6 +165,28 @@ else
else
bad "it cannot create a virtualenv"
fi
+ # Force a source build: a cached/platform wheel would hide missing Python.h
+ # and compilers, the exact gap behind issue #148. Use the production pin.
+ native_requirement=$(grep '^gevent==' "$REPO_DIR/backend/requirements.txt")
+ if /tmp/pp-venv/bin/python -m pip install --no-cache-dir --no-binary=gevent \
+ "$native_requirement" >/tmp/pp-native.log 2>&1 \
+ && /tmp/pp-venv/bin/python -c 'import gevent' >/dev/null 2>&1; then
+ ok "the pinned gevent dependency builds from source and imports"
+ else
+ bad "native dependency build failed"
+ tail -40 /tmp/pp-native.log
+ fi
+ # Ubuntu 26.04 is the regression target; validate all backend pins there.
+ if [ "${ID:-}" = ubuntu ] && [ "${VERSION_ID:-}" = 26.04 ]; then
+ if /tmp/pp-venv/bin/python -m pip install \
+ -r "$REPO_DIR/backend/requirements.txt" >/tmp/pp-requirements.log 2>&1 \
+ && /tmp/pp-venv/bin/python -m pip check >>/tmp/pp-requirements.log 2>&1; then
+ ok "all backend requirements install with consistent dependencies"
+ else
+ bad "backend requirements failed"
+ tail -40 /tmp/pp-requirements.log
+ fi
+ fi
rm -rf /tmp/pp-venv
fi