Arc Deploy CLI

A unified CLI tool for building and deploying Docker services to the Deploy Controller. Supports both single-service and monorepo architectures with configuration-driven deployments.

Features

• Single Service & Monorepo Support: Deploy one service or manage multiple services from a single configuration
• Configuration Inheritance: Shared settings via common section in monorepo configs
• Unique Image Tagging: Automatic tag generation using Git SHA and timestamp
• Flexible Deployment Options: Build only, build+push, or full deployment workflow
• Pre-build Hooks: Run custom commands before docker build
• Real-time Monitoring: Track deployment progress and status

📚 Documentation

Full documentation is available in the docs/ directory or served via MkDocs:

• Overview - Installation and basic usage
• Monorepo Guide - Configuring monorepo deployments
• Publishing Guide - How to publish the CLI package
• Package Info - Package structure and metadata

🚀 Quick Start

Installation

# Install via pip
pip install arc-deploy

# Or using uv
uv pip install arc-deploy

Single Service Configuration

Create deploy.yaml in your project root:

service_name: my_service
ecr_registry: 123.dkr.ecr.us-west-2.amazonaws.com
deploy_controller_url: https://deploy.example.com
aws_region: us-west-2

build:
  dockerfile: Dockerfile
  context: .
  build_args:
    NODE_ENV: production
  pre_commands:
    - pnpm install
    - pnpm run build

Deploy:

export WEBHOOK_TOKEN="your-token"
arc-deploy build-and-deploy --env test

Monorepo Configuration

Create deploy.yaml at repository root:

common:
  ecr_registry: 123.dkr.ecr.us-west-2.amazonaws.com
  deploy_controller_url: https://deploy.example.com
  aws_region: us-west-2

services:
  # 简化版本：不指定 service_name，使用 key 作为默认值
  api:
    build: { context: services/api }
  worker:
    build: { context: services/worker }
  
  # 完整版本：指定不同的 service_name（用于不同的 Docker 服务名）
  api-gateway:
    service_name: arc_api_gateway  # 可选：如果未指定，使用 key (api-gateway)
    build: { context: services/api-gateway }

Deploy:

# List available services
arc-deploy list-services

# Deploy specific service(s)
arc-deploy build-and-deploy --env test --service api
arc-deploy build-and-deploy --env prod --service api,worker

# Deploy all services
arc-deploy build-and-deploy --env test --all

Commands

build-and-deploy

Build Docker image, push to ECR, and deploy via Deploy Controller.

Options:

• --env, -e: Deployment environment (test/prod) - Required
• --config, -c: Configuration file path (default: deploy.yaml)
• --service, -s: Service name(s) for monorepo (comma-separated or multiple flags)
• --all: Deploy all services (monorepo only)
• --tag, -t: Custom image tag (optional, defaults to auto-generated tag)
• --skip-pre-build: Skip build pre-commands
• --skip-push: Build only, skip push and deploy
• --skip-deploy: Build and push only, skip deployment
• --skip-pre-deploy: Deploy without running pre_deploy (for when the job itself is what fails)

Examples:

# Single service
arc-deploy build-and-deploy --env test

# Monorepo - specific service
arc-deploy build-and-deploy --env test --service api

# Monorepo - multiple services
arc-deploy build-and-deploy --env prod --service api,worker

# Build only (no push/deploy)
arc-deploy build-and-deploy --env test --skip-push

# Skip pre-build commands
arc-deploy build-and-deploy --env test --skip-pre-build

validate-config

Validate the deployment configuration file.

Options:

• --config, -c: Configuration file path (default: deploy.yaml)

Example:

arc-deploy validate-config

build-only

Build Docker image only (no push or deploy).

Options:

• --config, -c: Configuration file path (default: deploy.yaml)
• --service, -s: Service name for monorepo
• --tag, -t: Custom image tag (optional, defaults to auto-generated tag)
• --skip-pre-build: Skip build pre-commands

Examples:

# Single service
arc-deploy build-only

# Monorepo
arc-deploy build-only --service api

# With custom tag
arc-deploy build-only --tag v1.0.0

# Skip pre-build commands
arc-deploy build-only --skip-pre-build

list-services

List all services in a monorepo configuration.

Options:

• --config, -c: Configuration file path (default: deploy.yaml)

Example:

arc-deploy list-services

Environment Variables

• WEBHOOK_TOKEN: Bearer token for Deploy Controller webhook authentication (required for deployments)
• AWS_PROFILE: AWS profile name (or use standard AWS environment variables)
• AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY: AWS credentials (if not using profile)

Configuration Reference

For monorepo configurations, see the Monorepo Guide for details on common and services sections.

Examples

Example configurations are available in the examples/ directory:

• arc-nodejs-service.yaml - Single service example
• arc-agent-gateway.yaml - Single service example
• monorepo/deploy.yaml - Basic monorepo example
• monorepo/deploy-fullstack.yaml - Fullstack app example

Development

For local development, install in editable mode:

cd cli
uv pip install -e .

License

MIT License - see LICENSE file for details.