bcgovimages/common-document-generation-service repository overview

⁠Common Document Generation Service

CDOGS - A common hosted service (API) for generating documents from templates, data documents, and assets

To learn more about the Common Services available visit the Common Services Showcase⁠ page.

⁠Table of Contents

• OpenAPI Specification⁠
• Environment Variables⁠
  • Carbone Variables⁠
  • Keycloak Variables⁠
  • Server Variables⁠
• Quick Start⁠
  • Docker⁠
  • Local Machine⁠
• License⁠

⁠OpenAPI Specification

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 http://localhost:3000/api/v2/docs⁠ (assuming you are running this microservice locally).

The hosted CDOGS API can usually be found at https://cdogs.nrs.gov.bc.ca/api/v2/docs⁠.

For more details on using CDOGS and its underlying Carbone library, take a look at the Usage guide⁠.

⁠Environment Variables

CDOGS behavior is highly customizable through Environment Variables. The following will provide you with the main settings that you should be aware of. However, the complete list of supported variables can be found under /app/config/custom-environment-variables.json⁠. Reference the NPM Config⁠ library for more details on how configuration is cascaded and managed.

⁠Carbone Variables

The following variables alter the behavior of Carbone and its caching behavior.

⁠Keycloak Variables

The following variables alter CDOGS authentication behavior. By default, if KC_ENABLED is left unset/undefined, CDOGS will run in unauthenticated mode, ignoring the rest of the Keycloak environment variables. Should you want CDOGS to require authentication, you will need to set KC_ENABLED to true.

⁠Server Variables

The following variables alter the general Express application behavior. For most situations, the defaults should be sufficient.

⁠Quick Start

The following sections provide you a quick way to get CDOGS set up and running.

⁠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.

Get CDOGS image (change latest tag to specific version if needed):

docker pull bcgovimages/common-document-generation-service:latest

Run CDOGS in unauthenticated mode

docker run -it --rm -p 3000:3000 bcgovimages/common-document-generation-service:latest

Run CDOGS in Keycloak protected mode (replace environment values as necessary)

docker run -it --rm -p 3000:3000 -e KC_CLIENTID=<id> -e KC_CLIENTSECRET=<secret> -e KC_ENABLED=true -e KC_PUBLICKEY=<publickey> -e KC_REALM=<realm> -e KC_SERVERURL=<url> bcgovimages/common-document-generation-service:latest

For more dedicated deployments of CDOGS in a Docker environment, make sure to consider using persistent volumes for the cache directories.

⁠Local Machine

This section assumes you have a recent version of Node.js (12.x or higher) and LibreOffice™ (6.3.4.x or higher) installed. Make sure to have an understanding of what environment variables are passed into the application before proceeding.

⁠Configuration

Configuration management is done using the config⁠ library. There are two ways to configure:

1. Look at 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⁠ and use explicit environment variables in your environment as mentioned above⁠ to configure your application behavior.

For more details, please consult the config library documentation⁠.

⁠Common Commands

Install node dependencies with either npm ci or npm install.

Run the server with hot-reloading for development

npm run serve

Run the server without hot-reloading

npm run start

Run your tests

npm run test

Lint the codebase

npm run lint

⁠License

Copyright 2019 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

    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.