diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index df7118e..d90af06 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -109,8 +109,8 @@ jobs:
build-docs:
name: Build docs site
runs-on: ubuntu-latest
- # GATED: docs-site/ directory does not exist yet. Uncomment + create docs-site/ before re-enabling.
- if: false
+ permissions:
+ contents: write
steps:
- uses: actions/checkout@v4
- name: Build static site
@@ -118,7 +118,10 @@ jobs:
run: |
npm ci
npm run build
+ # Build runs on every push/PR (validates the site). Deploy to gh-pages
+ # only on push to the default branch — PRs build but don't publish.
- uses: peaceiris/actions-gh-pages@v4
+ if: github.ref == 'refs/heads/main' && github.event_name == 'push'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: docs-site/out
diff --git a/README.md b/README.md
index 716a495..460b276 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# Stackup
-**Kubernetes on your laptop. ArgoCD + Argo Rollouts + Prometheus + Loki + Tempo + Grafana. `make up` in 10 minutes. Free.**
+**Kubernetes on your laptop. ArgoCD + Argo Rollouts + Prometheus + Grafana. `make up` in 10 minutes. Free.**
[](https://github.com/ykstorm/stackup/actions/workflows/ci.yml)
[](LICENSE)
@@ -29,11 +29,16 @@ The buyerchat workload deliberately runs degraded (no DB). That's intentional. T
| **TLS** | cert-manager | Self-signed ClusterIssuer (swap to ACME in one line for prod) |
| **Secrets** | Sealed Secrets | Encrypted secrets in git, decrypted in-cluster |
| **Metrics** | kube-prometheus-stack | Prometheus + Alertmanager + Grafana, RED dashboards pre-imported |
-| **Logs** | Loki + Promtail | Pod stdout → Loki → Grafana Explore |
-| **Traces** | Tempo (monolithic) | OTLP traces from workloads |
| **Workload demo** | buyerchat Helm chart | Next.js app — demonstrates the cluster, not a production app |
| **Hardening** | PSS `restricted` + NetworkPolicy `default-deny` | Zero-trust on workload namespaces |
+### Roadmap (not installed yet)
+
+| Layer | Component | What it would do |
+|---|---|---|
+| **Logs** | Loki + Promtail | Pod stdout → Loki → Grafana Explore |
+| **Traces** | Tempo | OTLP traces from workloads |
+
---
## 10-minute quickstart
@@ -55,7 +60,7 @@ Add to `/etc/hosts` (Windows: `C:\Windows\System32\drivers\etc\hosts`):
Then open:
- **[https://buyerchat.local.stackup.dev](https://buyerchat.local.stackup.dev)** — workload, returns 503 degraded (no DB — expected)
-- **[https://grafana.local.stackup.dev](https://grafana.local.stackup.dev)** — RED metrics + Loki logs + Tempo traces
+- **[https://grafana.local.stackup.dev](https://grafana.local.stackup.dev)** — RED metrics from Prometheus (logs/traces are roadmap)
- **[https://argocd.local.stackup.dev](https://argocd.local.stackup.dev)** — GitOps tree of 6 child apps
---
@@ -88,15 +93,13 @@ graph TD
Apps --> Rollout[Argo Rollouts CRD]
Rollout --> Pods[Canary pods]
Pods --> Prom[Prometheus]
- Pods --> LokiL[Loki]
- Pods --> TempoT[Tempo]
Prom --> Graf[Grafana]
- LokiL --> Graf
- TempoT --> Graf
```
For full topology + sequence diagrams, see [docs/architecture.md](docs/architecture.md).
+A static documentation site (overview, getting started, architecture, GitOps + canary) is built from `docs-site/` and published to GitHub Pages on merge to `main`.
+
---
## Makefile targets
diff --git a/docs-site/.gitignore b/docs-site/.gitignore
new file mode 100644
index 0000000..6bc3a19
--- /dev/null
+++ b/docs-site/.gitignore
@@ -0,0 +1,5 @@
+/node_modules
+/.next
+/out
+*.tsbuildinfo
+.DS_Store
diff --git a/docs-site/app/architecture/page.js b/docs-site/app/architecture/page.js
new file mode 100644
index 0000000..451976f
--- /dev/null
+++ b/docs-site/app/architecture/page.js
@@ -0,0 +1,122 @@
+export const metadata = {
+ title: 'Architecture — Stackup',
+};
+
+export default function Architecture() {
+ return (
+ <>
+ Architecture
+
+ Cluster topology, the GitOps tree, the observability flow, and the
+ security posture — all of it reproducible from make up.
+
+
+ Cluster topology
+
+ kind launches the cluster as Docker containers, each node running
+ containerd and kubelet. Pods run inside the worker nodes as
+ containers-within-containers. The cluster declares{' '}
+ disableDefaultCNI: true and installs Calico, which enforces
+ ingress and egress NetworkPolicy rules in full. The whole thing fits in
+ roughly 3 GB of RAM.
+
+
+ GitOps tree (app-of-apps)
+
+ A single root ArgoCD Application is the only thing make up{' '}
+ applies. It manages six child applications, and ArgoCD syncs each of
+ them from the git repo:
+
+
+ cert-manager — TLS issuance
+ ingress-nginx — ingress and TLS termination
+ sealed-secrets — in-cluster secret decryption
+ kube-prometheus-stack — Prometheus, Alertmanager, Grafana
+ argo-rollouts — the canary controller
+ buyerchat — the demo workload
+
+
+ The discipline is that state lives in git, not in ad-hoc{' '}
+ kubectl apply commands. ArgoCD runs automated sync, prune,
+ and self-heal against what the repo declares.
+
+
+ Observability flow
+
+ kube-prometheus-stack installs Prometheus, Alertmanager, and Grafana.
+ Metrics flow into Prometheus and render as RED dashboards in Grafana:
+
+
+
+
+ Signal
+ Path
+ Store
+
+
+
+
+ Metrics
+ /api/metrics scraped every 30s
+ Prometheus
+
+
+
+
+ Roadmap
+
+ Logs and traces (Loki + Promtail, Tempo) are on the roadmap — not
+ installed yet. Once they are wired in, a Grafana panel would let you
+ drill from a metric into the matching logs, and from a log line jump to
+ the trace by its trace_id.
+
+
+ Security posture
+
+
+
+ Layer
+ Control
+
+
+
+
+ Pod admission
+
+ Pod Security Standards restricted on workload
+ namespaces
+
+
+
+ Network
+
+ NetworkPolicy default-deny, explicit allow rules per
+ service
+
+
+
+ Secrets
+ Sealed Secrets — encrypted in git, decrypted in-cluster
+
+
+ TLS
+ cert-manager self-signed CA (swap to ACME for production)
+
+
+ RBAC
+ No cluster-admin bindings on workload namespaces
+
+
+
+
+ What changes for production
+
+ Taking the stack to EKS, GKE, or AKS means swapping kind for a managed
+ control plane, the self-signed issuer for ACME via DNS-01, hostPort
+ ingress for a real LoadBalancer, local volumes for a CSI driver,
+ single-replica components for HA, and loosening nothing on the RBAC
+ side.
+
+
+ );
+}
diff --git a/docs-site/app/getting-started/page.js b/docs-site/app/getting-started/page.js
new file mode 100644
index 0000000..fe22288
--- /dev/null
+++ b/docs-site/app/getting-started/page.js
@@ -0,0 +1,88 @@
+export const metadata = {
+ title: 'Getting Started — Stackup',
+};
+
+export default function GettingStarted() {
+ return (
+ <>
+ Getting Started
+
+ Clone the repo, run one command, and reach a working cluster in about
+ ten minutes. You need Docker and kubectl on the machine.
+
+
+ Bring it up
+
+ {`git clone https://github.com/ykstorm/stackup && cd stackup
+make up`}
+
+
+ make up creates the kind cluster, installs the platform,
+ and deploys the buyerchat workload. The root ArgoCD Application is the
+ only thing applied directly; ArgoCD syncs everything else from the git
+ repo.
+
+
+ Map the hostnames
+
+ Add these entries to your hosts file (/etc/hosts, or{' '}
+ C:\Windows\System32\drivers\etc\hosts on Windows):
+
+
+ {`127.0.0.1 buyerchat.local.stackup.dev
+127.0.0.1 grafana.local.stackup.dev
+127.0.0.1 argocd.local.stackup.dev
+127.0.0.1 prometheus.local.stackup.dev`}
+
+
+ Open the surfaces
+
+
+ buyerchat.local.stackup.dev — the workload. It
+ returns 503 degraded because there is no database wired in. That
+ response is expected.
+
+
+ grafana.local.stackup.dev — RED metrics from
+ Prometheus. Logs and traces (Loki, Tempo) are on the roadmap, not
+ installed yet.
+
+
+ argocd.local.stackup.dev — the GitOps tree of six
+ child apps.
+
+
+
+ Makefile targets
+
+ {`make help # Show all targets
+make up # Create cluster + install platform + buyerchat
+make down # Tear down the kind cluster
+make smoke # Run smoke tests (requires cluster up)
+make lint # Lint all YAML + Helm charts
+make rollout-status # Watch the buyerchat canary progress`}
+
+
+ Known limits
+
+
+ No real LoadBalancer service type — kind does not ship one, so the
+ stack uses hostPort. Deploy to a cloud cluster for a real load
+ balancer.
+
+
+ Storage is local-path PVs by default. Re-creating the cluster wipes
+ them. Add Longhorn or OpenEBS for persistence across teardowns.
+
+
+ Single-tenant workload namespace. Multi-tenant needs more
+ NetworkPolicy and RBAC work.
+
+
+ The buyerchat workload runs degraded with no database, on purpose. The
+ cluster is the demo, not the app.
+
+
+
+ );
+}
diff --git a/docs-site/app/gitops-canary/page.js b/docs-site/app/gitops-canary/page.js
new file mode 100644
index 0000000..005774d
--- /dev/null
+++ b/docs-site/app/gitops-canary/page.js
@@ -0,0 +1,62 @@
+export const metadata = {
+ title: 'GitOps & Canary — Stackup',
+};
+
+export default function GitopsCanary() {
+ return (
+ <>
+ GitOps & Canary
+
+ How a single commit turns into a canary rollout gated on Prometheus,
+ with automatic rollback when the analysis fails.
+
+
+ The trigger
+
+ Push a commit that bumps helm/buyerchat/values.yaml{' '}
+ image.tag. ArgoCD notices the change and syncs. Argo
+ Rollouts applies the new Rollout revision. Watch it advance:
+
+
+ {`make rollout-status
+# same as: kubectl argo rollouts get rollout buyerchat -n app --watch`}
+
+
+ The canary steps
+
+ Argo Rollouts shifts 25% of traffic to the new version and pauses, then
+ runs an analysis step. An AnalysisTemplate queries
+ Prometheus three times over 90 seconds. If the success condition holds,
+ the rollout advances to 50%, then 75%, then 100%. If the analysis fails,
+ Argo Rollouts aborts and rolls back to the previous revision. This is the
+ canary pattern teams run in production, reproduced on a laptop.
+
+
+
+ Scale the canary to 25% of traffic and pause.
+ Run the Prometheus analysis query three times over 90 seconds.
+ If the gate passes, advance to 50%, then 75%, then 100%.
+ If the gate fails, abort and revert to the previous revision.
+
+
+ The analysis query
+
+ The current analysis query is a conservative liveness check: is the
+ canary up and being scraped. Once the buyerchat image exports request
+ counters on /api/metrics, swap it for a real success-rate
+ ratio. The template carries a TODO marking the one line to
+ change.
+
+
+ Why GitOps for this
+
+ Because the image tag lives in git and ArgoCD reconciles against it, the
+ rollout has a single source of truth. There is no out-of-band{' '}
+ kubectl set image. A reviewer can read the diff that
+ triggered a deploy, and a revert is a git revert. The canary gate then
+ decides whether that change reaches all traffic, with Prometheus as the
+ judge.
+
+
+ );
+}
diff --git a/docs-site/app/globals.css b/docs-site/app/globals.css
new file mode 100644
index 0000000..7e184a4
--- /dev/null
+++ b/docs-site/app/globals.css
@@ -0,0 +1,198 @@
+:root {
+ --bg: #0d1117;
+ --panel: #161b22;
+ --border: #30363d;
+ --text: #e6edf3;
+ --muted: #9da7b3;
+ --accent: #2f81f7;
+ --accent-soft: #1f6feb33;
+ --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+}
+
+* {
+ box-sizing: border-box;
+}
+
+html,
+body {
+ margin: 0;
+ padding: 0;
+ background: var(--bg);
+ color: var(--text);
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+ line-height: 1.6;
+}
+
+a {
+ color: var(--accent);
+ text-decoration: none;
+}
+
+a:hover {
+ text-decoration: underline;
+}
+
+.site-header {
+ border-bottom: 1px solid var(--border);
+ background: var(--panel);
+}
+
+.site-header .inner {
+ max-width: 880px;
+ margin: 0 auto;
+ padding: 14px 24px;
+ display: flex;
+ align-items: center;
+ gap: 24px;
+ flex-wrap: wrap;
+}
+
+.brand {
+ font-weight: 700;
+ font-size: 18px;
+ color: var(--text);
+}
+
+.brand:hover {
+ text-decoration: none;
+}
+
+.nav {
+ display: flex;
+ gap: 18px;
+ font-size: 14px;
+}
+
+.nav a {
+ color: var(--muted);
+}
+
+.nav a:hover {
+ color: var(--text);
+ text-decoration: none;
+}
+
+main {
+ max-width: 880px;
+ margin: 0 auto;
+ padding: 40px 24px 80px;
+}
+
+h1 {
+ font-size: 30px;
+ line-height: 1.2;
+ margin: 0 0 8px;
+}
+
+h2 {
+ font-size: 21px;
+ margin: 36px 0 12px;
+ padding-top: 8px;
+ border-top: 1px solid var(--border);
+}
+
+h3 {
+ font-size: 17px;
+ margin: 24px 0 8px;
+}
+
+.lede {
+ font-size: 17px;
+ color: var(--muted);
+ margin: 0 0 24px;
+}
+
+code {
+ font-family: var(--mono);
+ font-size: 0.9em;
+ background: var(--panel);
+ border: 1px solid var(--border);
+ border-radius: 4px;
+ padding: 1px 5px;
+}
+
+pre {
+ background: var(--panel);
+ border: 1px solid var(--border);
+ border-radius: 8px;
+ padding: 14px 16px;
+ overflow-x: auto;
+}
+
+pre code {
+ background: none;
+ border: none;
+ padding: 0;
+}
+
+table {
+ width: 100%;
+ border-collapse: collapse;
+ margin: 16px 0;
+ font-size: 14px;
+}
+
+th,
+td {
+ border: 1px solid var(--border);
+ padding: 8px 12px;
+ text-align: left;
+ vertical-align: top;
+}
+
+th {
+ background: var(--panel);
+}
+
+ul,
+ol {
+ padding-left: 22px;
+}
+
+li {
+ margin: 4px 0;
+}
+
+.cards {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+ gap: 16px;
+ margin: 24px 0;
+}
+
+.card {
+ border: 1px solid var(--border);
+ border-radius: 8px;
+ padding: 18px;
+ background: var(--panel);
+}
+
+.card h3 {
+ margin-top: 0;
+}
+
+.card p {
+ color: var(--muted);
+ font-size: 14px;
+ margin: 8px 0 0;
+}
+
+.tag {
+ display: inline-block;
+ font-size: 12px;
+ font-family: var(--mono);
+ background: var(--accent-soft);
+ color: var(--accent);
+ border-radius: 4px;
+ padding: 2px 8px;
+ margin-bottom: 16px;
+}
+
+footer {
+ border-top: 1px solid var(--border);
+ color: var(--muted);
+ font-size: 13px;
+ max-width: 880px;
+ margin: 0 auto;
+ padding: 24px;
+}
diff --git a/docs-site/app/layout.js b/docs-site/app/layout.js
new file mode 100644
index 0000000..e959549
--- /dev/null
+++ b/docs-site/app/layout.js
@@ -0,0 +1,41 @@
+import './globals.css';
+
+export const metadata = {
+ title: 'Stackup Docs',
+ description:
+ 'Production-shaped Kubernetes on a laptop: ArgoCD app-of-apps, Argo Rollouts canary, kube-prometheus-stack, all from make up.',
+};
+
+function Header() {
+ return (
+
+ );
+}
+
+export default function RootLayout({ children }) {
+ return (
+
+
+
+ {children}
+
+ Stackup — Apache License 2.0. Built with Next.js static export.{' '}
+ Source on GitHub .
+
+
+
+ );
+}
diff --git a/docs-site/app/page.js b/docs-site/app/page.js
new file mode 100644
index 0000000..e7ff567
--- /dev/null
+++ b/docs-site/app/page.js
@@ -0,0 +1,114 @@
+export default function Home() {
+ return (
+ <>
+ kind · ArgoCD · Argo Rollouts · Prometheus
+ Stackup
+
+ A production-shaped Kubernetes stack that runs on your laptop. One{' '}
+ make up brings up a kind cluster with GitOps, canary
+ delivery, and full observability — for free.
+
+
+
+ Managed Kubernetes starts around $200/month on cloud providers. Stackup
+ runs the same control-plane patterns on kind, in Docker, on a single
+ machine. The buyerchat workload deliberately runs degraded with no
+ database. That is intentional: the cluster is the demo, not the app.
+
+
+ What it is
+
+ A kind-based cluster wired with a real ArgoCD app-of-apps over six child
+ applications, Argo Rollouts canary progressive delivery, the
+ kube-prometheus-stack for metrics (Prometheus, Alertmanager, Grafana),
+ cert-manager TLS, Sealed Secrets encrypted in git, and Calico
+ NetworkPolicy enforcement. Pod Security Standards restricted{' '}
+ applies on every workload namespace.
+
+
+ The components
+
+
+
+ Layer
+ Component
+ Role
+
+
+
+
+ Cluster
+ kind on Docker
+ Kubernetes nodes running in containers
+
+
+ CNI
+ Calico
+ NetworkPolicy enforcement (ingress + egress)
+
+
+ GitOps
+ ArgoCD app-of-apps
+ One root app manages six children; sync, prune, self-heal
+
+
+ Progressive delivery
+ Argo Rollouts
+ Canary 25 to 100% with an analysis gate and auto-rollback
+
+
+ Ingress
+ ingress-nginx
+ TLS termination over hostPort 80/443
+
+
+ TLS
+ cert-manager
+ Self-signed ClusterIssuer, swap to ACME for production
+
+
+ Secrets
+ Sealed Secrets
+ Encrypted in git, decrypted in-cluster
+
+
+ Metrics
+ kube-prometheus-stack
+ Prometheus, Alertmanager, Grafana with RED dashboards
+
+
+ Workload
+ buyerchat Helm chart
+ Next.js demo app that exercises the cluster
+
+
+
+
+ On the roadmap, not installed yet: logs (Loki + Promtail) and traces
+ (Tempo) for the full three-signal view in Grafana.
+
+
+ Start here
+
+
+
+
Clone, run make up, and reach the cluster in about ten minutes.
+
+
+
+
Cluster topology, the GitOps tree, and the observability flow.
+
+
+
+
How a commit becomes a canary rollout with a Prometheus gate.
+
+