Skip to main content

Reviewed-source hotfix workflow

A reviewed-source deployment runs the selected snapshot rather than every edit in the working checkout. Read source selection before publishing a hotfix.

Publish a scoped change​

A scoped backend production build writes to the shared backend artifact volume. Use a reviewed snapshot with the required source contract. Preserve a recoverable source/data backup and the other services' volumes.

Do not copy an entire dirty checkout, rewrite the source manifest, or change source root for a full redeployment merely to publish one service. Automatic schema/client regeneration is outside a source-only hotfix. Normal restart and scoped restart do not rebuild production artifacts. For a full production release, use bash restartDevServers.sh --prod. This does not itself run schema initialization. For a scoped source-only release, use the procedure below.

A scoped restart resumes the saved mode. It does not build or inherently choose development.

For a prepared service with compatible dependencies/schema and an identified reviewed source:

  1. Run bash devServerAttach.sh and select only the intended service.
  2. If its application is active, use Ctrl+C to return to that service's shell. Use stop there if a job remains.
  3. At that shell, enter prod. It refuses existing jobs. For a build-enabled service, the attach supervisor stops that container, builds the service's artifacts, and starts it after the build result.
  4. Check build success, service readiness, and the affected user action.
  5. Detach with Ctrl+P, then Ctrl+Q.

A failed build leaves the service shell without starting the failed output. Correct the cause before retrying prod. Do not infer publication from container Up alone.

Alternatively, an already stopped, prepared service container can use bash devstack.sh --prod start SERVICE. It refuses an already running container. Do not stop the whole stack merely to satisfy this precondition. Backend service builds share the backend artifact volume, so the reviewed source must be compatible with the other backend services.

Production docs can use this procedure with docs; their build creates build/site. Development docs use the source-watching npm start process.

The local search hash scans only docs/en and docs/hu. Private AgentStuffs files stay outside the published content and search input. Preserve this separation when changing the docs build configuration; private artifact targets may be unavailable inside the container.

Release a coordinated source change​

Scoped start, scoped restart, and service-shell prod use the configured source root. They do not remove a source pin. A successful build from an older snapshot does not validate newer checkout changes.

Use a coordinated release when the selected source includes changes across services, dependencies, or schemas. Review the complete selected revision, including earlier fixes. Run lifecycle commands from the original deployment root.

  1. Preserve the selected snapshot, recoverable backups, volumes, data, and authorization/encryption keys.
  2. Stop only the selected deployment with bash stopDevServer.sh. Check that its application writers stopped before changing source.
  3. Change only ECS_APPLICATION_SOURCE_ROOT in that deployment's root .env to the reviewed source. Use ECS_APPLICATION_SOURCE_ROOT=. to select the current checkout. Keep credentials and all other settings unchanged.
  4. Run the normal full production start: bash startDevServers.sh --prod. It runs initialization and production builds before application startup.
  5. Check the selected source, build results, readiness, and affected browser actions, including reload. Record acceptance against the actual source.

Source selection does not create a snapshot or alter an existing one. Keep existing schema mappings, tables, keys, and foreign-key actions compatible in both backend and BFF schemas. If schema checks report destructive changes, stop and correct the mappings or migration. Do not add --accept-data-loss or --force-reset, reset data, or delete volumes.

Full bash restartDevServers.sh --prod rebuilds production artifacts but does not run schema initialization. Use the full start above when the coordinated release needs initialization. Preserve unrelated deployments and the shared proxy.

Grant generated-UI tools​

Provider tool registration does not grant permission. The intended group's Agent tool access needs explicit displayOpenUI and displayMarkdown grants. Preserve existing grants. Canonical Admin save checks the caller and audits the change.

Keep the AGENT_TOOL_GRANT_REQUIRED check. Complexity chat permission and active run/chat tool selection remain separate requirements.

After publication, check service readiness and the affected user action. A source-file change alone does not prove that running code changed.

For optional custom React views, read custom-runtime setup before activation.