RED

Automates the heavy lifting of running containerized jobs on AWS Batch.

RED

Really Easy Deployments

Deploy containerized tasks and scheduled batch workloads to AWS Batch in seconds.

RED automates the heavy lifting of running containerized jobs on AWS Batch. It builds your Docker image, provisions an Amazon ECR repository, configures the AWS Batch compute environment, handles recurring cron schedules, and pulls logs directly to your terminal—all without manually wrestling with the AWS Console or writing CloudFormation/Terraform.

Features

• ⚡ Zero-Fuss Setup: Interactive prompt initializes your project, VPC settings, and resource sizing.
• 🐳 Automated Deployments: Builds and pushes your local Docker image to AWS ECR and registers job definitions.
• ⏱️ Flexible Execution: Trigger ad-hoc runs with custom JSON payloads or create recurring cron tasks.
• 🪵 Built-in Logging: Stream your CloudWatch logs directly to your terminal.
• 🧹 One-Command Cleanup: Tear down all provisioned Batch and ECR resources cleanly.

Prerequisites

Before using RED, ensure you have:

• macOS (currently optimized for Mac environments)
• Python 3.12+
• Docker Desktop installed and running
• AWS CLI configured locally (aws configure) with permissions for ECR, AWS Batch, IAM, and CloudWatch.

Installation

Install the CLI directly via pip:

pip install red-cli

Verify installation:

red --help

Quickstart in 5 Minutes

1. Initialize your project

Run the interactive setup in your application folder:

red init

This generates a starter Dockerfile, main.py, and a .red configuration file containing your infrastructure defaults.

2. Deploy infrastructure & image

Build your container, push it to ECR, and configure AWS Batch:

red deploy

3. Run a job

Trigger an immediate job execution:

red run --payload '{"action": "process_records", "batch_size": 100}'

4. Tail the logs

Stream output from the latest run:

red log --latest

5. Tear down (when finished)

Destroy all provisioned AWS Batch and ECR resources:

red kill

CLI Reference

red init

Runs an interactive wizard to configure compute sizing (vCPU, memory, timeout), VPC subnets, and security groups.

red init

red deploy

Builds your local Docker container, pushes it to your dedicated ECR repo, and registers/updates the AWS Batch job definition.

red deploy

red run

Triggers an immediate batch job or schedules a recurring task.

Examples:

# Run immediately with default payload
red run

# Run with a custom payload
red run --payload '{"file": "data.csv"}'

# Schedule as a recurring cron job
red run --cron
# Prompt will ask for: Schedule name, Cron expression (e.g. cron(0 12 * * ? *))

red log

Fetch CloudWatch execution logs for your jobs.

# Interactive selection menu of past runs
red log

# Directly stream the latest run
red log --latest

red cron

View or remove scheduled cron triggers.

# List all active schedules
red cron

# Delete a schedule
red cron --delete

red kill

Deconstructs provisioned AWS infrastructure to avoid unintended costs.

# Delete all project resources (Batch compute environment, job definitions, ECR repo)
red kill

# Delete only a specific cron schedule
red kill --schedule "daily-sync-job"

Configuration (.red)

Your project setup is saved in a .red JSON file in the project root. You can edit this file manually to tweak sizing or container properties before running red deploy.

Example .red File

{
  "Name": "data-processor",
  "Arch": "arm64",
  "Cpu": 2,
  "MemorySize": 4096,
  "StorageSize": 30,
  "Timeout": 60,
  "assignPublicIp": "ENABLED",
  "VPC": {
    "SubnetIds": ["subnet-0123456789abcdef0"],
    "SecurityGroupIds": ["sg-0123456789abcdef0"]
  },
  "Envs": {
    "ENVIRONMENT": "production",
    "API_SECRET": "ssmParam::app/production/api_secret"
  },
  "BuildContext": ".",
  "DockerfilePath": "Dockerfile",
  "ImageOverride": null,
  "IamPolicy": {},
  "ContainerProperties": {}
}

Configuration Options

Roadmap

• Interactive terminal session into active running jobs (red sh via AWS SSM Session Manager).