From 1885b04550242162552db750bc37a7ed41892c62 Mon Sep 17 00:00:00 2001 From: Jeremy Ho Date: Thu, 14 Apr 2022 15:26:38 -0700 Subject: [PATCH 1/8] Update general environment variable table documentation Signed-off-by: Jeremy Ho --- README.md | 2 +- SECURITY.md | 2 +- app/README.md | 65 +++++++++++++++++++++++++++++---------------------- 3 files changed, 39 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 9c163151..e3b30c3d 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ To learn more about the **Common Services** available visit the [Common Services .github/ - PR and Issue templates app/ - Application Root - |── src/ - Node.js web application + ├── src/ - Node.js web application │ ├── components/ - Components Layer │ ├── controllers/ - Controller Layer │ ├── db/ - Database Layer diff --git a/SECURITY.md b/SECURITY.md index 7bd848ef..692ad327 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -15,7 +15,7 @@ At this time, only the latest version of Common Object Management Service is sup | Version | Supported | | ------- | ------------------ | | 0.1.0 | :white_check_mark: | -| < 0.1 | :x: | +| < 0.1.x | :x: | ## Reporting a Bug diff --git a/app/README.md b/app/README.md index cca014a7..aef76a2b 100644 --- a/app/README.md +++ b/app/README.md @@ -32,55 +32,61 @@ To learn more about the **Common Services** available visit the [Common Services This API is defined and described in OpenAPI 3.0 specification. -When the API is running, you should be able to view the specification through ReDoc at (assuming you are running this microservice locally). The specification source file is [here](https://github.com/bcgov/common-object-management-service/blob/master/app/src/docs/v1.api-spec.yaml) +When the API is running, you should be able to view the specification through ReDoc at (assuming you are running this microservice locally). The specification source file can be found [here](src/docs/v1.api-spec.yaml) ## Environment Variables -NOTE: See our [wiki](https://github.com/bcgov/common-object-management-service/wiki/Deployment-Guide#authentication-modes) for a description of the different **Authentication Modes**. +COMS supports a large array of environment variables to configure how it will behave. Depending on which sections below are enabled, you will have certain subsets of functionality available. Visit our wiki documentation on [Authentication modes](https://github.com/bcgov/common-object-management-service/wiki/Deployment-Guide#authentication-modes) for more details on the impacts of enabling each section. ### Basic Auth Variables -The following variables configure the use of Basic Auth authentication of requests to COMS +The following variables enable and enforce the use of Basic Authentication for requests to COMS | Config Var | Env Var | Default | Notes | | --- | --- | --- | --- | -| `enabled` | `BASICAUTH_ENABLED` | undefined | Whether to run COMS in Basic Auth mode | -| `username` | `BASICAUTH_USERNAME` | undefined | An arbitrary Username provided in a Basic Auth header of requests from your COMS client application | -| `password` | `BASICAUTH_PASSWORD` | undefined | An arbitrary Password provided in a Basic Auth header of requests from your COMS client application | +| `enabled` | `BASICAUTH_ENABLED` | | Whether to run COMS in Basic Auth mode | +| `username` | `BASICAUTH_USERNAME` | | An arbitrary Username provided in a Basic Auth header of requests from your COMS client application | +| `password` | `BASICAUTH_PASSWORD` | | An arbitrary Password provided in a Basic Auth header of requests from your COMS client application | -### Keycloak Variables +### Database Variables + +The following variables enable and configure the use of a backend database to support user-based access control, tagging and other advanced features | Config Var | Env Var | Default | Notes | | --- | --- | --- | --- | -| `clientId` | `KC_CLIENTID` | coms | Keycloak service client ID for COMS | -| `clientSecret` | `KC_CLIENTSECRET` | undefined | Keycloak service client secret | -| `identityKey` | `KC_IDENTITYKEY` | undefined | The key in the JWT object for verifying a user's identity instead of the standard jwt.sub | -| `enabled` | `KC_ENABLED` | undefined | Whether to run COMS in OIDC mode, required for user-based access controls and integration with OIDC users | -| `publicKey` | `KC_PUBLICKEY` | undefined | If specified, verify all incoming JWT signatures off of the provided public key | -| `realm` | `KC_REALM` | undefined | Keycloak realm ID for COMS | -| `serverUrl` | `KC_SERVERURL` | undefined | Keycloak server url for COMS authentication | +| `enabled` | `DB_ENABLED` | | Whether to use a database, rquired for OIDC Auth Mode as well as user-based access control, tagging and advanced features | +| `database` | `DB_DATABASE` | coms | COMS database name | +| `host` | `DB_HOST` | localhost | Database conection hostname | +| `username` | `DB_USERNAME` | app | Database account username | +| `password` | `DB_PASSWORD` | | Database account password | +| `port` | `DB_PORT` | 5432 | Database connection port | -### Database Variables +### Keycloak Variables + +The following variables enable and enforce the use of OIDC Bearer Authentication for requests to COMS | Config Var | Env Var | Default | Notes | | --- | --- | --- | --- | -| `database` | `DB_DATABASE` | coms | COMS database name | -| `enabled` | `DB_ENABLED` | undefined | Whether to use a database, rquired for OIDC Auth Mode as well as user-based access control, tagging and advanced features. | -| `host` | `DB_HOST` | localhost | The hostname of the COMS database, | -| `username` | `DB_USERNAME` | app | Database account username | -| `password` | `DB_PASSWORD` | undefined | Database account password | -| `port` | `DB_PORT` | `5432` | The port that COMS database will bind to | +| `enabled` | `KC_ENABLED` | | Whether to run COMS in OIDC mode, required for user-based access controls and integration with OIDC users | +| `clientId` | `KC_CLIENTID` | | Keycloak service client ID for COMS | +| `clientSecret` | `KC_CLIENTSECRET` | | Keycloak service client secret | +| `identityKey` | `KC_IDENTITYKEY` | | Specify using alternative JWT claims for user identification instead of the standard jwt.sub. Multiple claim attributes may be specified via a comma-separated list. COMS will attempt to search for the custom claim ordered based on how it is specified in this variable before falling back to jwt.sub if none are found. | +| `publicKey` | `KC_PUBLICKEY` | | If specified, verify all incoming JWT signatures off of the provided public key | +| `realm` | `KC_REALM` | | Keycloak realm ID for COMS | +| `serverUrl` | `KC_SERVERURL` | | Keycloak server url for COMS authentication | ### Object Storage Variables +The following variables enable and enforce the use of OIDC Bearer Authentication for requests to COMS + | Config Var | Env Var | Default | Notes | | --- | --- | --- | --- | -| `accessKeyId` | `OBJECTSTORAGE_ACCESSKEYID` | undefined | The Access Key for your S3 compatible object storage account | -| `bucket` | `OBJECTSTORAGE_BUCKET` | undefined | The object storage bucket name. | -| `defaultTempExpiresIn` | `OBJECTSTORAGE_TEMP_EXPIRESIN` | `300` | The expiry time for pre-signed URLs to objects in miliseconds. | -| `endpoint` | `OBJECTSTORAGE_ENDPOINT` | undefined | Object store URL. eg: `https://nrs.objectstore.gov.bc.ca` | -| `key` | `OBJECTSTORAGE_KEY` | undefined | The base path for storage location | -| `secretAccessKey` | `OBJECTSTORAGE_SECRETACCESSKEY` | undefined | The Secret Access Key for your S3 compatible object storage account | +| `accessKeyId` | `OBJECTSTORAGE_ACCESSKEYID` | | The Access Key for your S3 compatible object storage account | +| `bucket` | `OBJECTSTORAGE_BUCKET` | | The object storage bucket name | +| `defaultTempExpiresIn` | `OBJECTSTORAGE_TEMP_EXPIRESIN` | 300 | The expiry time for pre-signed URLs to objects in seconds | +| `endpoint` | `OBJECTSTORAGE_ENDPOINT` | | Object store URL. eg: `https://nrs.objectstore.gov.bc.ca` | +| `key` | `OBJECTSTORAGE_KEY` | | The base path for storage location | +| `secretAccessKey` | `OBJECTSTORAGE_SECRETACCESSKEY` | | The Secret Access Key for your S3 compatible object storage account | ### Server Variables @@ -88,7 +94,10 @@ The following variables alter the general Express application behavior. For most | Config Var | Env Var | Default | Notes | | --- | --- | --- | --- | -| `port` | `SERVER_PORT` | `3000` | The port that COMS application will bind to | +| `bodyLimit` | `SERVER_BODYLIMIT` | 30mb | Maximum body size accepted for parsing to JSON body | +| `logFile` | `SERVER_LOGFILE` | | Writes logs to the following file only if defined | +| `logLevel` | `SERVER_LOGLEVEL` | http | The logging level of COMS | +| `port` | `SERVER_PORT` | 3000 | The port that COMS application will bind to | ## Quick Start From 3500ead5bc82e53686155d578f22e222fd16c251 Mon Sep 17 00:00:00 2001 From: Jeremy Ho Date: Thu, 14 Apr 2022 15:27:41 -0700 Subject: [PATCH 2/8] Move enabled to top of each config section Since most of our logic is pinned on enabled existing or not, having that attribute show up first makes the most sense. Signed-off-by: Jeremy Ho --- app/config/custom-environment-variables.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/config/custom-environment-variables.json b/app/config/custom-environment-variables.json index 09f9820e..8b5b4cb1 100644 --- a/app/config/custom-environment-variables.json +++ b/app/config/custom-environment-variables.json @@ -5,18 +5,18 @@ "password": "BASICAUTH_PASSWORD" }, "db": { - "database": "DB_DATABASE", "enabled": "DB_ENABLED", + "database": "DB_DATABASE", "host": "DB_HOST", "username": "DB_USERNAME", "password": "DB_PASSWORD", "port": "DB_PORT" }, "keycloak": { + "enabled": "KC_ENABLED", "clientId": "KC_CLIENTID", "clientSecret": "KC_CLIENTSECRET", "identityKey": "KC_IDENTITYKEY", - "enabled": "KC_ENABLED", "publicKey": "KC_PUBLICKEY", "realm": "KC_REALM", "serverUrl": "KC_SERVERURL" From ae4b9d1c7294c3980929ac92c14c0b563a4f9d9d Mon Sep 17 00:00:00 2001 From: Jeremy Ho Date: Thu, 14 Apr 2022 15:51:23 -0700 Subject: [PATCH 3/8] Add note to run database migration first before running application Signed-off-by: Jeremy Ho --- app/README.md | 137 ++++++++++++++++++++++++-------------------------- 1 file changed, 67 insertions(+), 70 deletions(-) diff --git a/app/README.md b/app/README.md index aef76a2b..f79081e9 100644 --- a/app/README.md +++ b/app/README.md @@ -19,8 +19,8 @@ To learn more about the **Common Services** available visit the [Common Services - [OpenAPI Specification](#openapi-specification) - [Environment Variables](#environment-variables) - [Basic Auth Variables](#basic-auth-variables) - - [Keycloak Variables](#keycloak-variables) - [Database Variables](#database-variables) + - [Keycloak Variables](#keycloak-variables) - [Object Storage Variables](#object-storage-variables) - [Server Variables](#server-variables) - [Quick Start](#quick-start) @@ -101,90 +101,90 @@ The following variables alter the general Express application behavior. For most ## Quick Start -The following sections provide you a quick way to get COMS set up and running. +The following sections provide you a quick way to get COMS set up and running either through Docker or directly as a node application. ### Docker This section assumes you have a recent version of Docker available to work with on your environment. Make sure to have an understanding of what environment variables are passed into the application before proceeding. -Note: change latest tag to specific version if needed. Avoid using the latest tag in Production to ensure consistency with your existing infrastructure. +Note: change the `latest` tag to specific version if needed. Avoid using the latest tag in Production to ensure consistency with your existing infrastructure. Get COMS image: -```sh -docker pull bcgovimages/common-object-management-service:latest +``` sh +docker pull docker.io/bcgovimages/common-object-management-service:latest ``` -Run COMS in **Unauthenticated mode** +Run COMS in **Unauthenticated mode** (replace environment values as necessary) -```sh +``` sh docker run -it --rm -p 3000:3000 \ --e OBJECTSTORAGE_ACCESSKEYID= \ --e OBJECTSTORAGE_BUCKET= \ --e OBJECTSTORAGE_ENDPOINT= \ --e OBJECTSTORAGE_KEY= \ --e OBJECTSTORAGE_SECRETACCESSKEY= \ -docker.io/bcgovimages/common-object-management-service:latest + -e OBJECTSTORAGE_ACCESSKEYID= \ + -e OBJECTSTORAGE_BUCKET= \ + -e OBJECTSTORAGE_ENDPOINT= \ + -e OBJECTSTORAGE_KEY= \ + -e OBJECTSTORAGE_SECRETACCESSKEY= \ + docker.io/bcgovimages/common-object-management-service:latest ``` Run COMS in **Basic Auth mode** (replace environment values as necessary) -```sh +``` sh docker run -it --rm -p 3000:3000 \ --e OBJECTSTORAGE_ACCESSKEYID= \ --e OBJECTSTORAGE_BUCKET= \ --e OBJECTSTORAGE_ENDPOINT= \ --e OBJECTSTORAGE_KEY= \ --e OBJECTSTORAGE_SECRETACCESSKEY= \ --e BASICAUTH_USERNAME= \ --e BASICAUTH_PASSWORD= \ --e BASICAUTH_ENABLED=true \ -docker.io/bcgovimages/common-object-management-service:latest + -e OBJECTSTORAGE_ACCESSKEYID= \ + -e OBJECTSTORAGE_BUCKET= \ + -e OBJECTSTORAGE_ENDPOINT= \ + -e OBJECTSTORAGE_KEY= \ + -e OBJECTSTORAGE_SECRETACCESSKEY= \ + -e BASICAUTH_ENABLED=true \ + -e BASICAUTH_USERNAME= \ + -e BASICAUTH_PASSWORD= \ + docker.io/bcgovimages/common-object-management-service:latest ``` Run COMS in **OIDC Auth Mode** (replace environment values as necessary) -```sh +``` sh docker run -it --rm -p 3000:3000 \ --e OBJECTSTORAGE_ACCESSKEYID= \ --e OBJECTSTORAGE_BUCKET= \ --e OBJECTSTORAGE_ENDPOINT= \ --e OBJECTSTORAGE_KEY= \ --e OBJECTSTORAGE_SECRETACCESSKEY= \ --e KC_CLIENTID= \ --e KC_CLIENTSECRET= \ --e KC_ENABLED=true \ --e KC_PUBLICKEY= \ --e KC_REALM= \ --e KC_SERVERURL= \ --e DB_ENABLED=true \ --e DB_PASSWORD= \ --e DB_PORT= \ -docker.io/bcgovimages/common-object-management-service:latest + -e OBJECTSTORAGE_ACCESSKEYID= \ + -e OBJECTSTORAGE_BUCKET= \ + -e OBJECTSTORAGE_ENDPOINT= \ + -e OBJECTSTORAGE_KEY= \ + -e OBJECTSTORAGE_SECRETACCESSKEY= \ + -e KC_ENABLED=true \ + -e KC_CLIENTID= \ + -e KC_CLIENTSECRET= \ + -e KC_PUBLICKEY= \ + -e KC_REALM= \ + -e KC_SERVERURL= \ + -e DB_ENABLED=true \ + -e DB_PASSWORD= \ + -e DB_PORT= \ + docker.io/bcgovimages/common-object-management-service:latest ``` Run COMS in **Full Auth Mode** (replace environment values as necessary) -```sh +``` sh docker run -it --rm -p 3000:3000 \ --e OBJECTSTORAGE_ACCESSKEYID= \ --e OBJECTSTORAGE_BUCKET= \ --e OBJECTSTORAGE_ENDPOINT= \ --e OBJECTSTORAGE_KEY= \ --e OBJECTSTORAGE_SECRETACCESSKEY= \ --e BASICAUTH_USERNAME= \ --e BASICAUTH_PASSWORD= \ --e BASICAUTH_ENABLED=true \ --e KC_CLIENTID= \ --e KC_CLIENTSECRET= \ --e KC_ENABLED=true \ --e KC_PUBLICKEY= \ --e KC_REALM= \ --e KC_SERVERURL= \ --e DB_ENABLED=true \ --e DB_PASSWORD= \ --e DB_PORT= \ -docker.io/bcgovimages/common-object-management-service:latest + -e OBJECTSTORAGE_ACCESSKEYID= \ + -e OBJECTSTORAGE_BUCKET= \ + -e OBJECTSTORAGE_ENDPOINT= \ + -e OBJECTSTORAGE_KEY= \ + -e OBJECTSTORAGE_SECRETACCESSKEY= \ + -e BASICAUTH_ENABLED=true \ + -e BASICAUTH_USERNAME= \ + -e BASICAUTH_PASSWORD= \ + -e KC_ENABLED=true \ + -e KC_CLIENTID= \ + -e KC_CLIENTSECRET= \ + -e KC_PUBLICKEY= \ + -e KC_REALM= \ + -e KC_SERVERURL= \ + -e DB_ENABLED=true \ + -e DB_PASSWORD= \ + -e DB_PORT= \ + docker.io/bcgovimages/common-object-management-service:latest ``` ### Local Machine @@ -195,12 +195,10 @@ This section assumes you have a recent version of Node.js (12.x or higher) insta Configuration management is done using the [config](https://www.npmjs.com/package/config) library. There are two ways to configure: -1. Look at [custom-environment-variables.json](/app/config/custom-environment-variables.json) and ensure you have the environment variables locally set. Create a `local.json` file in the config folder. This file should never be added to source control. Consider creating a `local-test.json` file in the config folder if you want to use different configurations while running unit tests. -2. Look at [custom-environment-variables.json](/app/config/custom-environment-variables.json) and use explicit environment variables in your environment as mentioned [above](#environment-variables) to configure your application behavior. +1. Configure via `local.json` file. Look at [custom-environment-variables.json](/app/config/custom-environment-variables.json) and ensure you have the environment variables locally set. Create a `local.json` file in the config folder. This file should never be added to source control. Consider creating a `local-test.json` file in the config folder if you want to use different configurations while running unit tests. +2. Configure via environment variables. Look at [custom-environment-variables.json](/app/config/custom-environment-variables.json) and use the explicit environment variables in your environment as mentioned [above](#environment-variables) to configure your application behavior. -For more details, please consult the config library [documentation](https://github.com/lorenwest/node-config/wiki/Configuration-Files). - -If you are running this on a local machine, you will need to create a `local.json` file in the `config` directory containing the values you want set. For more information on how the config library loads and searches for environment variables, take a look at this article: . +For more information on how the config library loads and searches for environment variables, take a look [here](https://github.com/lorenwest/node-config/wiki/Configuration-Files). At a minimum (when running COMS in 'Unauthenticated mode'), you are required to have configuration values for your Object Storage. To run COMS in Full Auth mode you will want your `local.json` to have the following values defined, with your own values as needed: @@ -236,12 +234,11 @@ To run COMS in Full Auth mode you will want your `local.json` to have the follow "port": "" } } - ``` #### Common Commands -Install node dependencies with either `npm ci` or `npm install`. +Install node dependencies with `npm ci`. You may use `npm install` if you are updating or changing the dependencies instead. Once your application is configured, make sure to run a database migration before starting up the COMS application. Run the server with hot-reloading for development @@ -249,7 +246,7 @@ Run the server with hot-reloading for development npm run serve ``` -Run the server without hot-reloading +Run the server ``` sh npm run start @@ -261,16 +258,16 @@ Migrate Database npm run migrate ``` -Run your tests +Lint the codebase ``` sh -npm run test +npm run lint ``` -Lint the codebase +Run your tests ``` sh -npm run lint +npm run test ``` ## License From 9da9d74f3ee1459ff89f1eea60ba6b289bfcad3d Mon Sep 17 00:00:00 2001 From: Jeremy Ho Date: Thu, 14 Apr 2022 15:53:58 -0700 Subject: [PATCH 4/8] Change repomountie lifecycle to Maturing With the imminent release of v0.1.0 MVP, COMS is starting to converge to a more stable state. The core shapes of the COMS API is in place, and future features will be extensions of the existing API. Signed-off-by: Jeremy Ho --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e3b30c3d..b8c6bfad 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Common Object Management Service -[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) [![Lifecycle:Experimental](https://img.shields.io/badge/Lifecycle-Experimental-339999)](https://github.com/bcgov/repomountie/blob/master/doc/lifecycle-badges.md) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) [![Lifecycle:Maturing](https://img.shields.io/badge/Lifecycle-Maturing-007EC6)](https://github.com/bcgov/repomountie/blob/master/doc/lifecycle-badges.md) ![Tests](https://github.com/bcgov/common-object-management-service/workflows/Tests/badge.svg) [![Maintainability](https://api.codeclimate.com/v1/badges/91d2b0aebc348a1d5d0a/maintainability)](https://codeclimate.com/github/bcgov/common-object-management-service/maintainability) From 32a636579a7ed42928f07347f80aebe62213b1d9 Mon Sep 17 00:00:00 2001 From: Jeremy Ho Date: Mon, 18 Apr 2022 17:20:23 -0700 Subject: [PATCH 5/8] Update OpenAPI section external links to wiki subsections Signed-off-by: Jeremy Ho --- app/src/docs/v1.api-spec.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/app/src/docs/v1.api-spec.yaml b/app/src/docs/v1.api-spec.yaml index cdcb8ec7..ef5671e2 100644 --- a/app/src/docs/v1.api-spec.yaml +++ b/app/src/docs/v1.api-spec.yaml @@ -23,19 +23,19 @@ tags: Operations directly influencing an S3 Object. Certain operations not available without a database. externalDocs: - url: https://github.com/bcgov/common-object-management-service/wiki + url: https://github.com/bcgov/common-object-management-service/wiki/Endpoint-Notes#object - name: Permission description: >- Operations for managing User Access Control to S3 Objects. Not available without a database. externalDocs: - url: https://github.com/bcgov/common-object-management-service/wiki + url: https://github.com/bcgov/common-object-management-service/wiki/Endpoint-Notes#permission - name: User description: >- Operations to list valid queryable users and identity providers. Not available without a database. externalDocs: - url: https://github.com/bcgov/common-object-management-service/wiki + url: https://github.com/bcgov/common-object-management-service/wiki/Endpoint-Notes#user paths: /object: post: From 6d186ee4489166cc4a3dacf603dd74faed8de0b3 Mon Sep 17 00:00:00 2001 From: Jeremy Ho Date: Tue, 19 Apr 2022 11:20:40 -0700 Subject: [PATCH 6/8] Standardize text blob formatting on main readme Signed-off-by: Jeremy Ho --- README.md | 59 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 32 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index b8c6bfad..064cb598 100644 --- a/README.md +++ b/README.md @@ -17,28 +17,31 @@ To learn more about the **Common Services** available visit the [Common Services ## Directory Structure - .github/ - PR and Issue templates - app/ - Application Root - ├── src/ - Node.js web application - │ ├── components/ - Components Layer - │ ├── controllers/ - Controller Layer - │ ├── db/ - Database Layer - │ ├── docs/ - OpenAPI 3.0 Specification - │ ├── middleware/ - Middleware Layer - │ ├── routes/ - API Route Layer - │ └── services/ - Services Layer - └── tests/ - Node.js web application tests - openshift/ - OpenShift-deployment and shared pipeline files - CODE-OF-CONDUCT.md - Code of Conduct - COMPLIANCE.yaml - BCGov PIA/STRA compliance status - CONTRIBUTING.md - Contributing Guidelines - LICENSE - License - SECURITY.md - Security Policy and Reporting +```txt +.github/ - PR and Issue templates +app/ - Application Root +├── src/ - Node.js web application +│ ├── components/ - Components Layer +│ ├── controllers/ - Controller Layer +│ ├── db/ - Database Layer +│ ├── docs/ - OpenAPI 3.0 Specification +│ ├── middleware/ - Middleware Layer +│ ├── routes/ - API Route Layer +│ └── services/ - Services Layer +└── tests/ - Node.js web application tests +openshift/ - OpenShift-deployment and shared pipeline files +CODE-OF-CONDUCT.md - Code of Conduct +COMPLIANCE.yaml - BCGov PIA/STRA compliance status +CONTRIBUTING.md - Contributing Guidelines +LICENSE - License +SECURITY.md - Security Policy and Reporting +``` ## Documentation * [Application Readme](app/README.md) * [API Specification](app/README.md#openapi-specification) +* [COMS Wiki](https://github.com/bcgov/common-object-management-service/wiki) * [Openshift Readme](openshift/README.md) * [Security Reporting](SECURITY.md) * [Showcase Team Roadmap](https://github.com/bcgov/nr-get-token/wiki/Product-Roadmap) @@ -55,16 +58,18 @@ Please note that this project is released with a [Contributor Code of Conduct](C ## License - Copyright 2022 Province of British Columbia +```txt +Copyright 2022 Province of British Columbia - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 + http://www.apache.org/licenses/LICENSE-2.0 - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +``` From 0f13a3091073721d37f097fbe9c2e721e9b2e357 Mon Sep 17 00:00:00 2001 From: Jeremy Ho Date: Tue, 19 Apr 2022 11:21:45 -0700 Subject: [PATCH 7/8] Add warning notes to openshift template readme We do not have this deployed on openshift yet, so these readme notes are not tested and updated accordingly yet. Signed-off-by: Jeremy Ho --- openshift/README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/openshift/README.md b/openshift/README.md index 964625ce..a083d0ed 100644 --- a/openshift/README.md +++ b/openshift/README.md @@ -1,5 +1,7 @@ # Application on Openshift +*Note: These instructions are a stub from vue-scaffold; they have not yet been updated specifically for COMS deployment yet!* + This application is deployed on Openshift. This readme will outline how to setup and configure an Openshift project to get the application to a deployable state. This document assumes a working knowledge of Kubernetes/Openshift container orchestration concepts (i.e. buildconfigs, deployconfigs, imagestreams, secrets, configmaps, routes, networksecuritypolicies, etc) Our builds and deployments are orchestrated with Jenkins. Refer to [Jenkinsfile](../Jenkinsfile) and [Jenkinsfile.cicd](../Jenkinsfile.cicd) to see how the Openshift templates are used for building and deploying in our CI/CD pipeline. @@ -14,6 +16,8 @@ Our builds and deployments are orchestrated with Jenkins. Refer to [Jenkinsfile] ## Environment Setup - ConfigMaps and Secrets +*Note: These instructions are a stub from vue-scaffold; they have not yet been updated specifically for COMS deployment yet!* + There are some requirements in the target Openshift namespace/project which are **outside** of the CI/CD pipeline process. This application requires that a few Secrets as well as Config Maps are already present in the environment before it is able to function as intended. Otherwise the Jenkins pipeline will fail the deployment by design. In order to prepare an environment, you will need to ensure that all of the following configmaps and secrets are populated. This is achieved by executing the following commands as a project administrator of the targeted environment. Note that this must be repeated on *each* of the target deployment namespace/projects (i.e. `dev`, `test` and `prod`) as that they are independent of each other. Deployments will fail otherwise. Refer to [custom-environment-variables](../app/config/custom-environment-variables.json) for the direct mapping of environment variables to the app. @@ -78,6 +82,8 @@ oc create -n $NAMESPACE secret generic $APP_NAME-sc-cs-secret \ ## Build Config & Deployment +*Note: These instructions are a stub from vue-scaffold; they have not yet been updated specifically for COMS deployment yet!* + This application is currently designed as a single application pod deployments. It will host a static frontend containing all of the Vue.js resources and assets, and a Node.js backend which serves the API that the frontend requires. We are currently leveraging Openshift Routes with path based filtering in order to forward incoming traffic to the right deployment service. ### Frontend @@ -90,6 +96,8 @@ The backend is a standard [Node](https://nodejs.org)/[Express](https://expressjs ## Templates +*Note: These instructions are a stub from vue-scaffold; they have not yet been updated specifically for COMS deployment yet!* + The Jenkins pipeline heavily leverages Openshift Templates in order to ensure that all of the environment variables, settings, and contexts are pushed to Openshift correctly. Files ending with `.bc.yaml` specify the build configurations, while files ending with `.dc.yaml` specify the components required for deployment. ### Build Configurations @@ -160,6 +168,8 @@ oc rollout -n $NAMESPACE latest dc/-master ## Pull Request Cleanup +*Note: These instructions are a stub from vue-scaffold; they have not yet been updated specifically for COMS deployment yet!* + As of this time, we do not automatically clean up resources generated by a Pull Request once it has been accepted and merged in. This is still a manual process. Our PR deployments are all named in the format "pr-###", where the ### is the number of the specific PR. In order to clear all resources for a specific PR, run the following two commands to delete all relevant resources from the Openshift project (replacing `PRNUMBER` with the appropriate number): ```sh From e428c7da4ed402deab57b5a87f0dbe87d1b953d5 Mon Sep 17 00:00:00 2001 From: Jeremy Ho Date: Tue, 19 Apr 2022 11:30:45 -0700 Subject: [PATCH 8/8] Add github pages theme configuration Signed-off-by: Jeremy Ho --- _config.yml | 1 + 1 file changed, 1 insertion(+) create mode 100644 _config.yml diff --git a/_config.yml b/_config.yml new file mode 100644 index 00000000..277f1f2c --- /dev/null +++ b/_config.yml @@ -0,0 +1 @@ +theme: jekyll-theme-cayman