Skip to content

Remove customize/build/ — fork the repo to add custom plugins #1663

Description

@mcdonc

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:

  1. clone klangk at a pinned ref into customize/build/.klangk/,
  2. copy customize/build/plugins.yaml over the clone's declaration, and
  3. 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

  1. 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).
  2. Drop plugin source trees under plugins/<name>/ in the fork (or keep them
    as git:/ref: entries pointing at their original repos).
  3. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions