cms-plugins/ARCHITECTURE.md

Architecture

This file is the contract between the build (Dockerfile, Woodpecker, Helm chart) and the FluxCD reconciliation in anton-helm-workloads. See DEPLOYMENT.md for the operational walkthrough.

Repo shape

cms-plugins/
├── app/                              ← Emdash/Astro source
│   ├── astro.config.mjs              ← node target, sqlite() + local()
│   ├── package.json
│   ├── src/                          ← pages, layouts, components
│   └── seed/seed.json                ← collections + kotkanagrilli plugin entries
├── Dockerfile                        ← multi-stage build, single PVC at /app/state
├── docker/entrypoint.sh              ← runs `emdash init` on first boot
├── deploy/
│   ├── helm/                         ← chart consumed by Flux directly from this repo
│   └── fleet-overlay/                ← HelmRelease/source/image-automation templates
│       ├── cms-plugins-staging/      ← copy → anton-helm-workloads/cms-plugins-staging/
│       └── cms-plugins-production/   ← copy → anton-helm-workloads/cms-plugins-production/
├── .woodpecker/container.yaml        ← build pipeline
└── .ddev/                            ← local dev (DDEV nginx → emdash service on :4321)

Build pipeline

A push to develop / staging / production runs .woodpecker/container.yaml. The pipeline labels itself arch: arm64 because the deploy target (kotkan) is an arm64 node, so building natively avoids a cross-compile step.

For each build the pipeline pushes three OCI tags to git.oleks.space/oleks/cms-plugins:

Tag	Mutability	Purpose
0.1.<pipeline>	Immutable	Audit trail. Use as a rollback target.
<branch>	Floating	Watched by FluxCD's ImagePolicy. Retagged on every build.
<branch>-latest	Floating	Cosmetic. Resolves the chart's image.tag fallback to a real ref when the digest path is unset.

Only the staging and production branches have an ImagePolicy, so only those move pods.

Container shape

Multi-stage Dockerfile:

• deps — node:22-bookworm-slim + python3 make g++ (better-sqlite3 build deps). Falls back to npm install if there's no committed lockfile.
• build — npm run build.
• runtime — node:22-bookworm-slim + tini. Runs as uid 1001. Persistent state symlinked from /app/data.db and /app/uploads → /app/state/... so the one PVC mounted at /app/state covers both SQLite and uploaded media.

Entrypoint runs emdash init on first boot (idempotent), then execs the Astro node server on port 4321.

Helm chart

deploy/helm/ ships with the app. The chart is not packaged or pushed to an OCI registry — FluxCD's GitRepository source pulls it directly from the matching branch of this repo. The ignore rule in source.yaml restricts reconciliation to /deploy/helm, so app-source pushes don't trigger chart re-reconcile.

Per-env values come from two independent sources that must be kept in sync by hand:

• The inline values: block in each FluxCD HelmRelease (in anton-helm-workloads, templated under deploy/fleet-overlay/). This is the only source Flux applies to the cluster.
• values-staging.yaml / values-production.yaml in deploy/helm/, used only for direct helm upgrade -f ... invocations. Flux never reads these files, so editing them has no effect on the live deploy and they can silently drift from the HelmRelease.

Key shape decisions:

• replicas: 1, strategy: Recreate. SQLite is single-writer. This also keeps the in-process Astro response cache (memoryCache() in app/astro.config.mjs, fed by Astro.cache.set(cacheHint) on the content pages) coherent: it is per-process, so a second replica would hold a divergent, independently-expiring cache. Scaling out would require a shared cache provider, not just relaxing the SQLite writer constraint.
• nodeSelector: kotkan. local-path PV is sticky to one node; emdash is colocated with the legacy kotkanagrilli WP install.
• Pinned by digest, not tag. The HelmRelease sets values.image.digest: "<sha256:...>" # {"$imagepolicy": ...} so that helm upgrade detects a change when the floating tag is reassigned. Without digest pinning, staging stays the literal string "staging" through every build and Helm sees no spec change.
• Single PVC, helm.sh/resource-policy: keep. Losing the PVC means losing all CMS data — uninstalls do not delete it.

Flux contract

Two repos cooperate:

• cms-plugins (this one) exposes the chart at deploy/helm/ on each branch.
• anton-helm-workloads runs the show: GitRepository points at the matching branch of cms-plugins, HelmRelease references chart: ./deploy/helm, ImagePolicy + ImageUpdateAutomation watch the floating tag and rewrite the digest setter back into helmrelease.yaml.

For the workloads repo to write digest commits, a GitRepository named anton-workloads-image-automation in flux-system namespace must exist with write access to anton-helm-workloads:main. The emdash-kotkanagrilli analogue is oleks-fleet-image-automation in the personal fleet repo.

Data model

Three Emdash collections (app/seed/seed.json):

• cmses — CMS platforms. Seeded with WordPress + Emdash.
• plugins — one entry per plugin. Fields: title, purpose, source_cms, target_cms, category, status (port/built-in/saas/drop/gated/done/proposed), source_repo_url, target_repo_url, notes (portableText).
• pages — static content (About, Submit, etc.).

The seeded plugin entries come from ~/projects/emdash.kotkanagrilli.fi/docs/parity.md and the mu-plugins/ / plugins-custom/ directories in ~/projects/kotkanagrilli.fi/. New entries are added through the Emdash admin (/_emdash/admin).

What this does NOT solve

• Cloudflare Workers target. The kotkanagrilli sister project has Cloudflare boundary files (src/worker.ts, wrangler.jsonc) for a later flip; this repo skips them. They can be added back from the emdash-kotkanagrilli pattern when needed.
• Authentication on the admin. Emdash's default passkey auth runs; the first visit to /_emdash/admin redirects to /setup and creates the first admin.
• Multi-language. No i18n — the catalog is English-only by default.