Oleks
67b07634ae
- app/: Emdash scaffold (Astro 6, node target) with cmses/plugins/pages collections - app/seed/seed.json: WordPress→Emdash parity for kotkanagrilli.fi (~30 entries) - Dockerfile + docker/entrypoint.sh: multi-stage build, single PVC at /app/state - deploy/helm/: chart mirroring emdash-kotkanagrilli (single-replica, sqlite, kotkan) - deploy/fleet-overlay/: HelmRelease/source/image-automation templates for anton-helm-workloads (staging + production) - .woodpecker/container.yaml: arm64 build, three OCI tags per push (immutable 0.1.<pipeline> + floating <branch> + <branch>-latest) - .ddev/: local dev with nginx proxy to emdash on :4321 - README/DEPLOYMENT/ARCHITECTURE/CLAUDE: docs covering the three-repo pipeline (cms-plugins + anton-helm-workloads + Gitea OCI registry)
93 lines
3.9 KiB
Markdown
93 lines
3.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
Guidance for Claude Code agents working in this repository.
|
|
|
|
## What this repo is
|
|
|
|
A browseable catalog of CMS plugins built on [Emdash](https://github.com/emdash-cms/emdash).
|
|
Phase 0 — scaffold + chart + pipeline are in place, no live deploy yet.
|
|
Seeded with the WordPress → Emdash plugin parity matrix from
|
|
`~/projects/kotkanagrilli.fi/` and `~/projects/emdash.kotkanagrilli.fi/docs/parity.md`.
|
|
|
|
## Linked repos
|
|
|
|
- `~/projects/kotkanagrilli.fi/` — legacy WordPress site. **Do not edit
|
|
from here.** Source of the seeded plugin entries.
|
|
- `~/projects/emdash.kotkanagrilli.fi/` — Emdash replacement for that site.
|
|
The Dockerfile, Helm chart, Woodpecker pipeline, and DDEV setup in this
|
|
repo are deliberate copies of that one. Treat it as the reference
|
|
implementation; deviations should be justified.
|
|
- `~/projects/servers/anton/anton-helm-workloads/` — where the FluxCD
|
|
`HelmRelease`s for `cms-plugins-{staging,production}.kotkanagrilli.fi`
|
|
live. `deploy/fleet-overlay/` in this repo is the template set to copy
|
|
into that repo. **Do not commit to anton-helm-workloads without
|
|
explicit confirmation** — secrets need sops-encryption with the right
|
|
age recipients.
|
|
- `~/projects/servers/fleet/` — personal fleet repo. Owns
|
|
`emdash-kotkanagrilli-{staging,production}` but NOT cms-plugins.
|
|
|
|
## Layout
|
|
|
|
- `app/` — Emdash scaffold (node target, no i18n, no Cloudflare boundary).
|
|
Three collections in `seed/seed.json`: `cmses`, `plugins`, `pages`.
|
|
- `Dockerfile` + `docker/entrypoint.sh` — production image.
|
|
- `deploy/helm/` — the chart Flux pulls from `./deploy/helm` on the
|
|
matching branch.
|
|
- `deploy/fleet-overlay/cms-plugins-{staging,production}/` — HelmRelease
|
|
+ GitRepository + image-automation + secrets templates ready to drop
|
|
into `anton-helm-workloads`.
|
|
- `.woodpecker/container.yaml` — build pipeline (arm64; deploy target is
|
|
`kotkan`).
|
|
- `.ddev/` — local dev.
|
|
- `DEPLOYMENT.md` — full pipeline walkthrough.
|
|
- `ARCHITECTURE.md` — chart / image / Flux contracts.
|
|
|
|
## Common commands
|
|
|
|
```bash
|
|
# Local dev
|
|
ddev start # https://cms-plugins.ddev.site/
|
|
# or, without DDEV:
|
|
cd app && npm install && npm run bootstrap && npx emdash dev
|
|
|
|
# Build production image
|
|
docker build -t cms-plugins:dev .
|
|
|
|
# Typecheck
|
|
cd app && npm run typecheck
|
|
```
|
|
|
|
## Architectural constraints to respect
|
|
|
|
- **One repo, one app, node target.** No Cloudflare boundary files yet;
|
|
adding them is a deliberate Phase-N call, not casual work.
|
|
- **SQLite single-writer.** One replica, pinned to `kotkan`, `local-path`
|
|
PVC. No StatefulSet, no horizontal scale.
|
|
- **Chart pulled directly from git by Flux** — no `helm push` step. Chart
|
|
changes ship in the same commit as the code that needs them.
|
|
- **Image is pinned by digest in the HelmRelease.** `ImageUpdateAutomation`
|
|
rewrites the digest setter; `helm upgrade` only sees a change because
|
|
of that. The floating `<branch>` tag alone wouldn't roll the pod.
|
|
- **The legacy WP site keeps running.** This repo doesn't migrate
|
|
kotkanagrilli.fi — it's a catalog ABOUT plugins, not the site itself.
|
|
|
|
## Emdash gotchas (from the kotkanagrilli reference)
|
|
|
|
- All content pages must be server-rendered (`output: "server"`); no
|
|
`getStaticPaths()` for CMS content.
|
|
- `entry.id` is the slug (URLs); `entry.data.id` is the database ULID
|
|
(used for API calls / cross-collection refs).
|
|
- Image fields are `{ src, alt }` objects, not strings.
|
|
- Always `Astro.cache.set(cacheHint)` on pages that query content.
|
|
- Taxonomy names in queries match `seed.json`'s `name` field exactly.
|
|
|
|
## What NOT to do
|
|
|
|
- Don't `npm install` random kotkanagrilli plugins (the e-commerce ones).
|
|
This is a catalog, not a store.
|
|
- Don't push to `anton-helm-workloads` without explicit confirmation —
|
|
unencrypted secrets would leak.
|
|
- Don't change branch promotion semantics (fast-forward only across
|
|
`develop` → `staging` → `production`). Mirroring emdash-kotkanagrilli's
|
|
flow is intentional.
|