Remove customize/build/ — fork the repo to add custom plugins
Post-#1660 the plugin declaration list is the checked-in plugins.yaml at the
repo root (the build-time source of truth). That makes customize/build/build.sh
— which clones klangk, overlays customize/build/plugins.yaml onto the clone,
then builds — redundant machinery. The simpler, more standard path is to fork
the repo and edit the checked-in plugins.yaml directly.
Why remove it
customize/build/build.sh exists to produce a custom host image with a
different plugin set than stock. Its whole job is:
- clone klangk at a pinned ref into
customize/build/.klangk/,
- copy
customize/build/plugins.yaml over the clone's declaration, and
- run
build-host-image.sh inside the clone's devenv shell.
Once plugins.yaml is checked in (#1660), steps 1 and 2 are just a roundabout
way of editing one file in a throwaway clone. A fork does the same thing
permanently and visibly:
- the operator's plugin list is a real commit in their fork (reviewable,
diffable, mergeable from upstream),
- the build is just
devenv up / build-host-image.sh in the fork — no
second scripting layer,
- there's no "clone klangk, overlay, build" indirection to document or maintain,
- fork-based customization is the model every other repo with a build-time
declaration list (package.json, Cargo.toml, go.mod) uses, so operators
already know it.
The customize/ scaffolding made sense when the plugin declaration lived in an
operator-supplied location that the build had to be pointed at. With a
checked-in declaration, the overlay is dead weight.
What's removed
The whole customize/build/ subdirectory:
customize/build/build.sh
customize/build/plugins.yaml (only exists to feed build.sh)
Stays: everything else under customize/ — custom/ (runtime
KLANGK_CUSTOMIZE_DIR content: OIDC config, certs, branding, email templates),
data/, mount/, docker-compose.yml, and the top-level customize/README.md.
Those are runtime-config concerns, not build concerns, and are unaffected.
The fork-based workflow that replaces it
# 1. Fork klangk on GitHub, clone your fork.
git clone https://github.com/<your-org>/klangk.git
cd klangk
# 2. Add your plugins under plugins/ and declare them in the checked-in
# plugins.yaml at the repo root (same format customize/build/plugins.yaml
# used — local path or git ref entries).
$EDITOR plugins.yaml
# 3. Build normally.
devenv up # dev
# or, for a shippable host image:
bash scripts/build-host-image.sh
To pull upstream klangk improvements into the custom build, git pull origin main
from the fork — the plugin declaration and plugin trees merge like any other
source file.
Migration for current customize/build/build.sh users
- Move any plugin entries from
customize/build/plugins.yaml into the
checked-in plugins.yaml in your fork (or copy the file wholesale — same
format).
- Drop plugin source trees under
plugins/<name>/ in the fork (or keep them
as git:/ref: entries pointing at their original repos).
- Set
KLANGK_VARIANT / KLANGK_HOST_IMAGE directly in the environment when
building (these were previously exported inside build.sh's devenv shell
invocation).
Docs to update
customize/README.md — drop the build/ section from the directory layout
and the "Two-File Workflow" / "Building" sections; replace with a one-line
"for custom plugins, fork the repo and edit plugins.yaml" pointer.
docs/deployment/customizing.md — same: the "custom image for plugins" path
becomes "fork and edit plugins.yaml."
Gating
Blocked-by #1660 — the rationale (checked-in plugins.yaml makes the
overlay redundant) only fully holds once #1660 lands. The fork-based workflow
is already viable today, but the clean "edit one checked-in file" story is the
post-#1660 one. Filing now so it's in the queue; do after #1660 merges.
Out of scope
Remove
customize/build/— fork the repo to add custom pluginsPost-#1660 the plugin declaration list is the checked-in
plugins.yamlat therepo root (the build-time source of truth). That makes
customize/build/build.sh— which clones klangk, overlays
customize/build/plugins.yamlonto the clone,then builds — redundant machinery. The simpler, more standard path is to fork
the repo and edit the checked-in
plugins.yamldirectly.Why remove it
customize/build/build.shexists to produce a custom host image with adifferent plugin set than stock. Its whole job is:
customize/build/.klangk/,customize/build/plugins.yamlover the clone's declaration, andbuild-host-image.shinside the clone's devenv shell.Once
plugins.yamlis checked in (#1660), steps 1 and 2 are just a roundaboutway of editing one file in a throwaway clone. A fork does the same thing
permanently and visibly:
diffable, mergeable from upstream),
devenv up/build-host-image.shin the fork — nosecond scripting layer,
declaration list (
package.json,Cargo.toml,go.mod) uses, so operatorsalready know it.
The
customize/scaffolding made sense when the plugin declaration lived in anoperator-supplied location that the build had to be pointed at. With a
checked-in declaration, the overlay is dead weight.
What's removed
The whole
customize/build/subdirectory:customize/build/build.shcustomize/build/plugins.yaml(only exists to feedbuild.sh)Stays: everything else under
customize/—custom/(runtimeKLANGK_CUSTOMIZE_DIRcontent: OIDC config, certs, branding, email templates),data/,mount/,docker-compose.yml, and the top-levelcustomize/README.md.Those are runtime-config concerns, not build concerns, and are unaffected.
The fork-based workflow that replaces it
To pull upstream klangk improvements into the custom build,
git pull origin mainfrom the fork — the plugin declaration and plugin trees merge like any other
source file.
Migration for current
customize/build/build.shuserscustomize/build/plugins.yamlinto thechecked-in
plugins.yamlin your fork (or copy the file wholesale — sameformat).
plugins/<name>/in the fork (or keep themas
git:/ref:entries pointing at their original repos).KLANGK_VARIANT/KLANGK_HOST_IMAGEdirectly in the environment whenbuilding (these were previously exported inside
build.sh'sdevenv shellinvocation).
Docs to update
customize/README.md— drop thebuild/section from the directory layoutand the "Two-File Workflow" / "Building" sections; replace with a one-line
"for custom plugins, fork the repo and edit
plugins.yaml" pointer.docs/deployment/customizing.md— same: the "custom image for plugins" pathbecomes "fork and edit
plugins.yaml."Gating
Blocked-by #1660 — the rationale (checked-in
plugins.yamlmakes theoverlay redundant) only fully holds once #1660 lands. The fork-based workflow
is already viable today, but the clean "edit one checked-in file" story is the
post-#1660 one. Filing now so it's in the queue; do after #1660 merges.
Out of scope
customize/custom/, env vars, bind mounts) —unaffected, stays as-is.
third, no-rebuild option for the stock plugin set).