From db478352bf9b3485f7a298f79d1c212e78fb1ca6 Mon Sep 17 00:00:00 2001 From: f-w Date: Fri, 20 Dec 2024 11:00:10 -0800 Subject: [PATCH] updated docs --- docs/docs/config/overview.md | 3 +- docs/docs/config/queue.md | 16 +++++- docs/docs/getting-started/installation.md | 63 ++++++++++++++-------- docs/docs/getting-started/quickstart.md | 2 +- docs/docs/miscellaneous/developer-notes.md | 8 +-- docs/docs/miscellaneous/upgrade.md | 4 +- package-lock.json | 4 +- package.json | 2 +- 8 files changed, 69 insertions(+), 33 deletions(-) diff --git a/docs/docs/config/overview.md b/docs/docs/config/overview.md index 15b71f281..408d4ac57 100644 --- a/docs/docs/config/overview.md +++ b/docs/docs/config/overview.md @@ -6,7 +6,7 @@ prev: /docs/what's-new/ # Configuration Overview ::: tip Helm Chart Configurations -The document pages in this section cover _NoitfyBC_ app level configurations only. +The document pages in this section cover _NotifyBC_ app level configurations only. If your _NotifyBC_ is deployed to Kubernetes using Helm, you can also [customize](../getting-started/installation.md#customizations) infrastructure level configurations. ::: @@ -34,6 +34,7 @@ Following configs should be customized per installation In addition, if installing from source code - [Database](../config/database.md) +- [Queue](./queue.md) - [Internal HTTP Host](../config/internalHttpHost.md) Customizing other configs only if needed. diff --git a/docs/docs/config/queue.md b/docs/docs/config/queue.md index c5ff2a852..619cd1a7f 100644 --- a/docs/docs/config/queue.md +++ b/docs/docs/config/queue.md @@ -18,6 +18,20 @@ module.exports = { }; ``` -To override the defaults, set the config in _src/config.local.js_. +To override the defaults, set the config in _src/config.local.js_. More connection parameters are documented in [ioredis](https://github.com/redis/ioredis). For example, to use Sentinel, + +```js +module.exports = { + // ... + queue: { + connection: { + sentinels: [{ host: process.env.REDIS_SERVICE_NAME }], + name: 'mymaster', + password: process.env.REDIS_PASSWORD, + sentinelPassword: process.env.REDIS_PASSWORD, + }, + }, +}; +``` If you deployed _NotifyBC_ using Helm chart, this config is taken care of. diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.md index 93e1d8cb6..69aca9efe 100644 --- a/docs/docs/getting-started/installation.md +++ b/docs/docs/getting-started/installation.md @@ -13,7 +13,7 @@ _NotifyBC_ can be installed in 3 ways: For the purpose of evaluation, both source code and docker container will do. For production, the recommendation is one of - deploying to Kubernetes -- setting up a load balanced app cluster from source code build, backed by MongoDB. +- setting up a load balanced app cluster from source code build; install MongoDB replica set and Redis with Sentinel separately To setup a development environment in order to contribute to _NotifyBC_, installing from source code is preferred. @@ -26,18 +26,21 @@ installing from source code is preferred. - Git - [Node.js](https://nodejs.org)@{{themeData.packageJson.engines.node}} - openssl (if enable HTTPS) + - Docker Desktop on Windows only and for evaluation only - Services - MongoDB with replica set, required for production + - Redis, required for production - A standard SMTP server to deliver outgoing email, required for production if email is enabled. - A tcp proxy server such as [nginx stream proxy](http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html) if list-unsubscribe by email is needed and _NotifyBC_ server cannot expose port 25 to internet - A SMS service provider if needs to enable SMS channel. The supported service providers are - Twilio (default) - Swift - - Redis - SiteMinder, if needs SiteMinder authentication - An OIDC provider, if needs OIDC authentication - Network and Permissions - Minimum runtime firewall requirements: + - outbound to MongoDB if you use a hosted service + - outbound to Redis if you use a hosted service - outbound to your ISP DNS server - outbound to any on port 80 and 443 in order to run build scripts and send SMS messages - outbound to any on SMTP port 25 if using direct mail; for SMTP relay, outbound to your configured SMTP server and port only @@ -49,28 +52,44 @@ installing from source code is preferred. ### Installation -Run following commands +Installation approach differs by your purpose + +- for evaluation, + + - internet connection is required + - Docker Desktop must be running if you localhost is Windows + - run following commands + ```sh + docker run --rm --pull always -dp 6379:6379 redis # only on Windows + git clone https://github.com/bcgov/NotifyBC.git + cd NotifyBC + npm i && npm run build + npx cross-env NOTIFYBC_WORKER_PROCESS_COUNT=1 npm run start + ``` + - wait till console displays `Server is running at http://0.0.0.0:3000/api` + - browse to http://localhost:3000 + +- for production, + + - install MongoDB with replica set or obtain a hosted service + - install Redis, preferably with Sentinel or obtain a hosted service + - follow [Database](../config/database.md) to setup connection to MongoDB + - follow [Queue](../config/queue.md) to setup connection to Redis + - follow [Configuration Overview](../config/overview.md) to customize other required configs + - run + ```sh + git clone https://github.com/bcgov/NotifyBC.git + cd NotifyBC + npm i && npm run build + npm run start + ``` + - wait till console displays `Server is running at http://0.0.0.0:3000/api` + - browse to http://localhost:3000 + +The above commands installs the _main_ version, i.e. main branch tip of _NotifyBC_ GitHub repository. To install a specific version, say _v6.0.2_, run ```sh -git clone https://github.com/bcgov/NotifyBC.git -cd NotifyBC -npm i && npm run build -npm run start -``` - -If successful, you will see following output - -``` -... -Server is running at http://0.0.0.0:3000 -``` - -Now open [http://localhost:3000](http://localhost:3000). The page displays NotifyBC Web Console. - -The above commands installs the _main_ version, i.e. main branch tip of _NotifyBC_ GitHub repository. To install a specific version, say _v2.1.0_, run - -```sh - git checkout tags/v2.1.0 -b v2.1.0 + git checkout tags/v6.0.2 -b v6.0.2 ``` after `cd NotifyBC`. A list of versions can be found [here](https://github.com/bcgov/NotifyBC/tags). diff --git a/docs/docs/getting-started/quickstart.md b/docs/docs/getting-started/quickstart.md index 2a4fdc490..a9b0f1aaf 100644 --- a/docs/docs/getting-started/quickstart.md +++ b/docs/docs/getting-started/quickstart.md @@ -19,7 +19,7 @@ git clone https://github.com/bcgov/NotifyBC.git cd NotifyBC npm i && npm run build npx cross-env NOTIFYBC_WORKER_PROCESS_COUNT=1 npm run start -# wait till console displays "ethereal email account created:" +# wait till console displays "Server is running at http://0.0.0.0:3000/api" # => Now browse to http://localhost:3000 ``` diff --git a/docs/docs/miscellaneous/developer-notes.md b/docs/docs/miscellaneous/developer-notes.md index 9565f748e..eec1ad1f5 100644 --- a/docs/docs/miscellaneous/developer-notes.md +++ b/docs/docs/miscellaneous/developer-notes.md @@ -51,6 +51,8 @@ You can now browse to the local docs site [http://localhost:8080/NotifyBC](http: ## Publish Version Checklist 1. update _version_ in _package.json_ -2. update _version_ _appVersion_ in _helm/Chart.yaml_ (major/minor only) -3. update [What's new](../getting-started/what's-new.md) (major/minor only) -4. create a new Github release +2. run `npm i` +3. globally find and replace older version number referenced in _docs_ folder +4. update _version_ _appVersion_ in _helm/Chart.yaml_ (major/minor only) +5. update [What's new](../getting-started/what's-new.md) (major/minor only) +6. create a new Github release diff --git a/docs/docs/miscellaneous/upgrade.md b/docs/docs/miscellaneous/upgrade.md index e12ce9723..7ffb3ad74 100644 --- a/docs/docs/miscellaneous/upgrade.md +++ b/docs/docs/miscellaneous/upgrade.md @@ -91,7 +91,7 @@ After above changes are addressed, to upgrade _NotifyBC_ to v6, Replace - - _v6.x.x_ with a v6 release, preferably latest, found in GitHub such as _v6.0.1_. + - _v6.x.x_ with a v6 release, preferably latest, found in GitHub such as _v6.0.2_. - if _NotifyBC_ is deployed to Kubernetes using Helm, 1. backup MongoDB database @@ -102,7 +102,7 @@ After above changes are addressed, to upgrade _NotifyBC_ to v6, helm upgrade -f helm/platform-specific/.yaml -f helm/values.local.yaml helm ``` Replace - - _v6.x.x_ with a v6 release, preferably latest, found in GitHub such as _v6.0.1_. + - _v6.x.x_ with a v6 release, preferably latest, found in GitHub such as _v6.0.2_. - \ with installed helm release name - \ with _openshift_ or _aks_ depending on your platform diff --git a/package-lock.json b/package-lock.json index 9ad840def..26a5d9925 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "notify-bc", - "version": "6.0.1", + "version": "6.0.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "notify-bc", - "version": "6.0.1", + "version": "6.0.2", "hasInstallScript": true, "license": "Apache-2.0", "dependencies": { diff --git a/package.json b/package.json index c5203a664..c506471b3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "notify-bc", - "version": "6.0.1", + "version": "6.0.2", "dbSchemaVersion": "0.9.0", "description": "A versatile notification API server", "author": "f-w",