Tech Coop Framework Homelab Pilot
GitHub Export PDF
Production Foundation • Live & Verified on core-node

Human-Scale Tech Sovereignty on Owned Hardware

A working technology cooperative platform engineered with homelab-first simplicity, Active Directory identity, verified restic backups, and strict operational discipline.

19 / 19
Automated Health Checks
0 Node.js
Production Runtime Overhead
~2,000
Append-Only Ops Log Lines
100%
Physical Hardware Sovereignty
Cooperative Strategy & Governance

Why Homelab-First Cooperative Infrastructure?

Modern cloud infrastructure traps community organizations in expensive recurring SaaS fees, vendor lock-in, and opaque data governance. The Tech Coop Framework proves that small communities can own, govern, and run their own resilient digital services on affordable local hardware.

Absolute Data Sovereignty

Member files, identities, and credentials never touch commercial third-party cloud servers. Data resides on owned physical NVMe storage with monthly offline air-gapped backups.

POSIX 0700 Isolation Zero SaaS Dependence

Rejecting SaaS Extravagance

Replaces thousands of dollars in annual Google Workspace, Microsoft 365, and Dropbox subscriptions with a single refurbished mini-PC server running open-source standards.

Low Power Usage Zero Ongoing Licensing

Steward-Friendly Continuity

Designed using the "Both Chairs" framework: weighing member convenience equally with steward maintenance toil. Written runbooks ensure any cooperative member can step in as administrator.

Runbook-First Policy Simple Reconciliation
Case Study in Systems Thinking

The Architectural Reboot: Salvage, Wipe, Rebuild

Before building the current resilient stack, an earlier prototype collapsed under the weight of premature abstraction. Here is how rigorous engineering discipline turned failure into durable success.

Dimension Earlier Prototype (v0 Collapse) Rebuilt Architecture (v1 Production)
Scoping Method 11 pre-declared theoretical IT departments with 30 interlocking specifications before any real user existed. Discovered from working needs. No abstract taxonomy; every service justified by real member demand.
Stack & Runtime Turborepo monorepo, pnpm, React, Vite, Hono API, heavy containerized OIDC orchestrations. Pure Go static binaries (`CGO_ENABLED=0`), vendored vanilla htmx, zero runtime Node.js overhead.
Validation Milestone Unresolved governance and legal entity definitions blocked basic software progress. The First Real Transaction: A second real member (`member.one`) authenticating and storing private files.
Documentation Uniform ceremonial paperwork applied identically to trivial and irreversible choices alike. Runbook-first (Rule 5): Human written steps before automation; ADRs reserved only for irreversible choices.
Infrastructure Deep Dive

Production Topology & Component Map

Every component on `core-node` serves a distinct, least-privilege role. Below is the network and service routing architecture.

TRUSTED LAN CLIENTS 10.0.0.0 / 24 Subnet Member Workstations macOS / Windows / Linux Mobile Devices iOS & Android Browsers Steward Console Admin UI & Terminal SSH CORE-NODE (10.0.0.10) x86-64 Mini-PC • Linux OS Edge Caddy Reverse Proxy (:443) TLS Termination • Internal CA • Route Isolation Samba4 AD DC DNS :53 • Kerberos :88 Blocky DNS :5335 DoT to Quad9 • Ad Filter SMB Shares (:445) /srv/share (Mode 0700) Guacamole (:8080) HTML5 RDP to RSAT VM Coop Library (:9095) & Blocky UI (:9090) Pure Go Daemons • CommonMark • Solar Theming RECOVERY & STORAGE Disaster Recovery Pipeline Restic Engine Encrypted Snapshots Monthly Offline Custody Physical External Air-Gap Drive Verified Restore Bridge Tested in Isolated LXD Bridge

Identity & Access (Samba4 AD DC)

Full Kerberos and LDAP implementation running in Samba Active Directory mode on the `COOP.INTERNAL` realm. Provides enterprise identity management and POSIX ACL mapping without external cloud brokers.

Ports: 53, 88, 389, 445, 636 Delegated `svc-lam` Account

Storage Isolation (POSIX DAC)

Individual member home directories at `/srv/share/{username}` are set to mode `0700` (`drwx------`) strictly owned by individual member UIDs. Cross-member access is rejected at the Linux kernel DAC layer.

Kernel DAC Enforcement Zero Cross-Member Leaks

Bespoke Go/HTMX Microservices

All custom services (`blocky-ui` and `coop-library`) are statically compiled pure Go binaries (`CGO_ENABLED=0`) with vendored vanilla htmx. Self-contained, crash-resilient, and running as non-root systemd daemons.

CommonMark/GFM Engine Astronomical Solar Timer

Hardened Administration Gateway

Apache Guacamole HTML5 gateway proxies browser connections into an isolated Windows RSAT VM with native clipboard forwarding and pinned TLS certificates, enabling full Active Directory GUI management from any machine.

Full RSAT Tooling Pinned TLS Fingerprints
Verification & Incident Readiness

Automated Verification & Ops Discipline

Per Rebuild Brief Rule 9, no service is "done" until it can be installed, backed up, restored, monitored with a health signal, and recovered from failure. Here is the evidence.

Automated Health Check Harness (`health-check.sh`)

Executed continuously and on every systemd boot

17 / 17 Passing
samba-ad-dc is active
smbd disabled (no port collision)
Port 53 listening (DNS)
Port 88 listening (Kerberos)
Port 389 listening (LDAP)
Port 445 listening (SMB)
Port 636 listening (LDAPS)
samba-tool dbcheck (0 errors)
Internal DNS resolves domain
External DNS forwarder active
Blocky daemon active
Ad filtering sinkhole verified
/srv disk capacity < 90%
/var/backups capacity < 90%
UFW host firewall active
coop-library service active
coop-library health API ok
coop-media service active
coop-media health API ok
Real-World Engineering Maturity

Security Postmortem: Unauthenticated Share Exposure Remediation

Date: 2026-09-19 • Severity: High (Contained in <15 minutes) • Root Cause: Linux Capability DAC Bypass

During initial staging of the Coop Library viewer, private photos from an individual member's personal share were visible over unauthenticated LAN HTTP. The engineering team executed an immediate, blameless postmortem:

1. Root Cause Identification

To allow the unprivileged daemon user to index operational runbooks, `CAP_DAC_READ_SEARCH` was granted in the systemd unit. Combined with an overbroad `SHARE_ROOT=/srv/share`, this bypassed Linux POSIX `0700` DAC permissions.

2. Rapid Containment

Immediately stripped `SHARE_ROOT` and revoked all Linux capabilities from the systemd unit. Scoped the filesystem read boundary strictly to `/opt/coop-docs`. Restarted the service within minutes.

3. Codebase Hardening

Hardcoded a security refusal in Go rejecting multi-user parent roots (`/srv/share`). Added regression tests in `main_test.go` and codified the rule in `docs/patterns.md` to prevent any unauthenticated daemon from bypassing DAC.