Title
Automate environment configuration rollout for test/prod containers (remove manual server .env + compose steps)
Type
Platform / DevOps Enhancement
Problem Statement
Environment/config changes currently require manual updates on each host (.env edits + docker compose recreate), which is slow and error-prone. This blocks timely fixes and causes drift between repo intent and runtime state.
Current Evidence
Pipeline builds/pushes images only: docker-build.yaml
Runtime config comes from compose env mapping: docker-compose.yml:4
Admin and auth-related settings are env-driven in compose: docker-compose.yml:10
Documentation explicitly says env changes do not apply until container recreate: README.md:233
Goal
Implement a repeatable, auditable deployment path that applies both image updates and environment/config updates to test/prod without manual SSH/server edits.
Proposed Approach (phased)
Phase 1: Automated remote deploy trigger
Add workflow_dispatch job for test deploy.
Run on self-hosted runner on test host (or secure SSH action).
Pull latest image, regenerate effective env config from GitHub Environment vars/secrets, run docker compose up -d with recreate.
Add post-deploy smoke check for /users/me and health endpoint.
Phase 2: Configuration as code
Move host-specific non-secret config to tracked env files per environment (or generated compose overrides).
Keep secrets in GitHub Environments/Secrets only.
Add drift detection step that reports runtime config hash vs expected config hash.
Phase 3: Promotion flow hardening
Promote tested artifact to prod with approval gate.
Apply same automated config rollout mechanism to prod.
Emit deployment summary including image tags, config version/hash, and smoke-test results.
Acceptance Criteria
Triggering test deploy from GitHub applies both new image and updated env/config without manual server access.
No direct manual edits are required on test/prod hosts for standard config changes.
Deployment logs clearly show:
image tag deployed
environment target
config version/hash (non-secret)
smoke test pass/fail
Secrets are sourced from GitHub Environments only and never echoed in logs.
Rollback path exists and is documented (previous known-good image + config version).
README deployment section is updated to reflect the automated process.
Existing quality gates remain green (unit tests + coverage gate in CI).
For production, deployment still requires manual approval gate.
Non-Goals
Rewriting application auth logic.
Replacing Docker Compose entirely (unless later agreed).
Risks
Self-hosted runner hardening and permissions model.
Secret leakage risk if deploy scripts are too verbose.
Config drift during transition period.
Dependencies
GitHub Environment setup for test/prod variables and secrets.
Host-level permission for runner/SSH identity to run docker compose commands.
Definition of Done
End-to-end test deploy demonstrated from workflow_dispatch with zero manual host edits.
Runbook added for deploy, rollback, and troubleshooting.
README updated and validated against real run.
Production gate still enforced.
Security review completed for secrets handling and least-privilege runner access.
Title
Automate environment configuration rollout for test/prod containers (remove manual server .env + compose steps)
Type
Platform / DevOps Enhancement
Problem Statement
Environment/config changes currently require manual updates on each host (.env edits + docker compose recreate), which is slow and error-prone. This blocks timely fixes and causes drift between repo intent and runtime state.
Current Evidence
Pipeline builds/pushes images only: docker-build.yaml
Runtime config comes from compose env mapping: docker-compose.yml:4
Admin and auth-related settings are env-driven in compose: docker-compose.yml:10
Documentation explicitly says env changes do not apply until container recreate: README.md:233
Goal
Implement a repeatable, auditable deployment path that applies both image updates and environment/config updates to test/prod without manual SSH/server edits.
Proposed Approach (phased)
Phase 1: Automated remote deploy trigger
Add workflow_dispatch job for test deploy.
Run on self-hosted runner on test host (or secure SSH action).
Pull latest image, regenerate effective env config from GitHub Environment vars/secrets, run docker compose up -d with recreate.
Add post-deploy smoke check for /users/me and health endpoint.
Phase 2: Configuration as code
Move host-specific non-secret config to tracked env files per environment (or generated compose overrides).
Keep secrets in GitHub Environments/Secrets only.
Add drift detection step that reports runtime config hash vs expected config hash.
Phase 3: Promotion flow hardening
Promote tested artifact to prod with approval gate.
Apply same automated config rollout mechanism to prod.
Emit deployment summary including image tags, config version/hash, and smoke-test results.
Acceptance Criteria
Triggering test deploy from GitHub applies both new image and updated env/config without manual server access.
No direct manual edits are required on test/prod hosts for standard config changes.
Deployment logs clearly show:
image tag deployed
environment target
config version/hash (non-secret)
smoke test pass/fail
Secrets are sourced from GitHub Environments only and never echoed in logs.
Rollback path exists and is documented (previous known-good image + config version).
README deployment section is updated to reflect the automated process.
Existing quality gates remain green (unit tests + coverage gate in CI).
For production, deployment still requires manual approval gate.
Non-Goals
Rewriting application auth logic.
Replacing Docker Compose entirely (unless later agreed).
Risks
Self-hosted runner hardening and permissions model.
Secret leakage risk if deploy scripts are too verbose.
Config drift during transition period.
Dependencies
GitHub Environment setup for test/prod variables and secrets.
Host-level permission for runner/SSH identity to run docker compose commands.
Definition of Done
End-to-end test deploy demonstrated from workflow_dispatch with zero manual host edits.
Runbook added for deploy, rollback, and troubleshooting.
README updated and validated against real run.
Production gate still enforced.
Security review completed for secrets handling and least-privilege runner access.