aws-deployer-threequarters

A Git-aware AWS deployment utility for Node.js applications. Automatically creates versioned deployments using Git commit information.

Features

• 🚀 Automated S3 deployment with Git commit versioning
• 🏷️ Automatic tagging with branch information
• 📦 Smart zip creation with configurable exclusions
• 🔐 Built-in encryption/decryption utilities
• 🌍 Multi-region S3 support
• 📝 Service-prefixed logging

Requirements

• Node.js >= 18.18.0
• Git repository
• AWS credentials configured (via AWS CLI, environment variables, or IAM role)

Installation

npm install aws-deployer-threequarters

Usage

Basic Deployment

import { AWSDeployer, EnvironmentTier } from 'aws-deployer-threequarters';

const config = {
  serviceName: 'my-app',
  repositoryName: 'my-company/my-app',
  tierName: EnvironmentTier.WEB_SERVER,
  whatsLiveIncludeTerminated: false,
  variables: new Map(),
  nodeVersion: '20.x',
};

const deployer = new AWSDeployer(config);

// Deploy to S3
await deployer.deploy();

// Deploy with encrypted environment file
// Use --env flag when running: node your-script.js --env
await deployer.deploy();

Environment Variables

Required:

• AWS_DEFAULT_REGION - AWS region for S3 operations
• AWS_ACCESS_KEY_ID - AWS access key for authentication
• AWS_SECRET_ACCESS_KEY - AWS secret key for authentication

Optional:

• CI_BRANCH - Branch name for CI/CD environments (used when Git HEAD is detached)
• GITHUB_ACTOR - Automatically detected in GitHub Actions
• NODE_ENV - Environment mode (automatically added if not present)
• DEPLOYER_ENCRYPTION_KEY - 32-character key for file encryption/decryption
• DEPLOYER_INITIALIZATION_VECTOR - 16-character IV for file encryption/decryption

Deployment Process

1. Validates environment variables (required vs optional)
2. Optionally loads encrypted environment file (with --env flag)
3. Extracts current Git commit information (hash, branch, message)
4. Creates a zip file excluding:
   • node_modules/
   • .git/
   • logs/
   • .DS_Store
5. Uploads to S3 bucket: {serviceName}-application-versions
6. Tags the upload with branch information

File Encryption/Decryption

The package includes utilities for encrypting sensitive configuration files:

# Encrypt a file
DEPLOYER_ENCRYPTION_KEY=your-32-char-key DEPLOYER_INITIALIZATION_VECTOR=your-16-char-iv \
node -e "new (require('aws-deployer-threequarters').AWSDeployer)({}).encryptFile()" config.json config.json.enc

# Decrypt a file
DEPLOYER_ENCRYPTION_KEY=your-32-char-key DEPLOYER_INITIALIZATION_VECTOR=your-16-char-iv \
node -e "new (require('aws-deployer-threequarters').AWSDeployer)({}).decryptFile()" config.json.enc config.json

# Note: The encryption/decryption methods read file paths from process.argv[2] and process.argv[3]
# Make sure to pass the input and output file paths as the last two arguments

S3 Bucket Structure

Deployments are stored in S3 with the following structure:

{serviceName}-application-versions/
├── 7f7a323.zip  (tagged with branch=main)
├── a1b2c3d.zip  (tagged with branch=feature/new-feature)
└── ...

API Reference

AWSDeployer

Main class for handling deployments.

Constructor

new AWSDeployer(config: IServiceConfig)

Methods

• deploy(): Promise<void> - Executes the deployment with optional encrypted env file support
• encryptFile(): void - Encrypts a file (reads paths from process.argv[2] and process.argv[3])
• decryptFile(): void - Decrypts a file (reads paths from process.argv[2] and process.argv[3])

Configuration Types

interface IServiceConfig {
  serviceName: string; // Used for S3 bucket naming and logging
  repositoryName: string; // Repository identifier
  tierName: EnvironmentTier; // Currently only WEB_SERVER supported
  whatsLiveIncludeTerminated: boolean;
  variables: Map<string, IEnvironmentVariable>;
  nodeVersion?: string; // Optional Node.js version
}

interface IEnvironmentVariable {
  isOptional: boolean;
  value?: string;
}

Error Handling

The package includes comprehensive error handling for:

• Missing S3 buckets (automatically creates them)
• Region-specific bucket creation
• Git command failures
• Missing environment variables

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests (once implemented)
npm test

License

ISC

Author

Dimitrios Chatziioannou