mira/docs/config/README.md

NearForm Accelerator for Cloud Native Serverless AWS

# Configuration
This section describes how to configure your app to work with Mira.
The configuration system is based on the [node config](https://www.npmjs.com/package/config) library.

__Note:__ Once app configuration properties are set, any change to them will trigger a full redeploy of the stacks (rather than an incremental update).

## File Location

In your app, the config file must be located in `./config/default.json`

## A Sample Config File

Let's take a look at a sample config file.
```
{
  "app": {
    "prefix": "John",
    "name": "My Great App"
  },
  "dev": {
    "target": "staging"
  },
  "costCenter": "cost-center-tag",
  "cicd": {
    target: "cicd",
    "buildspecFile": "infra/buildspec.yaml",
    "permissionsFile": "infra/src/permissions.js",
    "provider": "codecommit",
    "profile": "mira-dev",
    "repositoryUrl": "YORU_REPO_URL",
    "branchName": "feature/feature-xyz",
    "codeCommitUserPublicKey": "ssh-rsa ...",
    "environmentVariables": [
      {
        "name": "CUSTOM_VARIABLE",
        "value": "123453546647"
      }
    ],
    "stages": [
      {
        "target": "staging",
        "withDomain": false,
        "requireManualApproval": false,
        "privileged": true
      },
      {
        "target": "production",
        "withDomain": false,
        "requireManualApproval": true,
        "privileged": false
      }
    ]
  },
  "accounts": {
      "cicd": {
        "env": {
          "account": "ACCOUNT_NUMER",
          "region": "REGION"
        },
        "profile": "mira-dev"
      },
      "staging": {
        "env": {
          "account": "ACCOUNT_NUMER",
          "region": "REGION"
        },
        "profile": "mira-dev"
      },
      "production": {
        "env": {
          "account": "ACCOUNT_NUMER",
          "region": "REGION"
        },
        "profile": "mira-prod"
      }
    }
}
```
### Main Section

```
"app": {
  "prefix": "John"
  "name" : "Sample App"
}
```

This data is used to generate Cloud Development Kit (CDK) Resource names.

The example above generates `John-SampleApp` as the prefix for stacks, roles, pipelines stages and so on.

### Accounts Section
The accounts section of the config file is a collection of account objects that can be used to deploy apps and run cicd. The accounts also represent environments.
We define three accounts in the sample config file above: `staging`, `production`, `cicd`, each with different account numbers.

The `staging` account may represent a developer's personal account where they can test all Mira deployments. It uses the default profile defined in the `~/.aws` directory or the one passed in as `--profile` parameter in the CLI command.


### CI/CD Section
The `cicd` section specifies the various stages of the deployment pipeline and other properties required for the CI pipeline to work.
* `target` - Name of the account where the CI pipeline will be deployed.
* `buildspecFile` - Path to the buildspec file used by AWS CodeBuld for application deployment.
* `repositoryUrl` - Repository URL that is decomposed to extract project name used in the pipeline.
* `permissionsFile` - Path to the file with DeploymentPermissions stack. This stack defines a role that is required to assign permissions for the CI, so it can deploy application on a different AWS accounts.
* `branchName` - Name of the branch used by the pipeline.
* `codeCommitUserPublicKey` - RSA public key used for the Mira service user to get permissions to mirror the repository.
    __Caution:__ Make sure to not include any whitespace characters in `codeCommitUserPublicKey`
* `environmentVariables` - An array of environment variables passed into AWS CodeBuild.
    e.g.:
    ```json
      {
        "name": "FOO",
        "value": "BAR"
      }
    ```
* `stages` - An ordered list of stages where Code Pipeline will deploy the application.
Stage is described by 3 properties:
    * `target` - Name of the account used as a target account for the application deployment (e.g. staging).
    * `withDomain` - A boolean that specifies if the application supports a custom domain. __NB domain usage to follow in upcoming releases.__.
    * `requireManualApproval` - A boolean that specifies if manual approval is needed in the pipeline before continuing deployment.
    * `privileged` - A boolean that specifies if the pipeline should support the `privileged` environment value. 
                This value should be set to `true` if the `buildfile.yaml` requires to execute some docker actions.

## Domain Configuration

Domain management components (Certificate, Route53 and so on) are deployed on the `Domain` account. It uses `Z1234567890` as the Hosted Zone ID.

NB Example domain usage to follow in upcoming releases.


## Cost Center Tag

To enable the creation of the cost center tag you need to specify a `costCenter` property.

See [Using Cost Allocation Tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) for more information.

## Developer Configuration

To enable custom config modifications for developers working in the same team, Mira expects a `config/dev.json` file to be created.

__Note:__ This file should not by tracked in GIT.

Whenever a `config/dev.json` file is created and available at runtime, the contents of the `config/default.json` will be overridden in a shallow way. It means only the top-level properties are merged. The method used is comparable to [Object.assign](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign).