npm package: @mimik/local
Description: Local setup configuration for normal and test operation
Author: mimik technology inc
Latest version: 7.2.6

<a name="module_local"></a>

## local
Utilities for local deployment.

The following files are expected to exist:

In the directory **above** the server’s root directory: `mSTConfig.json`, `mIDConfig.json`, `mITConfig.json`, `sumoLog.json`, `kinesisLog.json`, `s3Log.json`, `customerConfig.json`, `key.json`, and `locationConfig.json`. If they don’t exist when the script launches, defaults will be set up.

- For `mSTConfig.json`:
```javascript
 {
   "basePath": "Base path of the mST server, e.g., `/mST/v1`",
   "protocol": "Protocol for the mST server, e.g., `http:` (default: `http:`)",
   "domainName": "Domain name of the mST server",
   "port": "Port for the mST server, e.g., `8025`",
   "passphrase": "Passphrase used to generate the public/private key pair; if not present, mST will use a regular key",
   "update": "Whether mST should be updated (default: `false`). If the address is localhost, mST will be updated.",
   "admin": {
     "clientId": "Client ID used to obtain an mST admin token, e.g., `12345`",
     "clientSecret": "Client secret used to obtain an mST admin token, e.g., `timeForSecret`"
   }
 }
```
`domainName` must exist. When `domainName` is `localhost`, `port` must also exist. When `domainName` is `localhost`, the local IP will replace `localhost`. When `domainName` is different from `localhost`, `port` is ignored.

- For `mIDConfig.json`:
```javascript
 {
   "basePath": "Base path of the mID server, e.g., `/mID/v1`",
   "protocol": "Protocol for the mID server, e.g., `http:` (default: `http:`)",
   "domainName": "Domain name of the mID server",
   "port": "Port for the mID server, e.g., `8015`",
   "implicit": {
     "key": "Key to sign and verify the signature of a user token, e.g., `timeForSecret`",
     "audience": "URL defining the audience used in the user token, e.g., `https://mimik`"
   }
 }
```
The same `domainName`/`port` rules as in `mSTConfig.json` apply.

- For `mITConfig.json`:
```javascript
 {
   "basePath": "Base path of the mIT server, e.g., `/mIT/v1`",
   "protocol": "Protocol for the mIT server, e.g., `http:` (default: `http:`)",
   "domainName": "Domain name of the mIT server",
   "port": "Port for the mIT server, e.g., `8050`"
 }
```
The same `domainName`/`port` rules as in `mSTConfig.json` apply.

- For `sumoLog.json`:
```javascript
 {
   "<serverType>": {
     "url": "Base URL for Sumo Logic, e.g., `https://endpoint2.collection.us2.sumologic.com/receiver/v1/http/`",
     "code": "The code for Sumo Logic (the part after the last `/` in the URL)"
   },
   "default": {
     "url": "Base URL for Sumo Logic, e.g., `https://endpoint2.collection.us2.sumologic.com/receiver/v1/http/`",
     "code": "The code for Sumo Logic (the part after the last `/` in the URL)"
   }
 }
```

- For `kinesisLog.json`:
```javascript
 {
   "region": "Region of the Kinesis implementation",
   "accessKeyId": "Access key ID for Kinesis",
   "secretAccessKey": "Secret access key for Kinesis",
   "streamNameInfo": "Name of the Kinesis stream for info",
   "streamNameError": "Name of the Kinesis stream for errors",
   "streamNameOther": "Name of the Kinesis stream for all other levels",
   "maxEvents": "Number of events buffered before sending to Kinesis",
   "timeout": "Number of minutes before a timeout triggers sending to Kinesis",
   "maxSize": "Maximum size in bytes before sending to Kinesis",
   "maxRetries": "Maximum retries to connect to Kinesis",
   "httpOptions": {
      "socketTimeout": "Socket timeout for the HTTP handler (in millisecond)",
      "connectionTimeout": "Connection timeout for the HTTP handler (in millisecond)"
   }
 }
