Configuration

Setting Options

You can set the Carlin commands options in different ways, such as using the command line, environment variables, or a configuration file.

Command Line

You can set the Carlin commands options using the command line. For example, to set the --environment, -e, --env option, you can use the following command:

carlin deploy --environment Production
carlin deploy -e Production

package.json

You can also provide the options creating a property name carlin in your package.json.

{
  "name": "my-app",
  "version": "0.1.0",
  "carlin": {
    "environment": "Production"
  }
}

Environment Variables

You can set the options as environment variables matching the prefix CARLIN. The examples below are equivalent:

• carlin deploy --stack-name MyStackName
• CARLIN_STACK_NAME=MyStackName carlin deploy

ENVIRONMENT is a special case because it is used to set the environment option, as well CARLIN_ENVIRONMENT. The examples below are equivalent:

• carlin deploy --environment Production
• CARLIN_ENVIRONMENT=Production carlin deploy
• ENVIRONMENT=Production carlin deploy

Configuration File

If --config isn't provided, the algorithm will search for any of these files and use it to retrieve the options:

• carlin.ts
• carlin.js
• carlin.yml
• carlin.yaml
• carlin.json

The algorithm also make a find up path to search for other config files that may exist in parent directories. If find more than one file, they'll be merged, in such a way that the files nearest from process.cwd() will take the precedence at the merging.

This is useful if you have a monorepo and have shared and specific configuration. For instance, you may have a config inside packages/app/ folder with the config below:

stackName: MyMonorepoApp
region: us-east-2

And on the root of your monorepo:

awsAccountId: 123456789012
region: us-east-1

The result options that will be passed to the commands executed on packages/app/ will be:

awsAccountId: 123456789012
stackName: MyMonorepoApp
region: us-east-2

If you define your config file programmatically, you can use the your environment variables from a .env file if it exists. For example:

export default {
 environment: process.env.ENVIRONMENT,
 region: process.env.REGION,
}

Multiple Environments

We architected Carlin to work with multiple environments. The environments option is an object that contains specific values for each environment. For instance, you may have a Production and a Staging environment with different values for the same option, like awsAccountId. The environment option is a string that represents the current environment. The environments option is an object that contains the values for each environment. The values of the current environment will be merged with the default values.

For example, if you have the following config file:

awsAccountId: 111111111111

environments:
 Production:
   awsAccountId: 222222222222

 Staging:
   awsAccountId: 333333333333

And you run the following command:

carlin deploy --environment Production

The final awsAccountId value will be 222222222222. If you run the following command:

carlin deploy --environment Staging

The final awsAccountId value will be 333333333333. If you run the deploy command without the --environment option, the final value will be 111111111111.

environments is great to work on CI/CD pipelines. You can set the environment value as an environment variable and Carlin will use the values from the config file.

Global Options

Option	Alias	Default	Description	Type
branch				string
config	c		Path to config file. You can create a config file and set all options there. Valid extensions: .js, .json, .ts, .yml, or .yaml.	string
environment	e, env			string
environments
project				string
region	r	us-east-1	AWS region.	string