SmartConfig CLI

A comprehensive deployment CLI tool for SmartConfig infrastructure that packages all dependencies and provides a single-command deployment experience.

Overview

The SmartConfig CLI is a Node.js-based command-line tool that automates the complete deployment of the SmartConfig platform to AWS. It bundles all necessary dependencies, builds and uploads Docker images, deploys infrastructure using AWS CDK, and uploads frontend assets to S3.

What It Does

🏗️ Infrastructure Deployment

• Deploys complete SmartConfig infrastructure using AWS CDK
• Creates VPC, subnets, security groups, and networking components
• Provisions RDS PostgreSQL database with configurable parameters
• Sets up ECS Fargate clusters for backend services
• Creates S3 buckets for website, widget, and documentation hosting
• Configures CloudFront distributions for content delivery
• Sets up Application Load Balancers and auto-scaling

🐳 Container Management

• Builds and uploads backend Docker images to Amazon ECR
• Handles multi-platform builds (linux/amd64)
• Manages ECR repository creation and authentication
• Tags images with build timestamps for versioning

📦 Asset Deployment

• Builds and uploads frontend React application to S3
• Deploys chat widget assets to dedicated S3 bucket
• Uploads documentation site to docs S3 bucket
• Invalidates CloudFront cache for immediate updates
• Updates frontend environment variables with deployed API endpoints

🔧 Dependency Management

• Bundles all SmartConfig packages into a single deployable package
• Includes infrastructure code, frontend, backend, and shared libraries
• Copies Yarn configuration and lock files for consistent builds
• Filters out development files (node_modules, tests, etc.)

Package Structure

The CLI creates a self-contained deployment package with the following structure:

dist/
├── src/                    # Compiled CLI source code
├── dependencies/
│   ├── packages/
│   │   ├── smartconfig-backend/      # Backend API code
│   │   ├── smartconfig-frontend/     # React frontend
│   │   ├── smartconfig-infrastructure/ # CDK infrastructure code
│   │   ├── smartconfig-shared/       # Shared types and utilities
│   │   ├── chat-widget/              # Chat widget assets
│   │   ├── smartconfig-docs/         # Documentation site
│   │   ├── utils-shared/             # Utility libraries
│   │   └── frontend-shared/          # Frontend shared components
│   ├── .yarn/                        # Yarn configuration
│   ├── yarn.lock                     # Dependency lock file
│   ├── package.json                  # Root package configuration
│   ├── .yarnrc.yml                   # Yarn settings
│   └── Dockerfile                    # Backend container definition

Installation

From NPM (Recommended)

npm install smartconfig-cli

Usage

Option 1: Using Config File (Recommended)

Create a configuration file (e.g., smartconfig.config.json):

{
  "account": "123456789012",
  "region": "us-east-1",
  "hostedZoneName": "example.com",
  "hostedZoneId": "Z1234567890ABC",
  "stackName": "SmartConfig",

  "vpcCidr": "10.0.0.0/16",
  "maxAzs": 3,
  "enableVpcEndpoints": true,

  "fargateCpu": 512,
  "fargateMemoryLimit": 1024,
  "backendMinCapacity": 2,
  "backendMaxCapacity": 10,

  "databaseName": "smartconfig",
  "enableMultiAz": true,
  "databaseLogRetentionDays": 30
}

Then deploy:

npx smartconfig-cli deploy --config smartconfig.config.json

Benefits of using config files:

• Version control your infrastructure configuration
• Easy environment management (production.json, sandbox.json)
• Self-documenting infrastructure setup
• Simpler command line usage

Configuration File Format

Config files use standard JSON format. Type flexibility:

• Numeric values can be numbers (512) or strings ("512") - both work
• Boolean values can be booleans (true/false) or strings ("true"/"false") - both work
• String values must be quoted ("us-east-1")

Example:

{
  "fargateCpu": 512, // Number (recommended for JSON)
  "fargateCpu": "512", // String (also works, useful for CLI)
  "enableMultiAz": false, // Boolean (recommended for JSON)
  "enableMultiAz": "false", // String (also works)
  "region": "us-east-1" // String (required format)
}

This flexibility allows the same configuration schema to work with both JSON config files and CLI arguments.

Option 2: Using CLI Flags

npx smartconfig-cli deploy \
  --account 123456789012 \
  --region us-east-1 \
  --hosted-zone-name example.com \
  --hosted-zone-id Z1234567890ABC