```

- For `s3Log.json`:
```javascript
 {
   "region": "Region of the S3 implementation",
   "accessKeyId": "Access key ID for S3",
   "secretAccessKey": "Secret access key for S3",
   "bucketname": "Name of the S3 bucket used to store information",
   "maxEvents": "Number of events buffered before sending to S3",
   "timeout": "Number of minutes before a timeout triggers sending to S3",
   "maxSize": "Maximum size in bytes before sending to S3"
 }
```

- for `key.json`:
```javascript
 {
   "bitbucket": {
     "username": "Username to access the Bitbucket account",
     "password": "Password to access the Bitbucket account"
   },
   "swaggerhub": "Key to access private APIs on SwaggerHub"
 }
```

- For `locationConfig.json`:
```javascript
 {
   "url": "URL of the location provider",
   "key": "API key used to make requests to the location provider"
 }
```

A property may be defined for each `serverType` involved. If the `serverType` does not exist, the `default` entry is used.

- for `customerConfig.json`: see `mST` `README.md` file for an example of a customer configuration. This may have to be updated to reflect the new server.
- In the `local` directory under the server's root directory: two files, `start.json` and `testStart.json`, may exist. `start.json` is used when `npm start` is executed; `testStart.json` is used when `npm test` is executed.
If these files don't exist, `example-start.json` is used to create `start.json` and `testStart.json`. Additionally, `example-testStart.json` is used to create `testStart.json`; values in `example-testStart.json` take precedence over values in `example-start.json`.
The configuration of these files depends on the server's configuration parameters.

Example `start.json` for `mIT`:
```javascript
 {
   "NODE_ENV": "local",
   "LOG_LEVEL": "debug",
   "CONSOLE_LEVEL": "silly",
   "DATABASE_NAME": "itResources",
   "SERVER_PORT": 8050,
   "IP_LOCATION_PROVIDER": "http://localhost:9000/json",
   // "LOCATION_PROVIDER": "http://ip-api.com/json",
   // "DEBUG": "swagger-tools:middleware.*",
   "SERVER_SECURITY_SET": "off"
 }
```

Although all files use the `.json` extension, you may still add `//` comments to make them more explicit or to remove parameters.

Reserved environment variables used by the library for configuration:
- `oauthImplicitNeeded`: if the service handles user tokens, the implicit configuration is required
- `mIDNeeded`: if the service targets mID
- `locationNeeded`: if location translation is needed
- `standAlone`: if the service must operate without other services (if the service has targets, 500 errors are likely)

If `SERVER_ID` is not set in `start.json` or `testStart.json`, it will be assigned using `uuidv4`.

For tests, a JSON file (`server-test.json`) is created in the project root (`.`).
This file contains information needed to start the tests:
```javascript
 {
   "start": "Information needed to set environment variables for the test",
   "CUSTOMER_NAME": "Customer name used to set up customer config",
   "CUSTOMER_CODE": "Customer code used to set up customer config (`not available for mST`)",
   "BASE_PATH": "Base path of the API",
   "MST_TOKEN": "mST admin token for creating clients (`not available in standAlone`)",
   "ADMIN_TOKEN": "Admin token of the service (`not available in standAlone`)",
   "MID_TOKEN": "mID admin token for creating users when `authImplicitNeeded` is set (`not available in standAlone`)"
 }
```

In `standAlone` mode, the test can obtain tokens using `oauth-helper-temp`.

**Example**  
```js
// Default import
import local from '@mimik/local';
```
**Example**  
```js
// Named imports
import { mSTTestSetup, mSTSetup, mITTestSetup, mITSetup, testSetup, setup, dotFiles, scripts, unScripts, commitCheckMsg, start2process, testJsonFile } from '@mimik/local';
```

