Frontend (JavaScript/TypeScript)

Backend (JavaScript/TypeScript)

QuickStart for OpenShift

Pull Request-Based Workflows with Sample Stack

The is a fully functional set of GitHub Actions workflows and a starter application stack intended to help Agile teams hit the ground running.

Features:

• Pull Request-based pipeline
• Sandboxed development environments
• Gateable production deployments
• Container publishing (ghcr.io) and importing (OpenShift)
• Security, vulnerability, infrastructure, and container scan tools
• Automatic dependency patching available from bcgov/renovate-config
• Enforced code reviews and workflow jobs (pass|fail)
• Helm Package Manager for atomic deployments
• Prometheus Metrics export from Backend/Frontend
• Resource Tuning with Horizontal Pod Autoscaler (TEST/PROD only)
• Affinity and anti-affinity for Scheduling on different worker nodes
• Rolling updates with zero downtime in PROD
• Database Migrations with Flyway
• Pod disruption budgets for high availability
• Self-healing through with 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
  • Frontend: TypeScript, Caddy Server
  • Backend: TypeScript, Nest.js
  • Alternative backend examples - see Alternative Backends

Setup

Initial setup is intended to take an hour or less. This depends greatly on intended complexity, features selected/excluded and outside cooperation.

Prerequisites

The following are required:

• BC Government IDIR accounts for anyone submitting requests
• GitHub accounts for all participating team members
• Membership in the BCGov GitHub organization
  • Provide GitHub IDs to BCGov's Just Ask
• OpenShift project namespaces:
  • BCGov signup

Using this Template

Create a new repository using this repository as a template.

• Verify bcgov/quickstart-openshift is selected under Repository template

Secrets and Variables

Variables and secrets are consumed by workflows. Environments provide their own values, overriding default sets.

Secrets are hidden from logs and outputs, while variables are visible. Using secrets exclusively can make troubeshooting more difficult.

Note: Dependabot, which we don't recommend as highly as Renovate, requires its own set of variables.

Secrets Values

Click Settings > Secrets and Variables > Actions > Secrets > New repository secret

OC_TOKEN

OpenShift token, different for every project/namespace. This guide assumes your OpenShift platform team has provisioned a pipeline account.

• Consume: {{ secrets.OC_TOKEN }}

Locate an OpenShift pipeline token:

1. Login to your OpenShift cluster, e.g.: Gold or Silver
2. Select your DEV namespace
3. Click Workloads > Secrets (under Workloads for Administrator view)
4. Select pipeline-token-... or a similarly privileged token
5. Under Data, copy token
6. Paste into the GitHub Secret OC_TOKEN

OC_NAMESPACE

OpenShift project/namespace. Provided by your OpenShift platform team.

• Consume: {{ secrets.OC_NAMESPACE }}
• Value: format abc123-dev | test | prod

SONAR_TOKEN(s)

If SonarCloud is being used each application will have its own token. Single-application repositories typically use ${{ secrets.SONAR_TOKEN }}, while monorepos use similar names.

E.g.:

• ${{ secrets.SONAR_TOKEN_BACKEND }}
• ${{ secrets.SONAR_TOKEN_FRONTEND }}

BC Government employees can request SonarCloud projects by creating an issue with BCDevOps. Please make sure to request a monorepo with component names (e.g. backend, frontend), which may not be explained in their directions.

Variable Values

Click Settings > Secrets and Variables > Actions > Variables > New repository variable

OC_SERVER

OpenShift server address.

• Consume: {{ vars.OC_SERVER }}
• Value: https://api.gold.devops.gov.bc.ca:6443 or https://api.silver.devops.gov.bc.ca:6443

MS_TEAMS_WEBHOOK_URI

• Consume: {{ vars.MS_TEAMS_WEBHOOK_URI }}
• Value:
• Refrence: 'https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=newteams%2Cdotnet' & 'https://learn.microsoft.com/en-us/outlook/actionable-messages/message-card-reference'

