DevOps & Deployment

For a quick local run of the stack, see docs/GETTING-STARTED.md.

Source Control

• Repository hosted on GitHub for collaboration and version control.

CI/CD (GitHub Actions)

• Automated build and test on pushes to any branch and pull requests to main.
• Python job: step-level detection, ruff/black/pytest, pip cache, runs on Python 3.12.
• Frontend job: step-level detection for package.json, uses Node LTS with npm cache, build/test with --if-present.
• Concurrency and minimal permissions configured.

Skip CI when needed: include "[skip ci]" in the commit message (push) or PR title (pull_request). See docs/devops/ci-cd.md for details.

See the full pipeline docs in docs/devops/ci-cd.md for the YAML, troubleshooting, and enhancements.

Deployment

• Deploy to a hosted Linux server (via SSH, Docker, or other methods).
• Environment variables and secrets managed securely.
• See docs/devops/deployment.md for environments, workflows, access (OIDC), triggers, and runbooks.
• Shared environment definitions: docs/devops/environments.md.
• Shared secrets guidance: docs/devops/secrets.md.

Authentication (Auth0 Free)

• Identity provider: Auth0 (Free). The SPA uses OIDC with PKCE; the API validates RS256 JWTs via JWKS.
• Configuration (per environment): domain, audience, client id. Treat as configuration; do not embed secrets in the repo.
• Secrets (if M2M or management APIs are introduced later) should live in a secrets manager and be injected at runtime.

See Docker setup in docs/devops/docker.md for local development containers and packaging guidance.

Branching Strategy

• Trunk-Based Development:
  • Short-lived feature branches.
  • All merges go through pull requests to main.
  • Frequent integration and deployment.

Branch Protection & PR Workflow

• Require code review and passing checks before merging to main.
• Automated tests and linting on every PR.
• Updates to strategies ([design/strategies.md]) and architecture ([design/architecture.md]) should follow the same PR and review process.

Server Setup & Security

• Hardened Linux server (firewall, SSH keys, regular updates).
• Secure handling of deployment credentials.

Observability

• Design and standards for logs, metrics, traces, dashboards, and alerting are defined in docs/devops/observability.md.
• Initial scope covers structured JSON logs, Prometheus metrics, and OpenTelemetry tracing with phased adoption of a collector and alerting.
• Stack decision (discussion): Grafana Free (Prometheus/Loki/Tempo) as the primary backend; exporters configured via OpenTelemetry. Secrets (Grafana API keys) managed with GitHub Environments/Secrets.