Skip to main content

Getting Started

Prerequisites​

  • Node.js: Version 18 or higher
  • AWS Account: Active AWS account with configured credentials
  • AWS CLI (optional): For credential management

Installing carlin​

Install carlin locally in your project:

pnpm add -D carlin

Add deployment scripts to package.json:

{
  "scripts": {
    "deploy": "carlin deploy",
    "deploy:production": "carlin deploy --environment production",
    "destroy": "carlin deploy --destroy"
  }
}

Run deployments:

pnpm deploy

Global Installation​

Install carlin globally for use across multiple projects:

pnpm add -g carlin

Verify installation:

carlin --version

AWS Credentials Configuration​

carlin uses AWS SDK credentials. Configure using any of these methods:

AWS CLI Configuration​

aws configure

Provide:

  • AWS Access Key ID
  • AWS Secret Access Key
  • Default region (e.g., us-east-1)
  • Output format (e.g., json)

Environment Variables​

export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="us-east-1"

AWS Credentials File​

Create ~/.aws/credentials:

[default]
aws_access_key_id = your-access-key
aws_secret_access_key = your-secret-key

[production]
aws_access_key_id = your-production-key
aws_secret_access_key = your-production-secret

Use specific profile:

AWS_PROFILE=production carlin deploy

Required AWS Permissions​

Ensure your AWS credentials have these permissions:

  • CloudFormation: cloudformation:* (Create/Update/Delete stacks)
  • S3: s3:* (Lambda code uploads, static apps)
  • IAM: iam:PassRole, iam:CreateRole, iam:AttachRolePolicy
  • Lambda: lambda:* (Function deployment)
  • CloudFront (for static apps): cloudfront:*
  • ECR (for Docker-based Lambdas): ecr:*

Minimal IAM policy example:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudformation:*",
        "s3:*",
        "lambda:*",
        "iam:PassRole",
        "iam:CreateRole",
        "iam:AttachRolePolicy",
        "logs:*"
      ],
      "Resource": "*"
    }
  ]
}

Verify Setup​

Test your installation and credentials:

carlin deploy --help

You should see carlin's help output with available commands and options.

Next Steps​