Environments

Environments are groups of secrets and variables that can be gatekept. This includes limting access to certain users or requiring manual approval before a requesting workflow can run. Environment values override any default values.

For pull requests and development surrounding lower-level, sandboxed environments it is best not to use an environment at all. Higher level environments, like TEST and PROD, will override those values as necessary.

Click Settings > Environments > New environment

Environments provide a number of features, including:

• Required reviewers
• Wait timer
• Deployment branches

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.

Renovate

A config file (renovate.json) is included with this template. It can source config from our renovate repository. Renovate can be self-hosted or run using the GitHub App managed at the organization level. For BC Government the OCIO controls this application, so please opt in with them using a GitHub issue.

To opt-in:

• Visit the Renovate GitHub App
• Click Configure and set up your repository
• Visit BCDevOps Requests
• Select Issues
• Select New Issue
• Select Request for integrating a GitHub App
• Create a meaningful title, e.g. Request to add X repo to Renovate App
• Fill out the description providing a repository name
• Select "Submit new issue"
• Wait for Renovate to start sending pull requests to your repository

Dependabot

Dependabot is no longer recommended as an alternative to Renovate for generating security, vulnerability and dependency pull requests. It can still be used to generate warnings under the GitHub Security tab, which is only viewable by repository administrators.

Repository Configuration

Pull Request Handling

Squash merging is recommended for simplified history and ease of rollback. Cleaning up merged branches is recommended for your DevOps Specialist's fragile sanity.

Click Settings > General (selected automatically)

Pull Requests:

• [uncheck] Allow merge commits
• [check] Allow squash merging
  • Default to pull request title
• [uncheck] Allow rebase merging
• [check] Always suggest updating pull request branches
• [uncheck] Allow auto-merge
• [check] Automatically delete head branches

Packages

Packages are available from your repository (link on right). All should have visibility set to public for the workflows to run successfully.

E.g. https://github.com/bcgov/quickstart-openshift/packages

Branch Protection Rules

This is required to prevent direct pushes and merges to the default branch. These steps must be run after one full pull request pipeline has been run to populate the required status checks.

1. Select Settings (gear, top right) > Rules > Rulesets (under Code and Automation)
2. Click New ruleset > New branch ruleset
3. Setup Ruleset:
   • Ruleset Name: main
   • Enforcement status: Active
   • Bypass list:
     • Click + Add bypass
     • Check [x] Repository admin
     • Click Add selected
   • Target branches:
     • Click Add target
     • Select Add default branch
   • Branch protections:
     • [x] Restrict deletions
     • [x] Require linear history
     • [x] Require a pull request before merging
       • Additional settings:
         • Require approvals: 1 (or more!)
         • [x] Require conversation resolution before merging
     • [x] Require status checks to pass
       • [x] Require branches to be up to date before merging
       • Required checks: These will be populated after a full pull request pipeline run!
         • Click +Add checks
         • This is our default set, yours may differ:
           • Analysis Results
           • PR Results
           • Validate Results
   • [x] Block force pushes
   • [x] Require code scanning results
     • Click + Add tool
     • This is our default set, yours may differ:
       • CodeQL
       • Trivy
   • Click Create

Status checks example

Required tools and alerts example

Adding Team Members

Don't forget to add your team members!

1. Select Settings (gear, top right) *> Collaborators and teams (under Access)
2. Click Add people or Add teams
3. Use the search box to find people or teams
4. Choose a role (read, triage, write, maintain, admin)
5. Click Add

Workflows

Pull Request

Runs on pull request submission.

• Provides safe, sandboxed deployment environments
• Build action pushes to GitHub Container Registry (ghcr.io)
• Build triggers select new builds vs reusing builds
• Deploy only when changes are made
• Deployment includes curl checks and optional penetration tests
• Run tests (e2e, load, integration) when changes are made
• Other checks and updates as required

