Development

This page is a suggestion for how to setup a local development environment for Katalogue.

Install the services in this order:

1. Repository Database
2. Backend Service
3. Frontend Service

Requirements

The following tools are required to set up a development environment locally on your computer (install in the specified order):

1. Git (source code management)
2. PostgreSQL (database)
3. Nodejs (backend environment)

Recommended IDEs for PostgreSQL are:

• pgAdmin (freeware, bundled with the PostgreSQL installation package above)
• DBeaver (open source, more potent but also more techy than pgAdmin)
• DataGrip (best, but requires a license)

Recommended IDEs to work with web development are:

• VSCode (free)
• Sublime Text (shareware, but has an unlimited testing period. Faster and more lightweight than VSCode)

Other:

• Postman (API-testing)
• Affinity Designer (Vector graphics tool used to create all icons, images and design templates for Katalogue. Requires license)

Repository Database (db)

1. Install and start a local PostgreSQL server.
2. Clone this git repository
3. Rename the /services/db/install.sh_script to install.sh (the suffix is provided to make the default PostgreSQL Docker image used with docker-compose skip this file)
4. Run the install.sh file from your terminal. This script creates roles used by Katalogue and a “katalogue” database with all objects required for Katalogue to run. You must specify the PostgreSQL hostname, admin user etc when running the command. Run install.sh --help to see how to use the install script and provide this information.

Backend Service (api)

This assumes that you run both the backend service and frontend service locally on the same computer.

1. Download GIT repo and go to the /services/api folder
2. Copy config/appsettings_default.json to config/appsettings.json and change config parameters according to you environment (see Configuration section below)
3. Open a terminal, go to the api-folder in the GIT repo and run npm install to install dependencies.
4. If you need the Oracle connector, install the Oracle Instant Client library.
5. Start the development app by running npm run-script dev in a terminal.

Configuration

Set these parameters in the config/appsettings.json file:

• 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 8080
• cookieHeaders.SAME_SITE. Set to boolean true.
• cookieHeaders.SECURE. Set to boolean false.
• API_ENDPOINT_BASE_URL. Full URL of the backend API app, example: http://localhost:8080.net
• CORS_ORIGIN. Array with URLs that are allowed to send requests to the API. Must at least contain the frontend app URL, example: http://localhost
• repository.. Connection credentials to the repository database. If not specified to something else when you ran the install.sh script for the repository database, these are the defaults:
  • REPOSITORY_HOSTNAME: localhost
  • REPOSITORY_PORT: 5432
  • REPOSITORY_DATABASE: katalogue
  • REPOSITORY_USERNAME: katalogue_superuser
  • REPOSITORY_PASSWORD: katalogue_superuser
  • REPOSITORY_USE_SSL: false
• connectors.oracle.INSTANT_CLIENT_PATH. Only required if you want to use the Oracle connector. If you do not need the Oracle connector, disable it by adding the config key connectors.oracle.ORACLE_IS_ENABLED: false. If you need Oracle, 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, but you probably do not want to taint your machine with these. If the Oracle driver cannot find the Instant Client library, the backend service will fail to start.

Frontend Service (spa)

1. Download GIT repo and go to the /services/spa folder
2. Copy src/appsettings_default.json to src/appsettings.json and change config parameters according to you environment (see below)
3. Check that the “proxy” parameter in package.json points to the correct URL/port where the backend API is running. This would normally be “http://localhost.8080”.
4. Open a terminal, go to the spa-folder in the GIT repo and run npm install to install dependencies.
5. Make sure the backend API is running.
6. Start the development server by running npm start in a terminal. A website should open automatically in your browser (normally http://localhost:3000), otherwise go to the url specified in appsettings.json.