* [local](#module_local)
    * _static_
        * [.testJsonFile](#module_local.testJsonFile) : <code>string</code>
    * _inner_
        * _async_
            * [~commitCheckMsg()](#module_local..commitCheckMsg) ⇒ <code>Promise</code>
        * _sync_
            * [~mSTTestSetup()](#module_local..mSTTestSetup) ⇒
            * [~mSTSetup()](#module_local..mSTSetup) ⇒
            * [~mITTestSetup()](#module_local..mITTestSetup) ⇒
            * [~mITSetup()](#module_local..mITSetup) ⇒
            * [~testSetup()](#module_local..testSetup) ⇒
            * [~setup()](#module_local..setup) ⇒
            * [~dotFiles()](#module_local..dotFiles) ⇒
            * [~scripts()](#module_local..scripts) ⇒
            * [~unscripts()](#module_local..unscripts) ⇒
            * [~start2process(start)](#module_local..start2process) ⇒ <code>void</code>

<a name="module_local.testJsonFile"></a>

### local.testJsonFile : <code>string</code>
Path to the JSON test file.

**Kind**: static constant of [<code>local</code>](#module_local)  
<a name="module_local..commitCheckMsg"></a>

### local~commitCheckMsg() ⇒ <code>Promise</code>
Check the validity of the commit message.

**Kind**: inner method of [<code>local</code>](#module_local)  
**Returns**: <code>Promise</code> - .  
**Category**: async  
**Fulfil**: `null`.

Exits with code `1` if the commit message is not correct or if the branch is not a Jira generated branch.  
<a name="module_local..mSTTestSetup"></a>

### local~mSTTestSetup() ⇒
Set up `mST` for tests.

**Kind**: inner method of [<code>local</code>](#module_local)  
**Returns**: `null`.

Exits with code `1` on error.

Actions performed:

1. Retrieve the API definition from [SwaggerHub](https://app.swaggerhub.com/search?type=API&owner=mimik).
2. Generate a JSON object and store it in a file in the project root (`.`) to enable tests.

Files required:

| Filename | Description |
| -------- | ----------- |
| `../sumoLog.json` | Sumologic endpoints and code
| `../kinesisLog.json` | AWS Kinesis configuration
| `../s3Log.json` | AWS S3 configuration
| `../mSTConfig.json` | mST configuration
| `../mITConfig.json` | mIT configuration
| `../locationConfig.json` | Location provider URL and key (when needed)
| `../key.json` | Github username and password or Swaggerhub key
| `./local/testStart.json` | Local configuration (if it does not exist, `example-start.json` will be used to create `testStart.json`)  
**Category**: sync  
<a name="module_local..mSTSetup"></a>

### local~mSTSetup() ⇒
Set up `mST`.

**Kind**: inner method of [<code>local</code>](#module_local)  
**Returns**: `null`.

Exits with code `1` on error.

Actions performed:

1. Retrieve the API definition from [SwaggerHub](https://app.swaggerhub.com/search?type=API&owner=mimik).
2. Generate a shell script in the project root (`.`) to start the server.

Files required:

| Filename | Description |
| -------- | ----------- |
| `../sumoLog.json` | Sumologic endpoints and code
| `../kinesisLog.json` | AWS Kinesis configuration
| `../s3Log.json` | AWS S3 configuration
| `../mSTConfig.json` | mST configuration
| `../mITConfig.json` | mIT configuration
| `../locationConfig.json` | Location provider URL and key (when needed)
| `../key.json` | Github username and password or Swaggerhub key
| `./local/start.json` | Local configuration (if it does not exist, `example-start.json` will be used to create `start.json`)  
**Category**: sync  
<a name="module_local..mITTestSetup"></a>

### local~mITTestSetup() ⇒
Set up `mIT` for tests.

**Kind**: inner method of [<code>local</code>](#module_local)  
**Returns**: `null`.

Exits with code `1` on error.

Two modes are available:

1. Standalone
2. With mST

The environment variable `STAND_ALONE` selects the mode.

When **standalone**, the following actions are performed:

1. Retrieve the API definition from [SwaggerHub](https://app.swaggerhub.com/search?type=API&owner=mimik).
2. Obtain an admin token for the service.
3. Generate a JSON object and store it in a file under the project root (`.`).

In `standAlone` mode, dependencies are not reachable and operations that contact dependencies will most likely return a 500 error.

When **mST and other servers are present**, the following actions are performed:

1. Retrieve the API definition from [SwaggerHub](https://app.swaggerhub.com/search?type=API&owner=mimik).
2. Obtain an admin token for mST.
3. Register the service in mST.
4. Register an admin client for the service in mST.
5. Obtain an admin token for the service.
6. Obtain an admin token for mID if needed.
7. Generate a JSON object and store it in a file under the project root (`.`).

Files required:

| Filename | Description |
| -------- | ----------- |
| `../sumoLog.json` | Sumologic endpoints and code
| `../kinesisLog.json` | AWS Kinesis configuration
| `../s3Log.json` | AWS S3 configuration
| `../mSTConfig.json` | mST configuration
| `../mITConfig.json` | mIT configuration
| `../locationConfig.json` | Location provider URL and key (when needed)
| `../key.json` | Github username and password or Swaggerhub key
| `./local/testStart.json` | Local configuration (if it does not exist, `example-start.json` will be used to create `testStart.json`)  
**Category**: sync  
<a name="module_local..mITSetup"></a>

### local~mITSetup() ⇒
Set up `mIT`.

**Kind**: inner method of [<code>local</code>](#module_local)  
**Returns**: `null`.

Exits with code `1` on error.

Two modes are available:

1. Standalone
2. With mST

The environment variable `STAND_ALONE` selects the mode.

When **standalone**, the following actions are performed:

1. Retrieve the API definition from [SwaggerHub](https://app.swaggerhub.com/search?type=API&owner=mimik).
2. Obtain an admin token for the service.
3. Generate a shell script in the project root (`.`) to start the server.

In `standAlone` mode, dependencies are not reachable and operations that contact dependencies will most likely return a 500 error.

When **mST is present**, the following actions are performed:

1. Retrieve the API definition from [SwaggerHub](https://app.swaggerhub.com/search?type=API&owner=mimik).
2. Obtain an admin token for mST.
3. Register the service in mST.
4. Generate a shell script in the project root (`.`) to start the server.

Files required:

| Filename | Description |
| -------- | ----------- |
| `../sumoLog.json` | Sumologic endpoints and code
| `../kinesisLog.json` | AWS Kinesis configuration
| `../s3Log.json` | AWS S3 configuration
| `../mSTConfig.json` | mST configuration
| `../mITConfig.json` | mIT configuration
| `../locationConfig.json` | Location provider URL and key (when needed)
| `../key.json` | Github username and password or Swaggerhub key
| `./local/start.json` | Local configuration (if it does not exist, `example-start.json` will be used to create `start.json`)  
**Category**: sync  
<a name="module_local..testSetup"></a>

### local~testSetup() ⇒
Set up a service (not mST or mIT) for tests.

**Kind**: inner method of [<code>local</code>](#module_local)  
**Returns**: `null`.

Exits with code `1` on error.

Two modes are available:

1. Standalone
2. With mST/mID and other dependent servers

The environment variable `STAND_ALONE` selects the mode.

When **standalone**, the following actions are performed:

1. Retrieve the API definition from [SwaggerHub](https://app.swaggerhub.com/search?type=API&owner=mimik).
2. Obtain an admin token for the service.
3. Generate a JSON object and store it in a file under the project root (`.`).

In `standAlone` mode, dependencies are not reachable and operations that contact dependencies will most likely return a 500 error.

When **mST and other servers are present**, the following actions are performed:

1. Retrieve the API definition from [SwaggerHub](https://app.swaggerhub.com/search?type=API&owner=mimik).
2. Obtain an admin token for mST.
3. Set up the customer in mST.
4. Register the service in mST.
5. Register an admin client for the service in mST.
6. Obtain an admin token for the service.
7. Obtain an admin token for mID if needed.
8. Generate a JSON object and store it in a file under the project root (`.`).

Files required:

| Filename | Description |
| -------- | ----------- |
| `../sumoLog.json` | Sumologic endpoints and code
| `../kinesisLog.json` | AWS Kinesis configuration
| `../s3Log.json` | AWS S3 configuration
| `../mSTConfig.json` | mST configuration
| `../mITConfig.json` | mIT configuration
| `../mIDConfig.json` | mID configuration (when needed)
| `../customerConfig.json` | mST customer configuration
| `../locationConfig.json` | Location provider URL and key (when needed)
| `../key.json` | Github username and password or Swaggerhub key
| `./local/testStart.json` | Local configuration (if it does not exist, `example-start.json` will be used to create `testStart.json`)  
**Category**: sync  
<a name="module_local..setup"></a>

### local~setup() ⇒
Set up a service (not mST or mIT).

**Kind**: inner method of [<code>local</code>](#module_local)  
**Returns**: `null`.

Exits with code `1` on error.

Two modes are available:
1. Standalone
2. With mST/mID and other dependent servers

The environment variable `STAND_ALONE` selects the mode.

When **standalone**, the following actions are performed:

1. Retrieve the API definition from [SwaggerHub](https://app.swaggerhub.com/search?type=API&owner=mimik).
2. Obtain an admin token for the service.
3. Generate a shell script to start the server.

In `standAlone` mode, dependencies are not reachable and operations that contact dependencies will most likely return a 500 error.

When **mST and other servers are present**, the following actions are performed:

1. Retrieve the API definition from [SwaggerHub](https://app.swaggerhub.com/search?type=API&owner=mimik).
2. Obtain an admin token for mST.
3. Set up the customer in mST.
4. Register the service in mST.
5. Generate a shell script in the project root (`.`) to start the server.

The following files are needed to perform these actions:

| Filename | Description |
| -------- | ----------- |
| `../sumoLog.json` | Sumo Logic endpoints and code
| `../kinesisLog.json` | Kinesis configuration
| `../s3Log.json` | S3 configuration
| `../mSTConfig.json` | mST configuration
| `../mITConfig.json` | mIT configuration
| `../mIDConfig.json` | mID configuration (when needed)
| `../customerConfig.json` | mST customer configuration
| `../locationConfig.json` | Location provider URL and key (when needed)
| `../key.json` | Github username and password or Swaggerhub key
| `./local/start.json` | Local configuration (if it does not exist, `example-start.json` will be used to create `start.json`)  
**Category**: sync  
<a name="module_local..dotFiles"></a>

### local~dotFiles() ⇒
Utility to create `rule files`.

**Kind**: inner method of [<code>local</code>](#module_local)  
**Returns**: `null`.

Creates the `rule files` for:

- `eslint` -> `eslint.config.js`.
- `github` -> `.gitignore`
- `husky` -> `.husky/pre-commit`, `.husky/pre-push`, `.husky/commit-msg`

If a file already exists, it will be overwritten.  
**Category**: sync  
<a name="module_local..scripts"></a>

### local~scripts() ⇒
Utility to add `scripts` to `package.json`.

**Kind**: inner method of [<code>local</code>](#module_local)  
**Returns**: `null`.

Adds `scripts` to `package.json`. If a script already exists, it will be overwritten.  
**Category**: sync  
<a name="module_local..unscripts"></a>

### local~unscripts() ⇒
Utility to remove `scripts` from `package.json`.

**Kind**: inner method of [<code>local</code>](#module_local)  
**Returns**: `null`.

Removes `scripts` from `package.json`. Only removes the scripts that are in the script file.  
**Category**: sync  
<a name="module_local..start2process"></a>

### local~start2process(start) ⇒ <code>void</code>
Set up the environment variables based on given JSON object.

**Kind**: inner method of [<code>local</code>](#module_local)  
**Category**: sync  

| Param | Type | Description |
| --- | --- | --- |
| start | <code>object</code> | JSON object that is used to configure the environment variables. The comments (starting by //) are ignored. |