Dakota

This is a monorepo for Dakota Development. It contains the following packages:

• dakota-ui - Next.js frontend replacement of MRC - runs on http://localhost:2022
• validation-ui - Next.js frontend to support import validation - runs on http://localhost:3000
• dakota-service - Nest.js REST API - runs on http://localhost:1985
• @bfc-software/dakota-schema - (CommonJS) Open API schema definition for the Dakota API
• @bfc-software/infrastructure - (ESM) Infrastructure tooling for deploys, application retrieval for the IBM, etc

Table of Contents

• Dakota
  • Table of Contents
  • Workspace Level Commands
    • To Work on the MRC replacement app
    • To work on the Validation UI
  • Libraries
    • Local Development
    • Debugging
    • Publishing
    • Changelog
  • Environment Configuration
    • Setting up ODBC
    • Set up your DSN (datasource name)
  • Deployment
  • IBM Setup
    • Installing the bfc executable
      • First Install
      • Update to latest package version
    • Retrieve a release
    • Start the Frontend
    • Start the Backend

Workspace Level Commands

Start with "Environment Configuration" if this is your first time running Dakota.

Ensure the latest dependencies are installed:

npm install

To Work on the MRC replacement app

Then run the development servers:

npm run frontend

npm run backend

To work on the Validation UI

npm run validation-ui

Libraries

Local Development

The packages contained in the @bfc-software directory represent npm packages that are available in our private registry. The monorepo approach allows making local changes that can be tested in the consuming entities prior to official publish.

To incorporate changes you've made to a package in the @bfc-software directory:

1. Bump the version in the package.json for the package. Your version bump should represent the change type - see the semver website for further details on semantic versioning. In broad strokes the change types are

   • [major]: Represents a significant change to the package approach or architecture, may contain breaking changes.
   • [minor]: Represents the addition of a new feature or deliverable with no breaking changes.
   • [patch]: Represents a small change such as a bug fix or amendment with no breaking changes.

2. Build the package using npm run build to generate processed files for consumption.

3. Bump the version in the package.json for any consuming packages.

4. Run npm install at the root directory level to ensure the installation is picked up by all packages.

Debugging

Libraries make use of the debug library to provide feedback during the development process. Logs are enabled by default in the application dev process but you can enable them in the browser using the following method:

localStorage.debug = 'pallet'

Current Namespaces:

• pallet

Publishing

Packages that live under the @bfc-software directory get published on NPM using a tool called Lerna.

Private packages (which is all of our packages to date) will have an entry in their package.json that points to our private repository ensuring they get published correctly:

   // package.json
  "publishConfig": {
    "registry": "https://www.npmjs.com/package/@bfc-software"
  },

Start by running the following to authenticate with npm: npm login

Then run: npm run publish

Changelog

This repo uses Lerna to generate an automated changelog of all library changes. Each PR is validated using the validate-release-labels workflow to ensure a valid tag is added when a change is made to any of the files in the packages/@bfc-software directories.

If a change is present and a tag has not been added you will be asked to add one.

Tag types:

• breaking
• enhancement
• bug
• documentation
• internal

You can generate the changelog using:

npm run generate-changelog

Environment Configuration

Setting up ODBC

ODBC is the preferred method of connecting to Db2 on i.

You will need unixODBC as your ODBC driver manager. unixODBC is available on homebrew, and can be installed running the following command:

$ brew install unixodbc

Set up your DSN (datasource name)

ODBC uses a connection string with keywords to create a database connection. Because these strings can be cumbersome to maintain, a more ergonomic format called a DSN (datasource name) is available.

When using unixODBC, DSNs are defined in odbc.ini (available to all users) and .odbc.ini (user scoped). You can find the files using the following command:

$ odbcinst -j

Open ~/.odbc.ini in your preferred editor and add the following configuration for accessing DEV5:

[DEV5]
Description            = The IBM i System
Driver                 = IBM i Access ODBC Driver
System                 = 10.150.0.37

Deployment

When a pull request is merged to the main branch, the GitHub deploy workflow is triggered and production assets get pushed to S3. Each deploy creates a new object where the name is the Git SHA.

• Asset Bucket
• Github Actions User

IBM Setup

Installing the bfc executable

Use the Code for IBM i VSCode plugin to access the PASE shell (or whatever means you usually use).

First Install

Add the following to ~/.npmrc, replace AUTH_TOKEN with a token generated on www.npmjs.com that can read from our private registry:

N.B. This will overwrite the existing ~/.npmrc file.

cat <<EOL > ~/.npmrc
//registry.npmjs.org/:_authToken=AUTH_TOKEN
@bfc-software:registry=https://registry.npmjs.org/
EOL

Add the package for the executable:

npm install -g @bfc-software/infrastructure

Ensure it is present by running bfc without any args:

bfc

Update to latest package version

npm update -g @bfc-software/infrastructure

If the executable isn't immediately available run:

source ~/.profile

Retrieve a release

You can retrieve a release using:

bfc fetch-assets

This will prompt you for the AWS credentials and then present a series of Git SHAs. The SHA is logged during the build-and-deploy workflow in case there is any question.

Start the Frontend

cd down to the dakota-ui directory that was unpacked by bfc.

Run npm run start:prod.

It should start the app on http://localhost:2022.

Start the Backend

cd down to the dakota-service directory that was unpacked by bfc.

It should start the app on http://localhost:1985.