Skip to content

docs: document conductor.enable.ui.serving for headless deployments#1086

Open
bishnubista wants to merge 3 commits into
conductor-oss:mainfrom
bishnubista:docs/document-enable-ui-serving
Open

docs: document conductor.enable.ui.serving for headless deployments#1086
bishnubista wants to merge 3 commits into
conductor-oss:mainfrom
bishnubista:docs/document-enable-ui-serving

Conversation

@bishnubista

Copy link
Copy Markdown

Summary

Closes #1074. Documents conductor.enable.ui.serving, the property that controls Conductor's bundled UI serving. Until now, operators wanting to run a headless (API-only) Conductor server had to discover the flag by reading SpaInterceptor.java.

The property toggles two Spring MVC registrations as a pair, both gated on the optional SpaInterceptor bean in RestConfiguration:

  1. The HandlerInterceptor that forwards unmatched paths to index.html so the SPA's client-side router can handle them.
  2. The resource handler that serves the UI bundle at /static/ui/**.

What changed

  • docs/documentation/configuration/appconf.md — new "UI Serving" section with the property reference table, the authoritative path-exclude list, and an example usage block. Cross-linked to the deploy guide.
  • docs/devguide/running/deploy.md — new "Headless (API-only) deployment" subsection under Production configuration, including a note that a small placeholder index.html shipped inside the server JAR is still served at / by Spring Boot's default static-resource handling (so the behavior is not a strict 404 at the root).
  • docker/server/config/config.properties — commented example of conductor.enable.ui.serving=false near the top of the default Docker config.

How I verified

Every behavioral claim was checked against source:

  • Property name and default: rest/src/main/java/org/conductoross/conductor/SpaInterceptor.java lines 25-28 (matchIfMissing = true).
  • The two gated registrations: rest/src/main/java/org/conductoross/conductor/RestConfiguration.java
    • Lines 36, 51-66 — SpaInterceptor registration via addInterceptors() is skipped when the bean is absent.
    • Lines 70-76 — /static/ui/** resource handler in addResourceHandlers() is also skipped.
  • Authoritative path exclude list: RestConfiguration.java:54-64 (excludePathPatterns(...) at the registration site). The doc lists exactly these patterns, not the belt-and-suspenders checks inside SpaInterceptor.preHandle().
  • Existing explicit default: server-lite/src/main/resources/application.properties:11.
  • Placeholder at /: rest/src/main/resources/static/index.html — confirmed it is a short page (logo + links to Swagger UI and the documentation), served by Spring Boot's default static-resource handling regardless of the flag.

Verified independently that no other class reads this property (grep for enable.ui.serving and enableUiServing — only SpaInterceptor.java and the server-lite default were hit).

Per the project's documentation policy in CLAUDE.md, no behavior is described that isn't traceable to one of these source files.

Test plan

  • mkdocs serve renders the new sections without warnings
  • Cross-links resolve in both directions:
    • appconf.mddeploy.md#headless-api-only-deployment
    • deploy.mdappconf.md#ui-serving
  • Tables render correctly on the docs site
  • docker/server/config/config.properties still loads (it's a comment-only change, but worth running docker compose up to confirm)

Closes conductor-oss#1074

Adds reference documentation for conductor.enable.ui.serving, the
property that disables Conductor's bundled UI serving so the server
can run alongside a separately hosted UI (CDN, Nginx, or another
container).

Until now operators had to discover the flag by reading
SpaInterceptor.java. The property toggles two Spring MVC
registrations as a pair, both gated on the optional SpaInterceptor
bean in RestConfiguration:

  - the HandlerInterceptor that forwards unmatched paths to
    index.html for the SPA's client-side router
  - the resource handler that serves the UI bundle at /static/ui/**

Files changed:
  - docs/documentation/configuration/appconf.md
      New "UI Serving" section with the property reference, the
      authoritative path-exclude list from
      RestConfiguration.addInterceptors(), and an example usage block.
  - docs/devguide/running/deploy.md
      New "Headless (API-only) deployment" subsection under
      Production configuration, including a note that a small
      placeholder index.html shipped in the JAR is still served at /
      by Spring Boot's default static-resource handling.
  - docker/server/config/config.properties
      Commented example of conductor.enable.ui.serving=false near
      the top of the default Docker config.

Verified against:
  rest/src/main/java/org/conductoross/conductor/SpaInterceptor.java
  rest/src/main/java/org/conductoross/conductor/RestConfiguration.java
  server-lite/src/main/resources/application.properties
  rest/src/main/resources/static/index.html

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document conductor.enable.ui.serving property for headless server deployments

2 participants