Oleks
8c119efff8
- #3 Liveness probe targets full SSR DB-querying / route, coupling pod liveness to SQLite - #4 Chart values-staging/production.yaml are dead config under Flux; drift trap - #6 tsconfig includes gitignored emdash-env.d.ts that only the dev server generates - #7 Dockerfile package-lock glob + npm install fallback can silently build an unlocked image - #8 Dockerfile creates runtime user without pinning its GID - #9 entrypoint.sh gates `emdash init` on data.db absence, skipping migrations on PVC reuse - #10 pullPolicy: Always vs digest pinning - #11 Dockerfile state symlinks contradict the STATE_DIR contract; Dockerfile does not set ENV STATE_DIR - #12 astro is a production dependency, so npm prune --omit=dev keeps build-only tooling - #14 Two ImageUpdateAutomations write back to the same anton-helm-workloads main branch - #16 memoryCache provider is per-process; correctness depends implicitly on replicas:1 - #17 Root catch-all [slug].astro couples nav links to pages-collection rows + DB hit per unmatched path - #18 Detail pages render a 200-style body under a 404 status and have no try/catch around getEmDash* calls - #19 vite allowedHosts hardcodes ddev hostnames (dev-only; no prod impact)
101 lines
4.5 KiB
Markdown
101 lines
4.5 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 — NOTE: requires app/emdash-env.d.ts, which tsconfig.json
|
|
# includes but which is gitignored + untracked. Emdash regenerates it
|
|
# ONLY via the dev-server `astro:server:setup` hook, so on a clean
|
|
# checkout you must start the dev server once (`npx emdash dev`, then
|
|
# stop it) before `astro check` will resolve emdash types. `astro build`
|
|
# (the Docker/CI image path) does NOT type-check and is unaffected.
|
|
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.
|
|
- Don't commit the dev SQLite DB. `data.db` / `data.db-shm` / `data.db-wal`
|
|
are dev artifacts (gitignored + dockerignored); they must never live in
|
|
the source tree. Regenerate via `npm run bootstrap` (`emdash init`).
|