INIT
- Responsibility
- Provisions hosts and converges the platform foundation.
- Stack
- OpenTofu · Proxmox · cloud-init · Ansible · K3s · Cilium · Longhorn
Systems, Hosting, Engineering, Linux & Lifecycle
SHELL
A modular platform for the infrastructure lifecycle
- IaC
- FreeIPA
- Kubernetes
- Argo CD
- Prometheus
In progress, actively built
Seven components with distinct ownership, checks, and explicit handoffs.
What the project does
SHELL treats infrastructure as one connected lifecycle rather than a collection of tools: build the foundation, control access and artifacts, deliver workloads, observe operations, and make system knowledge accessible.
INIT provides systems and runtime. SUDO and TAR define the identities and artifacts MAKE may use. MAKE manages declared workload state, WATCH verifies operations and recovery, MAN publishes architecture and evidence, and GREP retrieves knowledge from the approved corpus.
Architecture
The architecture separates foundation, platform, operations, and knowledge. Its key relationships are explicit handoffs: the technical base and controlled inputs feed delivery; runtime results are observed, documented, and then approved for retrieval.
SUDO
- Responsibility
- Defines identities, access, policy, and trust boundaries.
- Stack
- FreeIPA · OpenBao · Keycloak · SOPS/age · cert-manager · Kyverno
TAR
- Responsibility
- Moves, retains, and recovers controlled deployment artifacts.
- Stack
- Harbor · MinIO / S3 · ORAS · Skopeo · Velero · Crane
MAKE
- Responsibility
- Builds, packages, promotes, deploys, and rolls back workloads.
- Stack
- Forgejo · Argo Workflows · Argo CD · Buildah · Helm · Kustomize · Cosign
WATCH
- Responsibility
- Observes services and exercises bounded failure and recovery paths.
- Stack
- Prometheus · Alertmanager · Grafana · Loki · OpenTelemetry · k6
MAN
- Responsibility
- Publishes architecture, contracts, decisions, and bounded evidence.
- Stack
- Astro · Starlight · Mermaid · JSON Schema · Playwright · Pagefind
GREP
- Responsibility
- Retrieves cited knowledge only from the approved documentation corpus.
- Stack
- FastAPI · SQLite FTS5 · Qdrant · LlamaIndex · Ollama
| Subproject | Responsibility | Stack |
|---|---|---|
| INIT | Provisions hosts and converges the platform foundation. | OpenTofu · Proxmox · cloud-init · Ansible · K3s · Cilium · Longhorn |
| SUDO | Defines identities, access, policy, and trust boundaries. | FreeIPA · OpenBao · Keycloak · SOPS/age · cert-manager · Kyverno |
| TAR | Moves, retains, and recovers controlled deployment artifacts. | Harbor · MinIO / S3 · ORAS · Skopeo · Velero · Crane |
| MAKE | Builds, packages, promotes, deploys, and rolls back workloads. | Forgejo · Argo Workflows · Argo CD · Buildah · Helm · Kustomize · Cosign |
| WATCH | Observes services and exercises bounded failure and recovery paths. | Prometheus · Alertmanager · Grafana · Loki · OpenTelemetry · k6 |
| MAN | Publishes architecture, contracts, decisions, and bounded evidence. | Astro · Starlight · Mermaid · JSON Schema · Playwright · Pagefind |
| GREP | Retrieves cited knowledge only from the approved documentation corpus. | FastAPI · SQLite FTS5 · Qdrant · LlamaIndex · Ollama |
Documentation / system overview
SHELL Manual
The manual is the project’s documentation source. It connects the system overview, architecture decisions, operator playbooks, and bounded evidence so reviewers can follow a claim to its owner, check, and supporting evidence.
Use Cases
Provision hosts reproducibly
INIT provisions hosts with OpenTofu and Proxmox, converges system state with cloud-init and Ansible, and provides K3s, Cilium, and Longhorn as the platform foundation.
The path stays declarative and reproducible; rebuild becomes an architecture test rather than only a disaster procedure.
Deliver workloads through GitOps
MAKE builds, packages, and promotes workloads. Argo CD reconciles declared target state while TAR supplies the required artifacts through a controlled path.
Commit, artifact, and runtime state remain separate responsibilities with traceable handoffs.
Manage trust and artifacts centrally
SUDO uses FreeIPA, OpenBao, Keycloak, cert-manager, and Kyverno to define the identities, secrets, and policies accepted by the platform.
Trust remains an explicit input to delivery instead of hidden application configuration.
Observe operations and recover
WATCH connects Prometheus, Alertmanager, Grafana, Loki, OpenTelemetry, and k6 to bounded failure and recovery workflows.
Recovery is treated through observable state and verifiable procedures rather than documentation alone.
Current state
SHELL is in progress. The seven responsibility areas, their interfaces, and their reviewer paths are defined; implementation, checks, and evidence continue to evolve per component.
A documented tool or declared target state is not automatically deployment, recovery, or production evidence. Repository-owned checks and linked, dated evidence remain authoritative.