Homelab instance documentation

Before local commits, install native Gitleaks 8.30.1 and run sh .githooks/install.sh (Git Bash on Windows). See local secret prevention for clone/worktree setup. Existing CI source/history scanning remains required.

This public repository documents this Homelab installation: UDS on a four-node RKE2 cluster, its network and storage boundaries, application placement, delivery model, and verified operating state. It contains no credentials or live Secret values. The homelab wiki is a generic research and historical reference; new instance-specific architecture, decisions, status, and procedures belong here.

The same Markdown pages power a Next.js App Router documentation site. Its landing page is an index of dated instance notes and a manually maintained roadmap snapshot. On 2026-10-17, direct browser inspection confirmed that https://doc.app.gitchegumi.com/docs/architecture/ serves the public documentation without an SSO redirect. This verifies page reachability from the inspecting client; the exact deployed release and external-network path were not audited. Production configuration uses the existing UDS tenant gateway with no SSO or authservice integration.

The copied Magic UI component retains its MIT notice.

The records below were reconciled on 2026-09-24 from the existing wiki, owning repositories, issues, and owner-reported results. This is a documented baseline, not a fresh live-cluster audit. Treat a dated observation as evidence for that date, not as a continuously verified health claim. The owning repository holds deployable configuration and detailed operator runbooks; its issue holds acceptance evidence. Recheck the live system before changing it.

Start here	What it records
Architecture	Nodes, DNS, VIPs, ingress, external dependencies, and trust boundaries
Platform	RKE2, UDS Core, networking, certificates, secrets, GPU, and runners
Applications	Production services, migration targets, hostnames, and retained TrueNAS services
Storage and recovery	TrueNAS CSI, static and local volumes, backup and rollback boundaries
Delivery and operations	UDS artifacts, Forgejo Actions, image scanning, deployment and verification
Decisions and open work	Chosen direction, incomplete transitions, and issue links
Source register	Evidence dates, implementation owners, and how to update these pages

Status words have precise meanings here: deployed means an owner or cited run confirmed the live change; tested means a bounded test passed; prepared means configuration or an artifact exists but the live result is not confirmed; planned means a selected direction without completed implementation. A successful build is not a deployment, and a deployed manifest is not proof of end-to-end behavior.

Do not commit passwords, tokens, kubeconfigs, private keys, unseal material, live Kubernetes Secret data, credential-bearing URLs, or generated artifacts. Secret names and non-secret contracts may be documented where useful. Review every public diff for accidental disclosure, including copied logs and screenshots. See documentation maintenance.

Local site development

Use Node.js 22 or newer:

npm ci
npm run dev

Open http://localhost:3000. Before a pull request or publication:

npm run check
npm run build

