Introduction

carlin is a CLI tool for deploying AWS infrastructure using CloudFormation templates. It automates Lambda code building, S3 uploads, stack naming, multi-environment deployments, and CI/CD pipelines.

What is carlin?

carlin started in 2018 as deployment scripts for managing CloudFormation stacks across multiple environments (development, staging, production). After streamlining numerous deployments, we packaged these scripts into a unified CLI tool.

Today, carlin handles:

• CloudFormation deployments with automatic stack naming
• Lambda functions with code building and S3 uploads
• Static websites via S3 and CloudFront
• CI/CD pipelines with GitHub and Slack integration
• Environment variables generation from stack outputs
• Multi-environment configurations with termination protection

Why Use carlin?

Simplified AWS Deployments

Deploy CloudFormation stacks with a single command:

carlin deploy

carlin automatically:

• Finds your CloudFormation template
• Builds Lambda function code
• Uploads to S3 with versioning
• Creates or updates stacks
• Displays outputs

Automatic Lambda Handling

No manual Lambda packaging—carlin detects Lambda functions in templates, builds code with esbuild, uploads to S3, and injects parameters automatically.

Multi-Environment Support

Deploy to multiple environments with built-in protection:

carlin deploy --environment staging
carlin deploy --environment production # includes termination protection

This supports the E6: U-curve Principle by balancing automation with safety controls.

Branch-Based Deployments

Test feature branches with automatic stack naming:

# On feature/auth branch
carlin deploy
# Creates: my-app-feature-auth

Infrastructure as TypeScript

Write CloudFormation templates in TypeScript with type safety and dynamic generation:

export const template = {
  Resources: {
    Bucket: {
      Type: 'AWS::S3::Bucket',
      Properties: {
        BucketName: `my-app-${process.env.NODE_ENV}`,
      },
    },
  },
};

Use Cases

Serverless APIs

Deploy Lambda functions with API Gateway:

// cloudformation.ts
export const template = {
  Resources: {
    Api: {
      Type: 'AWS::ApiGateway::RestApi',
      Properties: { Name: 'MyApi' },
    },
    Function: {
      Type: 'AWS::Lambda::Function',
      Properties: {
        Runtime: 'nodejs20.x',
        Handler: 'api/handler.handler',
        Code: {
          S3Bucket: { Ref: 'LambdaS3Bucket' },
          S3Key: { Ref: 'LambdaS3Key' },
        },
      },
    },
  },
};

carlin deploy --environment production

Static Websites

Deploy React/Vue/Vite apps to S3 + CloudFront:

pnpm build
carlin deploy static-app --cloudfront --aliases app.example.com

Full-Stack Applications

Combine infrastructure, APIs, and frontends:

# Deploy infrastructure (DB, S3, API)
carlin deploy --environment production

# Generate environment variables
carlin generate-env --default-environment Production

# Deploy frontend
carlin deploy static-app --environment production

CI/CD Pipelines

Automate deployments with GitHub Actions:

- name: Deploy Infrastructure
  run: carlin deploy --environment production

- name: Deploy Application
  run: carlin deploy static-app --environment production

Quick Start

Get started in 5 minutes:

1. Install carlin:

pnpm add -D carlin

2. Create CloudFormation template (cloudformation.ts):

export const template = {
  Resources: {
    MyBucket: {
      Type: 'AWS::S3::Bucket',
    },
  },
  Outputs: {
    BucketName: {
      Value: { Ref: 'MyBucket' },
    },
  },
};

3. Deploy:

carlin deploy

See Quick Start Guide for complete walkthrough.

Documentation Structure

• Getting Started - Setup AWS credentials and carlin CLI
• Quick Start - Deploy your first stack in minutes
• Core Concepts - Stack naming, environments, base stack, templates
• Commands - Complete command reference
• Guides - Task-oriented tutorials
• Configuration - Advanced configuration options

Key Features

Automatic Stack Naming

carlin generates stack names from package.json and branch/environment:

# Package: my-app, Branch: main
carlin deploy
# Stack: my-app-main

# Package: my-app, Environment: production
carlin deploy --environment production
# Stack: my-app-production

Lambda Code Building

Automatic Lambda code bundling with esbuild:

// Template references handler
Handler: 'users/create.handler';

// carlin builds src/users/create.ts automatically

Static App Deployment

One command deploys static sites to S3 + CloudFront:

carlin deploy static-app --cloudfront --spa

Environment Variables

Generate .env files from stack outputs:

carlin deploy
carlin generate-env
# Creates .env.Staging with stack outputs

Termination Protection

Production environments are automatically protected:

carlin deploy --environment production
# Stack has termination protection enabled

Community and Support

• GitHub: ttoss/ttoss
• Issues: Report bugs or request features
• Examples: Terezinha Farm API

Next Steps

• Install carlin and configure AWS credentials
• Deploy your first stack with step-by-step guide
• Understand core concepts for advanced usage
• Explore commands for complete reference