Deployment Overview

Tested in Azure and in Redhat OpenShift. This section is intended as a high-level blueprint, there will probably be many organization-specific details to adhere to.

Backend Service (api)

Production

1. Setup and configure the PostgreSQL repository. This must be running to be able to start the backend api.
2. Download GIT repo and go to the /api folder
3. Copy config/appsettings_template.json to config/appsettings.json
4. Change config parameters according to you environment (see below)
5. Decide if you want to run the backend api in container mode or directly on a web server and continue in the appropriate section below

Container mode (Docker)

1. Perform all tasks in the Installation section above
2. Containerize the source code, either with a CI flow on e.g. Gitlab or locally on your computer. Example code to build and upload the docker image to a Gitlab container registry:
3. docker login registry.gitlab.com
4. docker build -t registry.gitlab.com/kayenta/katalogue/api .
5. docker push registry.gitlab.com/kayenta/katalogue/api
6. Deploy the docker image to e.g. Azure App Services. Here is a post on how to configure an Azure App Service to auto-fetch docker images from an external repository such as Gitlab: https://stackoverflow.com/questions/62042562/how-to-deploy-a-docker-container-to-azure-app-service-from-gitlab-container-regi

Webserver

1. Perform all tasks in the Installation section above
2. Open a terminal, go to the api-folder in the GIT repo and run npm install to install dependencies.
3. Upload everything in the /api folder to your webserver
4. Run node server.js to start the backend api

Configuration

This section covers the required config parameters in appsettings.json for the app to start.

• ENCRYPTION_KEY. Should be a long, random string that you keep safe. This is used to hash and encrypt passwords (local user account passwords and datasource connection passwords) in the Katalogue repository database. Currently, Katalogue does not support key rotation, meaning that this cannot be changed later if you already have encrypted data in the repository database
• PORT. In most cases 80
• cookieHeaders.SAME_SITE. “None” if backend API app and frontend app are hosted on different servers. Otherwise boolean true.
• cookieHeaders.SECURE. Boolean true if backend API app and frontend app are hosted on different servers. Otherwise boolean false.
• API_ENDPOINT_BASE_URL. Full URL of the backend API app, example: https://katalogue-demo-api.azurewebsites.net. This is used to verify the access- and refresh tokens to authenticate users.
• CORS_ORIGIN. Array with URLs that are allowed to send requests to the API. Must at least containt the frontend app URL, example: https://katalogue-demo.azurewebsites.net
• repository.*. Connection credentials to the repository database.
• connectors.oracle.INSTANT_CLIENT_PATH. If you are deploying the app as a Docker container and you use the provided Dockerfile, this can be left blank. Otherwise, this is a way to specify the path to the location where the Oracle Instant Client library is installed. Another way to do this is to specify Oracle environment variables. If the Oracle driver cannot find the Instant Client library, the backend API will fail to start.

Frontend Service (spa)

1. Download GIT repo and go to the /spa folder
2. Copy src/appsettings_default.json to src/appsettings.json
3. Change config parameters according to you environment (see below)
4. Decide if you want to run the frontend app in container mode or directly on a web server and continue in the appropriate section below

Container Mode (Docker)

1. Perform all tasks in the section above
2. Containerize the source code, either with a CI flow on e.g. Gitlab or locally on your computer. Example code to build and upload the docker image to a Gitlab container registry:
3. docker login registry.gitlab.com
4. docker build -t registry.gitlab.com/kayenta/katalogue/spa .
5. docker push registry.gitlab.com/kayenta/katalogue/spa
6. Deploy the docker image to e.g. Azure App Services. Here is a post on how to configure an Azure App Service to auto-fetch docker images from an external repository such as Gitlab: https://stackoverflow.com/questions/62042562/how-to-deploy-a-docker-container-to-azure-app-service-from-gitlab-container-regi

Webserver

1. Perform all tasks in the section above
2. Install dependencies by running npm install
3. Build the spa (React) app with npm run-script build
4. Upload everything in the /spa/build folder to your webserver
5. Configure the webserver to your needs