Skip to content

Migrate the headless-validator override to the static runtime overrides file #23

Description

@nicosampler

User story / Problem statement

Currently, headless validators (app-user / app-provider with enabled: true, ui: false) are handled by
writeGeneratedOverride in src/compose.js, which string-builds .generated/service-overrides.yaml
from JS on every run. PR #21 introduced a cleaner mechanism for the SV web UIs: a static, env-var-driven
override (templates/runtime-overrides.yaml). Having two mechanisms for the same concern (toggling
nginx-coupled UIs) is a problem because the YAML codegen is harder to review, test, and diff than a
static file.

Expected outcome

All runtime toggles flow through the same scheme: static YAML in the package + env vars written to
.generated/localnet.env. No YAML is generated from JS anywhere; .generated/ holds only env files
and the Splice checkout. Behavior is unchanged: a headless validator runs its backend with no nginx
routes, and the stack stays healthy.

Acceptance criteria

  • Headless validators are driven by templates/runtime-overrides.yaml via env vars, with behavior
    identical to today (backend reachable on direct ports, no nginx routes, nginx boots).
  • writeGeneratedOverride and .generated/service-overrides.yaml are removed, along with the
    conditional -f wiring in dockerComposeArgs.
  • Docs and comments updated: README design notes and the splice-localnet-overrides.yaml header
    (the "SECOND, GENERATED override" section disappears).
  • Tests updated (runtime-plan.test.js) and verified against a live stack with a headless and a
    UI-enabled validator.

Technical notes

Reuse Splice's own filename trick (app-user.c${APP_USER_PROFILE}f.template): statically mount the
empty file at /etc/nginx/templates/app-user.c${APP_USER_UI_NGINX}f.template. With the var set to on
(headless) the mount collides with Splice's real template and the empty file wins the merge; with off
the target renders to .cofff, which nginx ignores. Same idea for app-provider. writeLocalnetEnv
writes the two vars; the empty file it already generates can be reused as the mount source.

Benefits: one mechanism instead of two, fully declarative and reviewable YAML, less code in
compose.js, and simpler debugging (compose config shows everything; no regenerated files to chase).

Additional context

Follow-up to #4 / PR #21.

Activity

  1. added a commit that references this issue on Jul 31, 2026
    95acdda
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions