bcgov / nr-fop

Apache License 2.0
0 stars 0 forks source link
bcgov bcgov-wlrs nodejs openshift wlrs

Quality Gate Status Merge to Main Unit Tests and Analysis

Issues Pull Requests MIT License Lifecycle

QuickStart: OpenShift, TypeScript Frontend (React with Caddy WebServer), Pluggable Backend (Nest.js with Node Runtime, FastAPI with Python, Quarkus with Java On Native, Fiber with Golang), and Postgres/PostGIS

The DevOps Quickstart is a fully functional set of pipeline workflows and a starter application stack intended to help Agile DevOps teams hit the ground running. Currently OpenShift is supported with plans for AWS (Amazon Web Services). Pipelines are run using GitHub Actions.

Features:

Workflows

Pull Request Opened

Runs on pull request submission.

Pull Request Closed

Runs on pull request close or merge.

Merge to Main

Runs on merge to main branch.

* excludes database changes

Unit Tests

Runs on pull request submission or merge to main.

Starter Application

The starter stack includes a (React, MUI, Vite, Caddy) frontend, Pluggable backend(Nest/Node, Quarkus/Java On Native, FastAPI/Python, Fiber/Golang) and postgres database. See subfolder for source, including Dockerfiles and OpenShift templates.

Features:

Postgres is default. Switch to PostGIS by copying the appropriate Dockerfile to ./database:

cp ./database/postgis/Dockerfile ./database

Getting Started

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

Prerequisites

The following are required:

GitHub Repository from Template

Create a new repository using this repository as a template.

GitHub Secrets, Variables and Environments

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

Repository Secrets and Variables

Repository secrets and variables are available to all workflows, except pull requests triggered by Dependabot.

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

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

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

Environment

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.

Click Settings > Environments > New environment

Environments provide a number of features, including:

Secret and Variable Values

Secrets

GITHUB_TOKEN

Default token. Replaced every workflow run, available to all workflows.

OC_TOKEN

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

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 (see above)

SONAR_TOKEN and Other Sonar Tokens

If SonarCloud is being used each application will have its own token. Single-application repositories typically use ${{ secrets.SONAR_TOKEN }}, but monoreposities will have multiple, like ${{ secrets.SONAR_TOKEN_BACKEND }} and ${{ secrets.SONAR_TOKEN_FRONTEND }}.

BC Government employees can request SonarCloud projects from bcdevops/devops-requests by creating a SonarCloud request/issue. This template expects a monorepo, so please ask for that and provide component names (e.g. backend, frontend).

Variables

OC_SERVER

OpenShift server address.

OC_NAMESPACE

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

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:

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/nr-fop/packages

Branch Protection

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.

  1. Select Settings (gear, top right) -> Branches (under Code and Automation)
  2. Click Add Rule or edit an existing rule
  3. Under Protect matching branches specify the following:
    • Branch name pattern: main
    • [check] Require a pull request before merging
      • [check] Require approvals (default = 1)
      • [check] Dismiss stale pull request approvals when new commits are pushed
      • [check] Require review from Code Owners
    • [check] Require status checks to pass before merging
      • [check] Require branches to be up to date before merging
      • Status checks that are required:
        • Select checks as appropriate, e.g. Build x, Deploy y
    • [check] Require conversation resolution before merging
    • [check] Include administrators (optional)

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

Natural Resources Kickstarter

Members of the BC Government's Natural Resource minisistries are strongly recommended to follow the recommendations in their Kickstarter Guide. The linked document is generated from Confluence, so some links may be internal-only (sorry!).

Natural Resources Kickstarter Guide

Pluggable Backends

The quickstart comes with several pluggable backend components. Please delete the extra backends and remove them from any related workflows.

Unit Testing / Integration Testing for Node/Nest Backend

Currently, the unit testing and integration testing is done in the same stage. Please make sure the database container is up and running. please run this command from the root of the repository if the DB container is not running.

 docker compose up -d database
 # or
 podman compose up -d database

Database Documentation using SchemaSpy

The database documentation are auto generated by SchemaSpy and deployed to GitHub pages, it is available here.

Please update the pages in the repo settings as per the screenshot.

img.png

Feedback

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

Acknowledgements

This Action is provided courtesy of the Forestry Suite of Applications, part of the Government of British Columbia.