Validation

Runs on pull request submission.

• Enforces conventional commits in PR title
• Adds greetings/directions to PR descriptions

Analysis

Runs on pull request submission or merge to the default branch.

• Unit tests (should include coverage)
• CodeQL/GitHub security reporting (now handled as GitHub default!)
• Trivy password, vulnerability and security scanning

Pull Request Closed

Runs on pull request close or merge.

• Cleans up OpenShift objects/artifacts
• Merge retags successful build images as latest

Merge

Runs on merge to main branch.

• Code scanning and reporting to GitHub Security overview
• Zero-downtime* TEST deployment
• Penetration tests on TEST deployment (optional)
• Zero-downtime* PROD deployment
• Labels successful deployment images as PROD

* excludes database changes

Scheduled

Runs on scheduled job (cronjob) or workflow dispatch.

• PR environment purge
• Generate SchemaSpy documentation
• Tests (e2e, load, integration) on TEST deployment

DEMO Routing

There is a long-lived custom route available to be assigned to specific Pull Request deployments. Add the label demo to that pull request or run the DEMO Route workflow.

Typical route: https://<REPO_NAME>-demo.apps.silver.devops.gov.bc.ca

PR Label

Please note that the label must be manually created using GitHub's web interface.

Workflow

App Stack

Starter

The starter stack includes a frontend (React, MUI, Vite, Caddy), backend (Nest/Node) and postgres or postgis database. See subfolder for source, including Dockerfiles and OpenShift templates. Alternative backends are available.

Features:

• TypeScript strong-typing for JavaScript
• NestJS Nest/Node backend and frontend
• Flyway database migrations
• Crunchy Postgres/Postgis Database

Postgis is default. Switch to Postgres by removing the image names in crunchy helm chart values

Crunchy

Crunchy is the default choice for HA postgres/postgis DB in BCGov. provided chart is to get up and going fast, it is upto teams to fine tune resource allocation and patroni parameters of crunchy DB to get the best out of database.

• For specifying different resources for different envs, just add values-test.yml and values-prod.yml , then provide them to the DB Deployer in GHA.
• For enabling S3 backups/recovery, please enable in values file, and in the DB Deployer in GHA, then provide necessary secret values which are prefixed with s3 DB Deployer in GHA
• To disable crunchy deployment, make the following changes
  • make crunchy enabled to false in values.yaml
  • make bitnami postgis enabled to true in values.yaml
  • make the db-deployer false in gha workflow .deployer-db.yaml

Alternative Backends

The sample Java, Python and Go backends repository has been archived, but we have lots of other great examples of active projects you can learn from!

• NR-RFC-AlertAuthoring - Python with FastAPI and Alembic
• QuickStart OpenShift Backends

SchemaSpy

The database documentation is created and deployed to GitHub pages. See here.

After a full workflow run and merge can been run, please do the following:

1. Select Settings (gear, top right) *> Pages (under Code and automation)
2. Click Branch or Add teams
3. Select gh-pages
4. Click Save

Flyway, Prisma, Migrations

1. Flyway is used as Database Schema Migration tool
2. Prisma is used as ORM layer
3. The rationale behind using flyway to have schema first approach and let prisma generate ORM schema from the database, which would avoid pitfalls like , lazy loading, cascading et.. when defining entities in ORM manually.
4. Run flyway in the docker compose to apply latest changes to postgres db.
5. Run npx prisma db pull from backend folder to sync the prisma schema.
6. Run npx prisma generate to generate the prisma client which will have all the entities populated based on fresh prisma schema.
7. if using vscode be aware of this issue

Resources

This repository is provided by NRIDS Architecture and Forestry Digital Services, courtesy of the Government of British Columbia.

• NRID's Kickstarter Guide (via. Confluence, links may be internal)

Contributing

Please contribute your ideas! Issues and Pull Requests are appreciated.