Option 3: Hybrid Approach

Use a config file and override specific values:

npx smartconfig-cli deploy \
  --config production.json \
  --fargate-cpu 1024

Configuration Precedence

When using both config files and CLI flags, values are resolved in this order:

1. CLI flags (highest priority) - explicitly provided command-line arguments
2. Config file - values from the JSON config file
3. Defaults (lowest priority) - built-in default values

Example:

# Config file has: "fargateCpu": 256
# CLI override:
npx smartconfig-cli deploy --config sandbox.json --fargate-cpu 512

# Result: fargateCpu = 512 (CLI flag wins)

This allows you to:

• Maintain base configurations in version-controlled files
• Override specific values for one-off deployments
• Test configuration changes without modifying files

Configuration Reference

Required Parameters

• account: AWS account ID
• region: AWS region for deployment
• hostedZoneName: Domain name for the hosted zone
• hostedZoneId: Route53 hosted zone ID

Network Configuration

• vpcCidr: VPC CIDR block (default: 10.0.0.0/16)
• maxAzs: Maximum availability zones (default: 3)
• natGatewayCount: Number of NAT gateways (default: 1)
• enableVpcEndpoints: Create VPC endpoints for AWS services (default: true)

Backend Configuration

• fargateDesiredCount: Desired number of Fargate tasks (default: 1)
• fargateCpu: CPU units for Fargate task (default: 512)
• fargateMemoryLimit: Memory limit in MB (default: 1024)
• backendMinCapacity: Minimum auto-scaling capacity (default: 2)
• backendMaxCapacity: Maximum auto-scaling capacity (default: 10)

Database Configuration

• databaseName: Database name (default: smartconfig)
• databaseUsername: Database username (default: postgres)
• databaseInstanceSize: RDS instance size (default: t3.small)
  • Options: t3.micro (~$15/month), t3.small (~$30/month), t3.medium (~$60/month)
  • Sandbox recommendation: t3.micro for 50% cost savings
• databaseAllocatedStorage: Initial storage in GB (default: 20)
• databaseMaxAllocatedStorage: Maximum storage in GB (default: 100)
• enableMultiAz: Enable Multi-AZ deployment (default: true)
• databaseLogRetentionDays: Database backup retention (default: 30)
• postgresMaxConnections: Max database connections (default: 100)
• postgresSharedBuffers: Shared buffers in 8KB blocks (default: 2048, which equals 16 MB)

Weaviate Configuration

• weaviatePort: Weaviate service port (default: 8081)
• weaviateDesiredCount: Number of Weaviate instances (default: 1)
• weaviateCpu: CPU units for Weaviate (default: 1024)
• weaviateMemoryLimit: Memory limit for Weaviate (default: 4096)

Logging and Monitoring

• logRetentionDays: CloudWatch log retention (default: 30)
  • Options: 1, 3, 5, 7, 14, 30, 60, 90, 180, 365 days
  • Sandbox recommendation: 7 for ~70% cost savings on logs
• enableContainerInsights: Enable ECS Container Insights (default: true)
  • Cost: ~$10-20/month for detailed monitoring
  • Sandbox recommendation: false to save costs

Proxy Configuration

• proxyCpu: Squid proxy CPU units (default: 256)
• proxyMemoryLimit: Squid proxy memory in MB (default: 512)
• Sandbox recommendation: 128 CPU / 256 MB for 50% savings

Other Options

• stackName: CloudFormation stack name (default: SmartConfig)
• deletionProtection: Enable deletion protection (default: true)

Example Configurations

Production Configuration

See config.example.json for a production-ready configuration.

Sandbox/Development Configuration

See config.sandbox.example.json for a cost-optimized sandbox configuration with:

• Reduced compute resources (smaller Fargate, Weaviate, and proxy instances)
• Smaller RDS instance (t3.micro vs t3.small - saves ~$15/month)
• Single AZ database (no Multi-AZ - saves ~50% on database costs)
• VPC endpoints disabled (saves ~$20/month)
• Container Insights disabled (saves ~$10-20/month)
• Reduced log retention (7 days vs 30 days - saves ~70% on log costs)
• Lower auto-scaling limits (1-3 tasks vs 2-10)

Total estimated savings: $35-50/month 💰

Help

To see all available commands and options:

npx smartconfig-cli deploy --help

Contributing

For development and publishing instructions, see CONTRIBUTING.md.