added migration to Helm guide

docs/docs/getting-started/installation.md

@@ -6,9 +6,9 @@ permalink: /docs/installation/
 
 _NotifyBC_ can be installed in 3 ways:
 
-1. deploying locally from source code
-2. deploying a Docker container
-3. deploying to Kubernetes
+1. [deploying locally from source code](#deploy-locally-from-source-code)
+2. [deploying a Docker container](#deploy-docker-container)
+3. [deploying to Kubernetes](#deploy-to-kubernetes)
 
 For small-scale production deployment or for evaluation, both source code and docker container will do. For large-scale production deployment that requires horizontal scalability, the recommendation is one of
 
@@ -224,6 +224,28 @@ Following are some example customizations.
       host: 'smtp.myNotifyBC.myOrg.com'
   ```
 
+- To add certificates to OpenShift web route
+
+  ```yaml
+  # in file helm/values.local.yaml
+  route:
+    web:
+      tls:
+        caCertificate: |-
+          -----BEGIN CERTIFICATE-----
+          ...
+          -----END CERTIFICATE-----
+        certificate: |-
+          -----BEGIN CERTIFICATE-----
+          ...
+          -----END CERTIFICATE-----
+        insecureEdgeTerminationPolicy: Redirect
+        key: |-
+          -----BEGIN PRIVATE KEY-----
+          ...
+          -----END PRIVATE KEY-----
+  ```
+
 - To update _config.local.js_ in config map,
 
   ```yaml

docs/docs/getting-started/what's-new.md

@@ -8,9 +8,14 @@ permalink: /docs/what's-new/
 _NotifyBC_ has been built on Node.js [LoopBack](https://loopback.io/) framework since 2017. LoopBack v4, which was released in 2019, is backward incompatible. To keep software stack up-to-date, unless rewriting from scratch, it is necessary to port _NotifyBC_ to LoopBack v4. Great care has been taken to minimize migration effort.
 :::
 
+## v2.6.0
+
+- Helm chart updates
+- docs updates
+
 ## v2.5.0
 
-- added [helm chart](https://github.com/bcgov/NotifyBC/tree/main/helm)
+- added [helm chart](https://github.com/bcgov/NotifyBC/tree/main/helm). See [OpenShift template to Helm migration guide](../miscellaneous/migration.md#openshift-template-to-helm)
 - docs updates
 
 ## v2.4.0

docs/docs/miscellaneous/migration.md

@@ -4,16 +4,18 @@ permalink: /docs/migration/
 
 # Migration Guide
 
+## v1 to v2
+
 Migrating _NotifyBC_ from v1 to v2 involves two steps
 
-1. Update your client code if needed
-2. Migrate _NotifyBC_ server
+1. [Update your client code](#update-your-client-code) if needed
+2. [Migrate _NotifyBC_ server](#migrate-notifybc-server)
 
-## Update client code
+### Update your client code
 
 _NotifyBC_ v2 introduced backward incompatible API changes documented in the rest of this section. If your client code will be impacted by the changes, update your code to address the incompatibility first.
 
-### Query parameter array syntax
+#### Query parameter array syntax
 
 In v1 array can be specified in query parameter using two formats
 
@@ -22,11 +24,11 @@ In v1 array can be specified in query parameter using two formats
 
 In v2 only the latter format is supported.
 
-### Date-Time fields
+#### Date-Time fields
 
 In v1 date-time fields can be specified in date-only string such as 2020-01-01. In v2 the field must be specified in ISO 8601 extended format such as 2020-01-01T00:00:00Z.
 
-### Return status codes
+#### Return status codes
 
 HTTP response code of success calls to following APIs are changed from 200 to 204
 
@@ -35,18 +37,18 @@ HTTP response code of success calls to following APIs are changed from 200 to 20
 - most PUT by id requests except for [Replace a Subscription](../api-subscription/#replace-a-subscription)
 - most DELETE by id requests except for [Delete a Subscription (unsubscribing)](../api-subscription/#delete-a-subscription-unsubscribing)
 
-### Administrator API
+#### Administrator API
 
 - Password is saved to _Administrator_ in v1 and _UserCredential_ in v2. Password is not migrated. New password has to be created by following [Create/Update an Administrator's UserCredential
   ](../api-administrator/#create-update-an-administrator-s-usercredential).
 - [Complexity rules](../api/administrator.md#sign-up) have been applied to passwords.
 - [login](../api-administrator/#login) API is open to non-admin
 
-## Migrate _NotifyBC_ server
+### Migrate _NotifyBC_ server
 
 The procedure to migrate from v1 to v2 depends on how v1 was installed.
 
-### Source-code Installation
+#### Source-code Installation
 
 1. Stop _NotifyBC_
 2. Backup app root and database!
@@ -99,7 +101,7 @@ yarn install && yarn build
 
 11. Start server by running `yarn start` or Windows Service
 
-### OpenShift Installation
+#### OpenShift Installation
 
 1. Run
    ```sh
@@ -109,3 +111,51 @@ yarn install && yarn build
 2. Follow OpenShift [Build](../installation/#build)
 3. Follow OpenShift [Deploy](../installation/#deploy)
 4. Follow OpenShift [Change Propagation](../installation/#change-propagation)
+
+## OpenShift template to Helm
+
+Migrating _NotifyBC_ on OpenShift created from OpenShift template to Helm involves 2 steps
+
+1. [Customize and Install Helm chart](#customize-and-install-helm-chart)
+2. [Migrate MongoDB data](#migrate-mongodb-data)
+
+### Customize and install Helm chart
+
+Follow [customizations](../installation/#customizations) to create file _helm/values.local.yaml_ containing customized configs such as
+
+- _notify-bc_ configMap
+- web route host name and certificates
+
+Then run `helm install` with documented arguments to install a release.
+
+### Migrate MongoDB data
+
+To backup data from source
+
+```sh
+oc exec -i <mongodb-pod> -- bash -c 'mongodump -u "$MONGODB_USER" \
+-p "$MONGODB_PASSWORD" -d $MONGODB_DATABASE --gzip --archive' > notify-bc.gz
+```
+
+replace \<mongodb-pod\> with the mongodb pod name.
+
+To restore backup to target
+
+```sh
+cat notify-bc.gz | oc exec -i <mongodb-pod-0> -- \
+bash -c 'mongorestore -u "$MONGODB_USERNAME" -p"$MONGODB_PASSWORD" \
+--uri="mongodb://$K8S_SERVICE_NAME" --db $MONGODB_DATABASE --gzip --drop --archive'
+```
+
+replace \<mongodb-pod-0\> with the first pod name in the mongodb stateful set.
+
+If both source and target are in the same OpenShift cluster, the two operations can be
+combined into one
+
+```sh
+oc exec -i <mongodb-pod> -- bash -c 'mongodump -u "$MONGODB_USER" \
+-p "$MONGODB_PASSWORD" -d $MONGODB_DATABASE --gzip --archive' | \
+oc exec -i <mongodb-pod-0> -- bash -c \
+'mongorestore -u "$MONGODB_USERNAME" -p"$MONGODB_PASSWORD" \
+--uri="mongodb://$K8S_SERVICE_NAME" --db $MONGODB_DATABASE --gzip --drop --archive'
+```

helm/Chart.yaml

@@ -22,7 +22,7 @@ version: 0.2.0
 # incremented each time you make changes to the application. Versions are not expected to
 # follow Semantic Versioning. They should reflect the version the application is using.
 # It is recommended to use it with quotes.
-appVersion: 2.5
+appVersion: 2.6
 
 dependencies:
   - name: mongodb

package.json

@@ -1,6 +1,6 @@
 {
   "name": "notify-bc",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "dbSchemaVersion": "0.8.0",
   "description": "A versatile notification API server",
   "keywords": [