Metadata-Version: 2.4
Name: aws-red
Version: 3.0.1
Summary: Automates the heavy lifting of running containerized jobs on AWS Batch
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.35.16
Requires-Dist: rich>=13.8.1
Requires-Dist: typer>=0.12.5
Requires-Dist: sh>=2.0.7
Requires-Dist: questionary>=2.1.1


<div align="center">

  <img src="https://rowlinsonmike.com/red.png" alt="RED Logo" width="180" />

  # RED

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

  <br />

  <img src="https://rowlinsonmike.com/red-demo.gif" alt="Red Demo" width="750" />

</div>

---

<div align="center">
  <img src="image.png" alt="RED Logo" width="160" style="border-radius: 50%;">
  <h1>RED</h1>
  <p><strong>Really Easy Deployments</strong></p>
  <p>Deploy containerized tasks and scheduled batch workloads to AWS Batch in seconds.</p>

  [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
  [![Platform](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://apple.com)
</div>

---

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:

```bash
pip install red-cli

```

Verify installation:

```bash
red --help

```

---

## Quickstart in 5 Minutes

### 1. Initialize your project

Run the interactive setup in your application folder:

```bash
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:

```bash
red deploy

```

### 3. Run a job

Trigger an immediate job execution:

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

```

### 4. Tail the logs

Stream output from the latest run:

```bash
red log --latest

```

### 5. Tear down (when finished)

Destroy all provisioned AWS Batch and ECR resources:

```bash
red kill

```

---

## CLI Reference

### `red init`

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

```bash
red init

```

### `red deploy`

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

```bash
red deploy

```

### `red run`

Triggers an immediate batch job or schedules a recurring task.

| Flag | Short | Description | Default |
| --- | --- | --- | --- |
| `--payload` | `-p` | JSON string passed to the container | `{}` |
| `--cron` | `-c` | Interactive prompt to register as a recurring cron schedule | Off |

**Examples:**

```bash
# 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.

| Flag | Short | Description |
| --- | --- | --- |
| `--latest` | `-l` | Immediately tail the most recent job run |

```bash
# Interactive selection menu of past runs
red log

# Directly stream the latest run
red log --latest

```

### `red cron`

View or remove scheduled cron triggers.

| Flag | Short | Description |
| --- | --- | --- |
| `--delete` | `-d` | Interactively select and remove existing schedules |

```bash
# List all active schedules
red cron

# Delete a schedule
red cron --delete

```

### `red kill`

Deconstructs provisioned AWS infrastructure to avoid unintended costs.

| Flag | Short | Description |
| --- | --- | --- |
| `--schedule` | `-s` | Delete only a specific cron schedule by name |

```bash
# 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

```json
{
  "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

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `Name` | `string` | *(Folder name)* | Base name applied to all AWS resources (alphanumeric only). |
| `Arch` | `string` | `x86_64` | `x86_64` or `arm64`. Choose `arm64` if building on Apple Silicon. |
| `Cpu` | `number` | `1` | Allotted vCPUs ([valid Batch values](https://docs.aws.amazon.com/batch/latest/APIReference/API_ResourceRequirement.html)). |
| `MemorySize` | `number` | `2048` | Memory allotment in MiB. |
| `StorageSize` | `number` | `21` | Ephemeral scratch storage in GiB (Range: `21` - `200`). |
| `Timeout` | `number` | `1` | Maximum runtime in minutes before the job is terminated (Max: `10000`). |
| `assignPublicIp` | `string` | `DISABLED` | `ENABLED` or `DISABLED`. Set to `ENABLED` if subnets lack a NAT gateway. |
| `VPC` | `object` | Required | Array of `SubnetIds` and `SecurityGroupIds`. Subnets must have egress access. |
| `Envs` | `object` | `{}` | Key/value environment variables. Prefix value with `ssmParam::` to resolve AWS SSM parameters. |
| `BuildContext` | `string` | `.` | Directory context passed to Docker build. |
| `DockerfilePath` | `string` | `Dockerfile` | Relative path to the project Dockerfile. |
| `ImageOverride` | `string` | `null` | Provide an existing ECR URI to skip building locally. |
| `IamPolicy` | `object` | `{}` | Custom IAM policy block appended to the job task execution role. |
| `ContainerProperties` | `object` | `{}` | Pass raw overrides to ECS/Batch task definitions. |

---

## Roadmap

* [ ] Interactive terminal session into active running jobs (`red sh` via AWS SSM Session Manager).