npm run check verifies TypeScript, local Markdown links, the dynamic document route, and the production UDS routing/security contract. npm run build generates the standalone server in ignored .next/standalone/. Add or edit instance facts in docs/*.md; the page index discovers new Markdown files from the reviewed main branch at runtime. Add an entry to lib/docs.ts when a new page needs a custom title, summary, or group. Keep JSX focused on navigation and presentation. No deployment or live-cluster access is required for these checks.

The production server reads the public main branch of this repository through Forgejo's contents and raw-file endpoints. It refreshes the page list within 60 seconds; Markdown is fetched for each page request. New Markdown files with lowercase hyphenated names appear in the Reference group automatically. If Forgejo is unavailable, the server serves the documents bundled with its image. Its pods therefore need outbound HTTPS access to git.gitchegumi.com; confirm that path before deploying. The site reads main only, never pull-request branches. Source code and layout changes still require a scanned image and bundle release.

Architecture diagrams are self-contained SVGs in public/diagrams/. Use https://git.gitchegumi.com/Homelab/Documentation/media/branch/main/public/diagrams/<name>.svg for both Markdown images and full-size links. The deployed renderer already supports these URLs: browsers load the reviewed main files directly instead of the image's older bundled /diagrams/ copies. Markdown and diagram content updates take effect after merge and page refresh, without an image build, bundle release or deployment. Keep meaningful alt text and the surrounding state/evidence explanation with each chart. Images scroll horizontally on narrow screens and have full-size links. Diagram availability depends on Forgejo; application code and layout changes still use the reviewed release pipeline.

Security and release path

Pull requests and main pushes run Documentation site checks and the checkout-based Homelab/workflows stable-v1 source-security gate. Source validation, image, bundle and deploy callers select this channel with no explicit library_ref. The channel selected v1.44.5 when inspected on 2026-10-17; each run records its actual immutable library binding. The shared npm validator preserves npm ci, npm run check and npm run build; bundle validation also runs npm run check:deployment:published. It configures a writable job-local Node cache before setup. The security gate evaluates Gitleaks history/source findings, Trivy dependencies and configuration, Semgrep, ClamAV, and Kubernetes schema checks for the standard workload resources. Blocking findings and scanner errors stop the run, except ClamAV operational errors are reported as warnings; actual malware detections block. .pipeline/mitigations.json starts empty. The two custom resources, UDS Package and Istio VirtualService, are checked by scripts/check-deployment.mjs for the public host, gateway, ingress selector, and absence of SSO.

The protected, manual Build scanned documentation image workflow uses a pinned Node build stage and a pinned non-root Node.js runtime. It builds, scans the source and final image, signs evidence, and publishes the scanned image to git.gitchegumi.com/homelab/documentation. The separate manual Build signed documentation bundle workflow validates the reviewed production manifests, scans the pinned image again, and publishes a signed UDS release. These jobs use the existing organization-level signing and registry secrets and DEPLOY_ACTORS/REGISTRY_HOST variables; the bundle job also needs SIGNING_PUBLIC_KEY, RELEASE_READ_TOKEN, and read access to the image registry. Grant the release-read identity access to this new repository if its token is restricted by repository. No credential values belong in Git.

The manual builds accept optional release_tag names such as documentation-image-v1 and documentation-bundle-v1. Blank inputs produce component/version/run names without hashes. Existing tags cannot be reused, and existing signed releases remain deployable under their original tags.

Published 2026-10-17: documentation-image-v0.0.1 records the chart image at git.gitchegumi.com/homelab/documentation@sha256:6ae179adf61bf21b224330eeb0cbee4ada47f4deab031da1426993c26087cc55, with signed scan evidence attached. Both production image references select that digest. The owner confirmed release and deployment of the charts on 2026-10-17; browser inspection that day confirmed both SVGs load on the live architecture page. The delivery record preserves the earlier failed attempts and the correction to load chart content from main without rebuilding.

The immutable image reference in manifests/prod/workload.yaml and zarf.yaml must match a successful scanned publication. For application code or layout changes, the release sequence is:

1. Merge reviewed source changes and confirm both commit-time jobs pass on main.
2. Manually run Build scanned documentation image from protected main. Record the published repository@sha256:digest and signed evidence from its successful run.
3. Pin that same exact digest in manifests/prod/workload.yaml and zarf.yaml. Review and commit both files, then verify the new source-security and site-check runs. npm run check:deployment:published must pass.
4. Manually run Build signed documentation bundle from protected main. The workflow refuses an unpublished placeholder, rescans the selected image, and publishes a signed release. A passing site build or container build alone is not a released bundle. The first signed production bundle is release ci-cad9a4195befd865d78322ecff4a227ae2201834-4910, published on 2026-09-24; publication is not deployment.
5. After reviewing the release and target prerequisites, manually run Deploy signed documentation bundle in this repository from protected main, entering the exact signed readable release tag, for example documentation-bundle-v1. The paired bundle and deploy callers select Homelab/workflows@stable-v1 and retain the existing organization registry credential bindings. The deploy caller selects production only. Its deploy runner downloads the release, verifies signature, provenance and artifact hashes, checks the target and scoped OpenBao-issued credentials, refreshes image security evidence, deploys the same UDS archive, and checks rollout and HTTPS health. It does not rebuild the archive. Do not dispatch it from the workflows library repository.

The deploy caller requires the platform's prod-only managed onboarding support to be merged and reconciled for this repository before its first run. .pipeline/onboarding.json requests only the documentation production identity; it creates no dev identity. The organization deployment variables and the existing signing, release-read and registry-read secrets must be available to this caller. A missing or unready credential contract fails the deployment rather than falling back to a shared kubeconfig.

Deployment prerequisites and verification

Production uses the existing istio-tenant-gateway/tenant-gateway and its certificate for *.app.gitchegumi.com; it creates no new gateway, certificate, public forwarding rule, or SSO client. Before dispatch, confirm the gateway and certificate are ready, doc.app.gitchegumi.com resolves through the intended internal and public edge, and no other VirtualService owns that host. The deploy pipeline checks its approved cluster context and the gateway's HTTPS host coverage. A release or workflow configuration alone is not evidence that this site has been deployed.

Review the deploy run's signature/hash, security, credential, rollout and HTTPS steps. Verify public responses do not redirect to Keycloak, internal and external clients can reach the intended edge, and pods can fetch this repository's public main documentation endpoints. After a reviewed Markdown change lands on main, verify the public page updates within a minute without an image rebuild. The application has no persistent data; rollback is a manual dispatch of the same deploy workflow with the prior accepted release tag, leaving the shared gateway and certificate untouched.