feat: single db as primary and crunchy as secondary

Author: mishraomp

.github/workflows/.deployer.yml

@@ -88,13 +88,18 @@ jobs:
     name: Stack
     environment: ${{ inputs.environment }}
     runs-on: ubuntu-24.04
+    env:
+      # Repo-level toggle: Settings -> Variables -> Actions
+      # Expected values: 'single' or 'crunchy'
+      DB_PROVIDER: ${{ vars.DB_PROVIDER || 'single' }}
     outputs:
       tag: ${{ inputs.tag || steps.pr.outputs.pr }}
       triggered: ${{ steps.deploy.outputs.triggered }}
     steps:
       - uses: bcgov/action-crunchy@a109166ff26880dc75676492a33b816ac0ce392f # v1.2.6
         name: Deploy Crunchy
         id: deploy_crunchy
+        if: env.DB_PROVIDER == 'crunchy'
         with:
           oc_namespace: ${{ secrets.OC_NAMESPACE }}
           oc_token: ${{ secrets.OC_TOKEN }}
@@ -120,15 +125,44 @@ jobs:
           # version, to support helm packaging for non-pr based releases (workflow_dispatch). default to 1.0.0+github run number
           version=1.0.0+${{ github.run_number }}
 
+          # Database provider toggle
+          db_provider="${DB_PROVIDER}"
+          if [ "${db_provider}" != "single" ] && [ "${db_provider}" != "crunchy" ]; then
+            echo "Unsupported DB_PROVIDER='${db_provider}'. Expected 'single' or 'crunchy'." >&2
+            exit 1
+          fi
+
+          # Database alias used by the Helm chart:
+          # - crunchy: points at operator-created Secrets/Services
+          # - single: points at in-release Service named '${release}-db'
+          crunchy_release="${{ steps.deploy_crunchy.outputs.release }}"
+          if [ "${db_provider}" = "crunchy" ]; then
+            databaseAlias="${crunchy_release}-crunchy"
+            db_password=""
+            db_name=""
+          else
+            databaseAlias="db"
+            db_name="app"
+            # Keep it URL-safe and helm-flag-safe (no quotes/spaces)
+            db_password=$(openssl rand -hex 24)
+          fi
+
             # Summary
           echo "tag=${tag}"
           echo "release=${release}"
           echo "version=${version}"
+          echo "db_provider=${db_provider}"
+          echo "databaseAlias=${databaseAlias}"
+          [ -z "${db_name}" ] || echo "db_name=${db_name}"
 
           # Output
           echo "tag=${tag}" >> $GITHUB_OUTPUT
           echo "release=${release}" >> $GITHUB_OUTPUT
           echo "version=${version}" >> $GITHUB_OUTPUT
+          echo "db_provider=${db_provider}" >> $GITHUB_OUTPUT
+          echo "databaseAlias=${databaseAlias}" >> $GITHUB_OUTPUT
+          echo "db_name=${db_name}" >> $GITHUB_OUTPUT
+          echo "db_password=${db_password}" >> $GITHUB_OUTPUT
 
       - name: Stop pre-existing deployments on PRs (status = pending-upgrade)
         if: github.event_name == 'pull_request'
@@ -172,11 +206,17 @@ jobs:
             helm package -u . --app-version="tag-${{ steps.vars.outputs.tag }}_run-${{ github.run_number }}" --version=${{ steps.pr.outputs.pr || steps.vars.outputs.version }}
             # print the values.yaml file to see the values being used
             # Helm upgrade/rollout
+            DB_PARAMS=""
+            if [ "${{ steps.vars.outputs.db_provider }}" = "single" ]; then
+              DB_PARAMS="--set-string global.secrets.databaseName=${{ steps.vars.outputs.db_name }} --set-string global.secrets.databasePassword=${{ steps.vars.outputs.db_password }}"
+            fi
             helm upgrade \
               --set-string global.repository=${{ github.repository }} \
               --set-string global.tag="${{ steps.vars.outputs.tag }}" \
               --set-string global.config.databaseUser="${{ inputs.db_user }}" \
