feat(deploy): bootstrap deploy/.env and add auth-enabled flag (FLPATH-4806)

[chadcrum]

Summary

Aligns utilities deploy and E2E harness with control-plane compose externalized secrets (dcm-project/control-plane#60).

• Bootstrap deploy/.env from .env.example after cloning control-plane, upserting DB credentials and AUTH_DISABLED
• Add --auth-enabled flag to deploy-dcm.sh (compose auth profile + Keycloak/JWT vars in .env)
• Forward --auth-enabled and --keycloak-url from run-e2e.sh for Jenkins compatibility
• Extend validate-scripts.yaml help checks and update docs

Jira: FLPATH-4806

Depends on: control-plane#60 (flpath-4806-compose-externalize-secrets) — deploy against that branch or merged main with externalized secrets.

[qodo-code-review]

PR Summary by Qodo

Bootstrap deploy secrets and support auth-enabled E2E stacks

✨ Enhancement ⚙️ Configuration changes 🧪 Tests 📝 Documentation 🕐 20-40 Minutes

AI Description

• Bootstrap control-plane compose credentials from its environment template.
• Enable Keycloak and JWT validation through deploy and E2E flags.
• Validate new flags and document authenticated deployment workflows.

Diagram

graph TD
  Harness["E2E Harness"] -->|"forwards flags"| Deploy["Deploy Script"] -->|"clones"| Control["Control Plane"] -->|"provides template"| Env["deploy/.env"] -->|"configures"| Compose["Podman Compose"] --> Tests["E2E Tests"]
  Deploy --> Auth{"Auth enabled?"} -->|"yes"| Compose -->|"auth profile"| Keycloak["Keycloak"] -->|"auth endpoint"| Tests

Loading

High-Level Assessment

The chosen approach is appropriate because it follows control-plane’s new env_file contract while retaining shell-environment overrides required by Jenkins. Directly exporting every compose variable or maintaining a utilities-specific compose override would duplicate upstream configuration and increase drift.

Files changed (6) +167 / -10

Enhancement (2) +121 / -0

deploy-dcm.shBootstrap compose environment and enable the auth profile +105/-0

Bootstrap compose environment and enable the auth profile

• Creates 'deploy/.env' from the control-plane template and idempotently upserts database, version, pull-secret, and authentication values. Adds '--auth-enabled' and 'AUTH_DISABLED=false' handling to activate the compose 'auth' profile across deployment, teardown, and version inspection.

scripts/deploy-dcm.sh

run-e2e.shForward authentication options through the E2E harness +16/-0

Forward authentication options through the E2E harness

• Adds '--auth-enabled' passthrough to deployment and supports '--keycloak-url' by exporting 'DCM_KEYCLOAK_URL' for authentication tests. Help text and examples describe the new Jenkins-compatible options.

tests/run-e2e.sh

Tests (1) +7 / -0

validate-scripts.yamlValidate deploy and E2E authentication help options +7/-0

Validate deploy and E2E authentication help options

• Extends script help-output checks to require the new deploy auth flag, E2E Keycloak option, and 'DCM_KEYCLOAK_URL' documentation.

.github/workflows/validate-scripts.yaml

Documentation (3) +39 / -10

deploy-dcm.mdDocument authenticated deploy and compose credential bootstrap +24/-5

Document authenticated deploy and compose credential bootstrap

• Adds authenticated deployment and teardown examples, documents 'AUTH_DISABLED', and explains how 'deploy/.env' is initialized and populated. The documented lifecycle now includes credential bootstrapping before compose startup.

.cursor/prompts/deploy-dcm.md

CLAUDE.mdDescribe compose secrets and authenticated deployment internals +7/-1

Describe compose secrets and authenticated deployment internals

• Updates repository guidance with the new environment bootstrap stage, auth-enabled lifecycle, E2E passthrough options, and credential helper functions.

CLAUDE.md

README.mdAdd environment bootstrap and auth-enabled usage +8/-4

Add environment bootstrap and auth-enabled usage

• Documents 'deploy/.env' creation as part of deployment and adds a quick-start example for launching Keycloak with JWT validation.

README.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Auth-enabled test runs always fail ✗ Dismissed 🐞 Bug ≡ Correctness

Description

run-e2e.sh forwards --auth-enabled into deployment, but its HTTP and command-line test helpers
never obtain or attach a bearer token. When authentication is enabled, suite setup calls protected
catalog endpoints without credentials and receives the specified 401 response before the normal
tests can run.

Code

tests/run-e2e.sh[R199-201]

+        --auth-enabled)
+            DEPLOY_ARGS+=("$1")
+            shift ;;

