Skip to content

Self-hosted monitoring for homelabs: host and container metrics and uptime checks from all your machines in one dashboard, with an optional AI agent that diagnoses incidents and suggests fixes.

refactor(version): read the version from one VERSION file

Karlo Kajba Šimanićf775c00e80b1
diff --git a/.github/workflows/images.yml b/.github/workflows/images.yml
index f28955d..13a958e 100644
--- a/.github/workflows/images.yml
+++ b/.github/workflows/images.yml
@@ -1,5 +1,6 @@
# Builds the collector, Docker proxy and system helper images and publishes them to GHCR, signed
-# with cosign (keyless, using this workflow's identity). Runs when a version tag is pushed:
+# with cosign (keyless, using this workflow's identity). Runs when a version tag is pushed; the tag must match
+# the VERSION file:
# git tag v0.1.0 && git push origin v0.1.0
# Remote hosts install from these images, pinned by digest, so no code is ever fetched from the
# dashboard. Third-party actions are pinned to commit hashes; update them deliberately.
@@ -26,6 +27,13 @@ jobs:
- { name: system-helper, dockerfile: docker/system-helper.Dockerfile }
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+ # The images report the version in VERSION, so a tag that says otherwise would publish mislabelled images.
+ - name: The tag matches VERSION
+ run: |
+ if [ "${GITHUB_REF_NAME#v}" != "$(cat VERSION)" ]; then
+ echo "::error::Tag ${GITHUB_REF_NAME} doesn't match VERSION ($(cat VERSION)). Update VERSION first, then tag."
+ exit 1
+ fi
- uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3
- uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
- uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
diff --git a/TESTS.md b/TESTS.md
index 25061b0..1b545b7 100644
--- a/TESTS.md
+++ b/TESTS.md
@@ -4,7 +4,7 @@ Infradeck ships with an automated test suite. This page explains how to run it,
covers (and what it doesn't), and what every single test is for, so you can decide
whether a failure matters before you upgrade or change your setup.
-- **1435 test cases** from 773 test functions, plus 38 small tests of the frontend helpers (see [Frontend helper tests](#frontend-helper-tests)) (some functions run once per input).
+- **1438 test cases** from 776 test functions, plus 38 small tests of the frontend helpers (see [Frontend helper tests](#frontend-helper-tests)) (some functions run once per input).
- **About two minutes** to run. No Docker, PostgreSQL, Redis, network or root access needed.
- **Safe to run next to a live install.** The tests use a throwaway in-memory database
and fakes; they never touch your running containers or your data. (Two collector
@@ -131,7 +131,7 @@ side and the backend's side in one file, because the feature only works when bot
| Folder | What is in it |
|---|---|
| `tests/accounts/` | Sign-in, two-factor, sessions, passwords, roles and the admin settings. |
-| `tests/collectors/` | Adding and trusting collectors (enrollment, approval, pending servers, the dashboard's own machine), what they report and how it is validated, the filesystems they report, and the read-only Docker proxy. |
+| `tests/collectors/` | Adding and trusting collectors (enrollment, approval, pending servers, the dashboard's own machine), what they report and how it is validated, the filesystems they report, the read-only Docker proxy, and the version they report. |
| `tests/monitoring/` | What is watched and how it turns into incidents: the alert engine and its rules, system, container and network checks, the system helper and the container details. |
| `tests/history/` | Long-term history: rollups, the history API, statistics and the database indexes behind them. |
| `tests/assistant/` | The AI assistant: its fixed health checks, error messages and conversations. |
@@ -178,6 +178,7 @@ The chart helper tests for the frontend are separate, in `src/frontend/tests/`.
| [`test_system_checks.py`](#test_system_checkspy) | 17 | Reboot, OOM, kernel-fault, clock and pending-reboot detection, and the System row's event list. |
| [`test_system_helper.py`](#test_system_helperpy) | 35 | The optional system helper: kernel-log parsing, `wtmp`, crash detection, hostile input. |
| [`test_trusted_proxies.py`](#test_trusted_proxiespy) | 17 | Whose `X-Forwarded-For` nginx believes: nobody by default, only addresses and CIDR ranges from `TRUSTED_PROXIES`. |
+| [`test_version.py`](#test_versionpy) | 3 | The dashboard and the collector report the version from the one `VERSION` file. |
## Every test, explained
@@ -1125,6 +1126,17 @@ settings that decide whose `X-Forwarded-For` is believed. These tests run the re
| `test_each_proxy_is_trusted_and_the_header_read_from_it` | IPv4 and IPv6 addresses and ranges, with or without spaces, each become a trusted proxy, and the header is read from them. |
| `test_anything_but_addresses_stops_the_container` *(11 inputs)* | Injected nginx directives, a line break, `*`, host names, shell commands and malformed ranges stop the container; nothing is written. |
+### test_version.py
+
+The version is written once, in `VERSION` at the repository root. If these fail, the dashboard could call an
+outdated collector "up to date", or the other way round.
+
+| Test | What it checks |
+|---|---|
+| `test_the_dashboard_and_the_collector_report_the_version_in_the_version_file` | The backend and the collector both report the version in `VERSION`, and it looks like `1.2.3`. |
+| `test_the_collector_image_reads_the_version_file_next_to_it` | In the collector image, `VERSION` sits next to `collector.py` and is read from there. |
+| `test_a_collector_without_a_version_file_says_dev` | A collector copied somewhere without `VERSION` reports `dev` instead of failing. |
+
## Frontend helper tests
The chart helpers (axis ticks, gaps, histograms, the hour-by-weekday grid, donut slices, the
diff --git a/VERSION b/VERSION
new file mode 100644
index 0000000..78bc1ab
--- /dev/null
+++ b/VERSION
@@ -0,0 +1 @@
+0.10.0
diff --git a/docker/backend.Dockerfile b/docker/backend.Dockerfile
index 179e4cf..1f9fbdc 100644
--- a/docker/backend.Dockerfile
+++ b/docker/backend.Dockerfile
@@ -6,6 +6,7 @@ COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY src ./src
+COPY VERSION ./VERSION
# Runs as an unprivileged user with a fixed UID; the code is owned by root, so it can't change it.
RUN useradd --system --uid 10001 --no-create-home --shell /usr/sbin/nologin infradeck
diff --git a/docker/collector.Dockerfile b/docker/collector.Dockerfile
index f8f3ef6..7fe44ac 100644
--- a/docker/collector.Dockerfile
+++ b/docker/collector.Dockerfile
@@ -3,6 +3,7 @@ FROM python:3.12-alpine
WORKDIR /app
COPY src/collector/collector.py ./collector.py
+COPY VERSION ./VERSION
ENV INFRADECK_STATE_DIR=/var/lib/infradeck-collector \
HOST_PROC=/host/proc \
diff --git a/docs/deployment.md b/docs/deployment.md
index f0f1149..a588c02 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -114,12 +114,16 @@ Things to get right:
Remote machines install the collector and the Docker proxy from container images,
pinned by digest, so no code is ever downloaded from the dashboard. The
[Publish images](../.github/workflows/images.yml) workflow builds them (amd64 and
-arm64), signs them with cosign and prints their digests:
+arm64), signs them with cosign and prints their digests. The version lives in one place, the `VERSION` file
+at the repository root; the dashboard and the collector both read it. Tag the version it holds:
```bash
-git tag v0.9.2 && git push origin v0.9.2 # the version in src/backend/config.py
+git tag "v$(cat VERSION)" && git push origin "v$(cat VERSION)"
```
+For a new version, change `VERSION` in a pull request first and tag after it is merged. The workflow refuses a
+tag that doesn't match `VERSION`, so the images never report a different version than their tag.
+
1. Open the workflow run's summary and copy the `COLLECTOR_IMAGE=…` and
`DOCKER_PROXY_IMAGE=…` lines into `.env`.
2. Make the three packages **public** (GitHub → your profile → Packages → each of `infradeck/collector`,
diff --git a/src/backend/config.py b/src/backend/config.py
index e0d848b..2b5e1f0 100644
--- a/src/backend/config.py
+++ b/src/backend/config.py
@@ -10,8 +10,9 @@ for _name, _value in dotenv_values(BASE_DIR / ".env").items():
if _value:
os.environ.setdefault(_name, _value)
-# Shown in the sidebar and compared with what each collector reports.
-APP_VERSION = "0.10.0"
+# Shown in the sidebar and compared with what each collector reports. VERSION at the repository root is the
+# only place the version is written; the backend image copies it to /app/VERSION.
+APP_VERSION = (BASE_DIR / "VERSION").read_text().strip()
DATABASE_URL = os.getenv(
"DATABASE_URL",
diff --git a/src/collector/collector.py b/src/collector/collector.py
index ec15205..cba1600 100644
--- a/src/collector/collector.py
+++ b/src/collector/collector.py
@@ -512,7 +512,20 @@ def collect_system() -> dict[str, Any]:
}
-COLLECTOR_VERSION = "0.10.0"
+def _read_version():
+ """The release this collector belongs to: VERSION next to this file in the image, or at the repository root
+ when run from a checkout. "dev" when neither exists."""
+ here = os.path.dirname(os.path.abspath(__file__))
+ for path in (os.path.join(here, "VERSION"), os.path.join(here, "..", "..", "VERSION")):
+ try:
+ with open(path, encoding="utf-8") as file:
+ return file.read().strip()
+ except OSError:
+ continue
+ return "dev"
+
+
+COLLECTOR_VERSION = _read_version()
MAX_INTERFACES = 16
MAX_TEMPERATURES = 8
_KERNEL_IMAGE = re.compile(r"vmlinuz-(\d[\w.+~-]*)")
diff --git a/tests/collectors/test_version.py b/tests/collectors/test_version.py
new file mode 100644
index 0000000..435d47e
--- /dev/null
+++ b/tests/collectors/test_version.py
@@ -0,0 +1,31 @@
+"""VERSION at the repository root is the only place the version is written. The dashboard and the collector both
+read it, so "Collector: up to date" compares two copies of the same value."""
+import re
+from pathlib import Path
+
+from src.backend import config
+from src.collector import collector
+
+VERSION_FILE = Path(__file__).resolve().parents[2] / "VERSION"
+
+
+def test_the_dashboard_and_the_collector_report_the_version_in_the_version_file():
+ version = VERSION_FILE.read_text().strip()
+
+ assert re.fullmatch(r"\d+\.\d+\.\d+", version)
+ assert config.APP_VERSION == collector.COLLECTOR_VERSION == version
+
+
+def test_the_collector_image_reads_the_version_file_next_to_it(tmp_path, monkeypatch):
+ (tmp_path / "VERSION").write_text("9.8.7\n")
+ monkeypatch.setattr(collector, "__file__", str(tmp_path / "collector.py"))
+
+ assert collector._read_version() == "9.8.7"
+
+
+def test_a_collector_without_a_version_file_says_dev(tmp_path, monkeypatch):
+ folder = tmp_path / "a" / "b"
+ folder.mkdir(parents=True)
+ monkeypatch.setattr(collector, "__file__", str(folder / "collector.py"))
+
+ assert collector._read_version() == "dev"