Skip to content
Homelab Infrastructure

Versions Service

Overview

Section titled “Overview”

Versions Service is an automated metadata aggregator and JSON endpoint running on the homelab. It collects and presents detailed, nested version information for all active system components, NixOS software, Home Assistant core, HACS custom components, Python packages, and Podman containers.

The service is defined in modules/nixos/services/versions.nix and the generator script in modules/nixos/services/versions-generator.py.

Architecture

Section titled “Architecture”
graph LR
    SystemD[Systemd Timer: 05:00 AM / Rebuild] -->|Execute| Generator[versions-generator.py]
    Generator -->|Write| Disk[/var/lib/versions/versions.json]
    Disk -->|Read| Nginx[Nginx :18900]
    Nginx -->|Expose| Web[https://versions-home.javiersc.com]

Data Discovery

Section titled “Data Discovery”

The service relies on 100% dynamic runtime discovery:

  • System: Queries NixOS release metadata, kernel version (uname -r), and CPU architecture.
  • Home Assistant: Reads Core version, glob-scans /var/lib/hass/custom_components/*/manifest.json for custom components, and inspects Python package distributions for dependencies.
  • Podman Containers: Queries podman ps and podman inspect to extract image tags, SHA256 digests, resolved container versions, and OpenContainer source/doc labels.
  • Homelab Proxies: Queries configured homelab proxy endpoints dynamically to extract service versions.
  • Metadata: Dynamically attaches GitHub repository (repository) and documentation (documentation) links for all items.

Ports & Networking

Section titled “Ports & Networking”
ServicePortProtocolDescription
Static Nginx18900HTTPServes static /var/lib/versions/versions.json

Access Policy

Section titled “Access Policy”
  • Local / Tailscale Network: Direct access via LAN or Mesh IP (nixos.local / versions-home.javiersc.com), requiring no authentication.
  • Public Internet: Routed through Cloudflare Tunnel where a Cloudflare Access policy blocks unauthorized remote requests.

Performance & State

Section titled “Performance & State”
  • Storage Location: /var/lib/versions/versions.json
  • Backup: State directory /var/lib/versions is included in Restic backups.
  • Overhead: 0ms CPU overhead during HTTP requests, as Nginx directly serves the pre-generated static JSON payload.

Operational Commands

Section titled “Operational Commands”

Manual Regeneration

Section titled “Manual Regeneration”
Terminal window
sudo systemctl start versions-generator.service

Checking Service Logs

Section titled “Checking Service Logs”
Terminal window
sudo journalctl -u versions-generator.service -n 50