-              --set-string global.databaseAlias="${{ steps.deploy_crunchy.outputs.release }}-crunchy" \
+              --set-string global.database.provider="${{ steps.vars.outputs.db_provider }}" \
+              --set-string global.databaseAlias="${{ steps.vars.outputs.databaseAlias }}" \
+              ${DB_PARAMS} \
               ${{ inputs.params }} \
               --install --wait ${{ inputs.atomic && '--atomic' || '' }} ${{ steps.vars.outputs.release }} \
               --timeout ${{ inputs.timeout-minutes }}m \

.github/workflows/demo.yml

@@ -32,7 +32,7 @@ jobs:
           oc_namespace: ${{ secrets.oc_namespace }}
           oc_token: ${{ secrets.oc_token }}
           oc_server: ${{ vars.oc_server }}
-          command: |
+          commands: |
             oc delete route/${{ env.REPO }}-${{ env.DEST }} --ignore-not-found=true
             oc create route edge ${{ env.REPO }}-${{ env.DEST }} \
               --hostname=${{ env.REPO }}-${{ env.DEST }}.${{ env.DOMAIN }} \

.github/workflows/merge.yml

@@ -4,16 +4,16 @@ on:
   push:
     branches: [main]
     paths-ignore:
-      - '*.md'
-      - '.github/**'
-      - '.github/graphics/**'
-      - '!.github/workflows/**'
+      - "*.md"
+      - ".github/**"
+      - ".github/graphics/**"
+      - "!.github/workflows/**"
   workflow_dispatch:
     inputs:
       tag:
         description: "Image tag set to deploy; e.g. PR number or prod"
         type: string
-        default: 'prod'
+        default: "prod"
 
 concurrency:
   # Do not interrupt previous workflows
@@ -48,8 +48,7 @@ jobs:
     with:
       environment: prod
       db_user: appproxy # appproxy is the user which works with pgbouncer.
-      params:
-        --set backend.deploymentStrategy=RollingUpdate
+      params: --set backend.deploymentStrategy=RollingUpdate
         --set frontend.deploymentStrategy=RollingUpdate
         --set global.autoscaling=true
         --set frontend.pdb.enabled=true
@@ -64,7 +63,7 @@ jobs:
       packages: write
     strategy:
       matrix:
-        package: [migrations, backend, frontend]
+        package: [migrations, backend, frontend, database, pgbouncer]
     timeout-minutes: 1
     steps:
       - uses: shrink/actions-docker-registry-tag@f04afd0559f66b288586792eb150f45136a927fa # v4

.github/workflows/pr-open.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-24.04
     strategy:
       matrix:
-        package: [backend, frontend, migrations]
+        package: [backend, frontend, migrations, database, pgbouncer]
     timeout-minutes: 10
     steps:
       - uses: bcgov/action-builder-ghcr@2b24ac7f95e6a019064151498660437cca3202c5 # v4.2.1
@@ -40,14 +40,14 @@ jobs:
     with:
       db_user: app-${{ github.event.number }}
       params: --set global.secrets.persist=false
-      triggers: ('backend/' 'frontend/' 'migrations/' 'charts/' '.github/workflows/.deployer.yml')
+      triggers: ('backend/' 'frontend/' 'migrations/' 'database/' 'pgbouncer/' 'charts/' '.github/workflows/.deployer.yml')
       db_triggers: ('charts/crunchy/')
 
   tests:
-     name: Tests
-     if: needs.deploys.outputs.triggered == 'true'
-     needs: [deploys]
-     uses: ./.github/workflows/.tests.yml
+    name: Tests
+    if: needs.deploys.outputs.triggered == 'true'
+    needs: [deploys]
+    uses: ./.github/workflows/.tests.yml
 
   results:
     name: PR Results

README.md

