arc-deploy 0.1.14
Unified deployment CLI tool for Docker Swarm with monorepo support
License: MIT
Requires Python: >=3.8
Keywords: cicd, cli, deployment, devops, docker, monorepo, swarm

# 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](docs/cli/index.md) - Installation and basic usage
- [Monorepo Guide](docs/cli/monorepo.md) - Configuring monorepo deployments
- [Publishing Guide](docs/cli/publishing.md) - How to publish the CLI package
- [Package Info](docs/cli/package.md) - Package structure and metadata

## 🚀 Quick Start

### Installation

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

```yaml
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**:

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

### Monorepo Configuration

Create `deploy.yaml` at repository root:

```yaml
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**:

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

**Examples**:
```bash
# 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**:
```bash
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**:
```bash
# 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**:
```bash
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

| Field | Description | Required |
|-------|-------------|----------|
| `service_name` | Service name in Deploy Controller | Yes |
| `ecr_registry` | ECR repository URL | Yes |
| `deploy_controller_url` | Base URL of Deploy Controller | Yes |
| `aws_region` | AWS region for ECR | Yes |
| `image_name` | Docker image name (defaults to `service_name`) | No |
| `build.dockerfile` | Path to Dockerfile (default: `Dockerfile`) | No |
| `build.context` | Build context path (default: `.`) | No |
| `build.build_args` | Dictionary of build arguments | No |
| `build.pre_commands` | Pre-build commands (string or list) | No |

For monorepo configurations, see the [Monorepo Guide](docs/cli/monorepo.md) 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:

```bash
cd cli
uv pip install -e .
```

## License

MIT License - see [LICENSE](LICENSE) file for details.