Evidence

The new flag enables authentication, while the common request helper sends no Authorization header
and suite initialization immediately accesses protected catalog endpoints. The authentication test
plan explicitly requires those unauthenticated requests to return 401 under this configuration.

tests/run-e2e.sh[199-204]
scripts/deploy-dcm.sh[664-675]
scripts/deploy-dcm.sh[865-871]
tests/e2e/api_helpers_test.go[73-91]
tests/e2e/rehydration_helpers_test.go[54-74]
test-plans/FLPATH-3254-dcm-authentication-test-plan.md[171-202]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`run-e2e.sh --auth-enabled` deploys a control plane that rejects unauthenticated non-health requests, while the E2E HTTP and CLI helpers continue issuing requests without credentials.

## Fix Focus Areas
- tests/run-e2e.sh[199-204]
- tests/e2e/api_helpers_test.go[73-91]
- tests/e2e/cli_helpers_test.go[54-69]

## Recommended Fix
When auth is enabled, wait for Keycloak readiness, obtain a token using the configured Keycloak URL and test credentials, and expose it to the E2E suite. Update the HTTP helper to add the bearer token and configure the CLI helper with equivalent authentication before executing protected operations.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Custom database passwords break startup ✗ Dismissed 🐞 Bug ≡ Correctness

Description

ensure_deploy_env resolves POSTGRES_PASSWORD, DB_PASS, and DB_PASSWORD independently,
assigning adminpass to every alias not explicitly supplied. When a caller overrides only one
supported password variable, the database and services receive different credentials and dependent
services cannot connect.

Code

scripts/deploy-dcm.sh[R659-662]

+    upsert_deploy_env_var "${deploy_dir}" "POSTGRES_PASSWORD" "$(env_or_default POSTGRES_PASSWORD adminpass)"
+    upsert_deploy_env_var "${deploy_dir}" "DB_USER" "$(env_or_default DB_USER admin)"
+    upsert_deploy_env_var "${deploy_dir}" "DB_PASS" "$(env_or_default DB_PASS adminpass)"
+    upsert_deploy_env_var "${deploy_dir}" "DB_PASSWORD" "$(env_or_default DB_PASSWORD adminpass)"

Evidence

The helper falls back each exact variable independently, while repository compose overrides derive
application DB_PASS from the PostgreSQL password so both sides remain synchronized. The new
implementation breaks that relationship whenever only one alias is customized.

scripts/deploy-dcm.sh[616-623]
scripts/deploy-dcm.sh[658-662]
tests/compose-three-tier-app-demo-sp.yaml[22-27]
.cursor/prompts/deploy-dcm.md[127-129]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Database password aliases are resolved independently, so a normal single-variable override creates conflicting credentials in the generated compose environment.

## Fix Focus Areas
- scripts/deploy-dcm.sh[658-662]
- tests/compose-three-tier-app-demo-sp.yaml[22-27]

## Recommended Fix
Resolve one canonical database username and password from the accepted shell variables, detect and reject conflicting explicit values, and write the resolved credentials consistently to every alias required by compose services.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Version checks overwrite live secrets ✗ Dismissed 🐞 Bug ≡ Correctness

Description