@@ -28,7 +28,7 @@ This repository provides a template to rapidly deploy a modern web application s
 * 🔍 Self-healing through probes/checks (startup, readiness, liveness)
 * 🎯 Point the long-lived DEMO route to PRs by using the `demo` label
 * **Sample application stack:**
-    * 🗄️ Database: Crunchy (Postgres, PostGIS), backups, Flyway
+    * 🗄️ Database: Single Postgres/PostGIS (default) or Crunchy (optional), backups, Flyway
     * 🎨 Frontend: TypeScript, Caddy Server with Coraza WAF
     * ⚙️ Backend: TypeScript, Nest.js
     * 🔄 Alternative backend examples - see [Alternative Backends](#alternative-backends)
@@ -152,6 +152,16 @@ OpenShift server address (API endpoint for your OpenShift cluster).
 * Example values (BCGov): `https://api.gold.devops.gov.bc.ca:6443` or `https://api.silver.devops.gov.bc.ca:6443`
 * For other OpenShift clusters: Use your cluster's API server address (typically `https://api.<cluster-domain>:6443`)
 
+**`DB_PROVIDER`** 🗄️
+
+Database provider toggle for deployments.
+
+* Where: `Settings > Secrets and Variables > Actions > Variables`
+* Values: `single` (default) or `crunchy`
+* Behavior:
+    * `single`: Deploys an in-release Postgres/PostGIS StatefulSet with PgBouncer sidecar (no Crunchy operator resources).
+    * `crunchy`: Deploys Crunchy via `bcgov/action-crunchy` and wires the app to the Crunchy-generated service/secrets.
+
 ## 🔄 Updating Dependencies
 
 Dependabot and Mend Renovate can both provide dependency updates using pull requests.  Dependabot is simpler to configure, while Renovate is much more configurable and lighter on resources.
@@ -454,10 +464,14 @@ The starter stack includes a frontend (React, Bootstrap, Vite, Caddy), backend (
 * 💪 [TypeScript](https://www.typescriptlang.org/) strong-typing for JavaScript
 * 🏗️ [NestJS](https://docs.nestjs.com) Nest/Node backend and frontend
 * 🔄 [Flyway](https://flywaydb.org/) database migrations
-* 🐘 [Crunchy](https://www.crunchydata.com/products/crunchy-postgresql-for-kubernetes) Postgres/PostGIS Database
+* 🗄️ Database provider toggle (`single` or `crunchy`)
+* 🐘 [Crunchy](https://www.crunchydata.com/products/crunchy-postgresql-for-kubernetes) Postgres/PostGIS Database (optional)
+* 🐘 Single Postgres/PostGIS (default) with PgBouncer sidecar
 * 🛡️ [OWASP Coraza WAF](https://github.com/corazawaf/coraza-caddy) Web Application Firewall integrated with Caddy
 
-PostGIS is enabled by default for geospatial data support when postGISVersion value is provided. To switch to standard PostgreSQL, update the `postGISVersion` field in the [Crunchy Helm chart values](./charts/crunchy/values.yml) to `~`. This disables PostGIS extensions, making it a plain PostgreSQL setup.
+PostGIS notes:
+* **Single mode** uses the repository-owned database image (built from `./database/Dockerfile`), currently targeting Postgres 18 + PostGIS.
+* **Crunchy mode** uses `charts/crunchy/values.yml`. PostGIS is enabled when `crunchy.postGISVersion` is set; to switch to standard PostgreSQL, set it to `~`.
 
 ### 🛡️ OWASP Coraza WAF: Application Security
 
@@ -504,9 +518,34 @@ The WAF is integrated directly into the Caddy web server, providing real-time pr
 
 For more details, see the [Coraza documentation](https://coraza.io/docs/).
 
-## 🗄️ Crunchy Database
+## 🗄️ Database
+
+This template supports two database providers. The provider is controlled via the repository variable `DB_PROVIDER` and is also passed into Helm as `global.database.provider`.
+
+### 🐘 Single Postgres/PostGIS (default)
+
+This mode deploys a NON-HA database **inside the application Helm release**:
+
+* A Postgres/PostGIS **StatefulSet** and **Service** named `<release>-db`
+* A **PgBouncer sidecar** (service port 5432 targets PgBouncer)
+* Optional backups via a **CronJob** using the BCGov backup container (`ghcr.io/bcgov/backup-container`)
+
+Images:
+* Database image is built from `./database/Dockerfile` and published to GHCR (expected default: `ghcr.io/<org>/<repo>/database:<tag>`)
+* PgBouncer image is built from `./pgbouncer/Dockerfile` and published to GHCR (expected default: `ghcr.io/<org>/<repo>/pgbouncer:<tag>`)
+
+Backups (single mode):
+* Enable with Helm values: `global.database.backup.enabled=true`
+* Configure schedule/retention/PVC under `global.database.backup.*` in `charts/app/values.yaml`
+* Optional object storage settings live under `global.database.backup.s3.*`
+Pros:
+* Simple to maintain, low resource consumption
+Cons:
+* Non HA:  https://developer.gov.bc.ca/docs/default/component/platform-developer-docs/docs/automation-and-resiliency/app-resiliency-guidelines/#a-highly-available-application
+
+### 🐘 Crunchy Database (optional)
 
-Crunchy is the default choice for high availability (HA) Postgres/PostGIS databases in BC Government.
+Crunchy is still the recommended choice for high availability (HA) Postgres/PostGIS databases in BC Government with its known pitfalls and drawbacks around operational overhead.
 
 ### 🌟 Key Features
 - ⚡ Automatic failover with Patroni
@@ -521,11 +560,7 @@ Crunchy is the default choice for high availability (HA) Postgres/PostGIS databa
 3. **🚨 DR Testing**: Disaster Recovery Testing is **`MANDATORY`** before go live.
 
 ### 💾 Enabling S3 Backups
-To enable S3 backups/recovery, provide these parameters to the GitHub Action:
-- `s3_access_key`
-- `s3_secret_key` 
-- `s3_bucket`
-- `s3_endpoint`
+To enable S3 backups/recovery in Crunchy mode, configure `crunchy.pgBackRest.s3.*` in `charts/crunchy/values.yml` (or an environment-specific override values file).
 
 > **Important**: Never reuse the same s3/object store, bucket path across different Crunchy deployments or instances (dev, test, prod)
 

charts/app/templates/_helpers.tpl

@@ -44,3 +44,45 @@ Selector labels
 app.kubernetes.io/name: {{ include "fullname" . }}
 app.kubernetes.io/instance: {{ .Release.Name }}
 {{- end }}
+
+{{/*
+Database component helpers (single-db mode)
+*/}}
+{{- define "db.name" -}}
+{{- printf "db" -}}
+{{- end }}
+
+{{- define "db.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "db.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{- define "db.labels" -}}
+{{ include "db.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+app.kubernetes.io/component: db
+{{- end }}
+
+{{/*
+Database backup component helpers
+*/}}
+{{- define "dbbackup.name" -}}
+{{- printf "db-backup" -}}
+{{- end }}
+
+{{- define "dbbackup.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "dbbackup.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{- define "dbbackup.labels" -}}
+{{ include "dbbackup.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+app.kubernetes.io/component: db-backup
+{{- end }}

charts/app/templates/backup/cronjob.yaml

@@ -0,0 +1,48 @@
+{{- if and (eq (default "single" .Values.global.database.provider) "single") (.Values.global.database.backup.enabled | default false) }}
+---
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: {{ .Release.Name }}-db-backup
+  labels: {{- include "dbbackup.labels" . | nindent 4 }}
+spec:
+  schedule: {{ default "0 8 * * *" .Values.global.database.backup.schedule | quote }}
+  concurrencyPolicy: Forbid
+  successfulJobsHistoryLimit: 1
+  failedJobsHistoryLimit: 3
+  jobTemplate:
+    spec:
+      template:
+        metadata:
+          labels: {{- include "dbbackup.labels" . | nindent 12 }}
+        spec:
+          restartPolicy: OnFailure
+          containers:
+            - name: backup
+              image: {{ default "ghcr.io/bcgov/backup-container:2.11.0" .Values.global.database.backup.image }}
+              imagePullPolicy: {{ default "IfNotPresent" .Values.global.database.backup.imagePullPolicy }}
+              env:
+                - name: BACKUP_STRATEGY
+                  value: {{ default "rolling" .Values.global.database.backup.strategy | quote }}
+                - name: DAILY_BACKUPS
+                  value: {{ default "6" .Values.global.database.backup.retention.daily | quote }}
+                - name: WEEKLY_BACKUPS
+                  value: {{ default "4" .Values.global.database.backup.retention.weekly | quote }}
+                - name: MONTHLY_BACKUPS
+                  value: {{ default "1" .Values.global.database.backup.retention.monthly | quote }}
+                - name: BACKUP_DIR
+                  value: "/backups"
+                - name: DATABASE_SERVICE_NAME
+                  value: {{ printf "%s-db" .Release.Name | quote }}
+              envFrom:
+                - secretRef:
+                    name: {{ .Release.Name }}-db-backup
+              volumeMounts:
+                - name: backups
+                  mountPath: /backups
+              resources: {{- toYaml (.Values.global.database.backup.resources | default dict) | nindent 16 }}
+          volumes:
+            - name: backups
+              persistentVolumeClaim:
+                claimName: {{ .Release.Name }}-db-backups
+{{- end }}

charts/app/templates/backup/pvc.yaml

@@ -0,0 +1,17 @@
+{{- if and (eq (default "single" .Values.global.database.provider) "single") (.Values.global.database.backup.enabled | default false) }}
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ .Release.Name }}-db-backups
+  labels: {{- include "labels" . | nindent 4 }}
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: {{ default "25Gi" .Values.global.database.backup.persistence.size }}
+  {{- if .Values.global.database.backup.persistence.storageClassName }}
+  storageClassName: {{ .Values.global.database.backup.persistence.storageClassName }}
+  {{- end }}
+{{- end }}

charts/app/templates/backup/secret.yaml

@@ -0,0 +1,22 @@
+{{- if and (eq (default "single" .Values.global.database.provider) "single") (.Values.global.database.backup.enabled | default false) }}
+{{- $databaseUser := required "global.config.databaseUser is required" .Values.global.config.databaseUser }}
+{{- $databasePassword := required "global.secrets.databasePassword is required for single-db" .Values.global.secrets.databasePassword }}
+{{- $databaseName := default "app" .Values.global.secrets.databaseName }}
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ .Release.Name }}-db-backup
+  labels: {{- include "labels" . | nindent 4 }}
+type: Opaque
+data:
+  POSTGRESQL_USER: {{ $databaseUser | b64enc | quote }}
+  POSTGRESQL_PASSWORD: {{ $databasePassword | b64enc | quote }}
+  POSTGRESQL_DATABASE: {{ $databaseName | b64enc | quote }}
+  {{- if .Values.global.database.backup.s3.enabled }}
+  S3_USER: {{ required "global.database.backup.s3.accessKey is required when s3.enabled=true" .Values.global.database.backup.s3.accessKey | b64enc | quote }}
+  S3_PASSWORD: {{ required "global.database.backup.s3.secretKey is required when s3.enabled=true" .Values.global.database.backup.s3.secretKey | b64enc | quote }}
+  S3_ENDPOINT: {{ required "global.database.backup.s3.endpoint is required when s3.enabled=true" .Values.global.database.backup.s3.endpoint | b64enc | quote }}
+  S3_BUCKET: {{ required "global.database.backup.s3.bucket is required when s3.enabled=true" .Values.global.database.backup.s3.bucket | b64enc | quote }}
+  {{- end }}
+{{- end }}