Case study · platform engineering

Docs as a control plane, Terraform against Proxmox

Three repositories that only work as one: architecture governance, infrastructure reconciled from code, and a delivery pattern applications can be built on without reinventing the deployment every time.

Role: Platform architect, infrastructure builder, delivery workflow designer
Status: Active foundation work
Stack: GitHub Actions, Terraform, Proxmox, cloud-init, Docker Compose, Infisical, Django, Vite
Source: Private repositories, public-safe summary

The problem in one sentence. Documentation, infrastructure, CI and deployment were four separate habits maintained by four separate conventions, so every new environment was a negotiation and every handoff lost something.

What I built

A documentation-as-code structure: architecture decision records, runbooks, checklists, user stories and public-safe project summaries, versioned alongside the things they describe.
GitHub Actions validation that enforces documentation presence, secret hygiene and reusable workflow structure before anything downstream depends on it.
A Terraform workspace for Proxmox cluster configuration, cloud image handling, guest inventory collection and safe import planning.
A parameterized guest definition for a Docker host with cloud-init, observability hooks and environment-specific local inputs.
A Django and Groundwork application scaffold with dev containers, TypeScript and Vite assets, and CI-backed lint and test execution.
A reusable deployment pattern joining GitHub Actions, Infisical, SSH orchestration, Docker Compose rollout and health validation.

How it is built

Docs as control plane

Architecture rules, safety boundaries and runbooks are versioned and validated in GitHub before automation is allowed to depend on them.

Infrastructure reconciliation

Terraform is used to inventory and model the Proxmox guests that already exist, not only to create new ones. Import planning comes before apply.

A delivery baseline

Django, Groundwork, PostGIS, TypeScript and containerized CI, so application work starts from a structured base rather than a blank directory.

Deployment standardization

Reusable Actions and Compose patterns replace one-off deployment logic, and make secret handling and health checks explicit rather than assumed.

Evidence

Public-safe diagrams. Open any panel for full size.

Diagram of the documentation repository governance model — Documentation governance. Architecture principles, decision records, reusable deployment templates, and checks that block obvious secrets and structural regressions.

Diagram of the Terraform workspace targeting Proxmox — Terraform Proxmox workspace. Cluster inputs, cloud image handling, VM initialization, and guest inventory taken before state import or rollout.

Diagram of the web application delivery stack — Web application delivery. Django, Groundwork, Vite, Jest, dev containers and pull-request CI as one repeatable engineering base.

Diagram of the reusable Docker Compose deployment pattern — Reusable deployment. GitHub Actions, Infisical, SSH coordination, rsync, Compose rollout and health checks templated into one release flow.

Why it matters

The value is not in any single repository. It is in the consistency across planning, provisioning, validation, deployment and handoff — the part that decides whether a second engineer can pick the work up without a meeting.

Standing up systems is the easy half. Defining a standard, codifying it, and turning it into a workflow a team will actually keep using is the half that determines whether the platform survives the person who built it.

Talk about your platform Back to all work