The --running-versions branch calls ensure_deploy_env, which unconditionally replaces database
credentials and AUTH_DISABLED in an existing deployment with current-shell values or lab defaults.
Running this nominally read-only command without reproducing the original environment therefore
changes custom secrets and disables auth in .env, leaving later container recreation or restart
with invalid configuration.

Code

scripts/deploy-dcm.sh[R878-880]

+    if [[ -d "${CONTROL_PLANE_TMP_DIR}/deploy" ]]; then
+        ensure_deploy_env "${CONTROL_PLANE_TMP_DIR}" || exit 1
+    fi

Evidence

Running-versions mode targets an existing deployment and now invokes a mutating helper. That helper
always upserts five database values and always writes AUTH_DISABLED, defaulting them when the
caller does not repeat the deployment's original environment.

scripts/deploy-dcm.sh[875-881]
scripts/deploy-dcm.sh[649-675]
scripts/deploy-dcm.sh[530-548]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`--running-versions` invokes the credential bootstrap against an existing deployment, overwriting its `.env` even though version inspection should not change deployment configuration.

## Fix Focus Areas
- scripts/deploy-dcm.sh[878-881]
- scripts/deploy-dcm.sh[649-675]

## Recommended Fix
Remove the `ensure_deploy_env` call from running-versions mode. Validate that the existing compose file and required environment file are present, then inspect the running containers without writing credentials or authentication settings.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Auth teardown can leave Keycloak running ✗ Dismissed 📘 Rule violation ⚙ Maintainability

Description

COMPOSE_PROFILES adds the auth profile only when --auth-enabled or AUTH_DISABLED=false is
supplied, yet .cursor/prompts/tear-down.md still recommends teardown without either setting. When
an assistant follows that prompt after an authenticated deployment, tear_down receives no auth
profile and does not target the Keycloak service.

Code

scripts/deploy-dcm.sh[R869-870]

+if [[ "${AUTH_ENABLED}" == true ]]; then
+    COMPOSE_PROFILES+=("--profile" "auth")

Evidence

Compliance rule 2901048 requires affected Cursor guidance to be updated when commands or behavior
change. The deploy script now conditionally passes the auth compose profile, while the dedicated
teardown prompt still lists only commands that omit the required auth setting; CLAUDE.md confirms
that authenticated teardown must use the same flag.

Rule 2901048: Update project documentation and cursor configs when behavior or conventions change
scripts/deploy-dcm.sh[865-870]
.cursor/prompts/tear-down.md[7-15]
CLAUDE.md[53-53]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The dedicated Cursor teardown prompt omits the authentication flag even though authenticated deployments require the auth compose profile during teardown.

## Fix Focus Areas
- .cursor/prompts/tear-down.md[7-15]

## Recommended Fix
Add an authenticated-stack teardown example using `./scripts/deploy-dcm.sh --auth-enabled --tear-down`, and explain that the same authentication setting used during deployment must be supplied during teardown.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

⚠️ Tickets: not configured — ticket URL found in PR but could not be fetched — check ticket provider credentials

✅ Compliance rules (platform): 18 rules

Review mode: ⚖️ Balanced: This changes deployment authentication, secret-file bootstrapping, compose profiles, and E2E argument forwarding across multiple runtime paths, creating genuine security and operational risk that warrants a complete single-pass review.

Tip of the day

💡 Did you know, you can enable the Remediation agent and Qodo fixes findings in a dedicated fix PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[testetson22]

PR body points at control-plane #60; thread also references #66. In-repo docs don’t state a hard dependency on merged externalized deploy/.env.

Location	Lines	What
GitHub PR #46 description	~191–192	“Depends on: control-plane#60 …”
README.md	38–39	Mentions bootstrap from .env.example; no issue/PR pin
scripts/deploy-dcm.sh	649–652	Fails if deploy/.env.example missing (needs control-plane with FLPATH-4806 layout)

[testetson22]

Most of my feedback is clarity-focused. Functionally everything seems fine, we just might end up with some confusion, particularly if an agent is trying to run through the scripts, parse docs, etc.

[gciavarrini]

Only 2 minor comments, not blockers