# Deployment Controller

A self-service deployment platform for Docker Swarm with webhook integration, real-time log streaming, and version management.

## Features

- **Webhook Deployments**: Trigger deployments from CI/CD pipelines via authenticated webhooks
- **Real-time Logs**: Server-Sent Events (SSE) for live deployment log streaming
- **Service Versions**: Track and preserve deployed image tags across stack deployments
- **Rollback Support**: One-click rollback to previous service versions
- **Mock Mode**: Local development without Docker Swarm requirement
- **Web UI**: React dashboard for monitoring services and deployments

## Tech Stack

- **Backend**: FastAPI (Python 3.13), SQLAlchemy, Docker SDK
- **Frontend**: React 19, TypeScript, Vite, TanStack Query, shadcn/ui
- **Package Managers**: uv (backend), pnpm (frontend)
- **Infrastructure**: Docker Swarm, AWS ECR

## Quick Start

### Using Docker Compose (Recommended)

```bash
# Start both backend and frontend
docker-compose up -d

# View logs
docker-compose logs -f backend
docker-compose logs -f frontend
```

**Access the application**:
- Frontend: `http://localhost:5173`
- Backend API: `http://localhost:8000`
- API Docs: `http://localhost:8000/docs`

**Default Credentials**:
- Username: `admin`
- Password: `123456`

### Manual Development

**Backend**:
```bash
cd backend
uv sync                                    # Install dependencies
uv run uvicorn app.main:app --reload      # Start dev server
```

**Frontend**:
```bash
cd frontend
pnpm install                               # Install dependencies
pnpm run dev                               # Start dev server
```

## Environment Configuration

Copy `backend/.env.example` to `backend/.env` and configure:

```bash
# Docker service strategy: "mock" (local dev/testing), "ssh" (remote Swarm via SSH), or "local" (local Docker daemon)
DOCKER_MODE=mock

# SSH host for remote Docker Swarm (required when DOCKER_MODE=ssh)
# SSH_HOST=user@remote-host

# Authentication
ADMIN_USERNAME=admin
ADMIN_PASSWORD=123456
WEBHOOK_TOKEN=your-secure-token

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/deploy_controller
```

## API Usage

### Webhook Deployment

```bash
curl -X POST http://localhost:8000/api/webhooks/deploy \
  -H "Authorization: Bearer dev-token-123" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "arc_nodejs_service",
    "environment": "prod",
    "image_tag": "v1.2.3",
    "triggered_by": "github-actions"
  }'
```

### Get Service Versions

```bash
# For use in deploy scripts
curl http://localhost:8000/api/services/versions?environment=prod
```

## Service Version Management

The Service Versions feature solves the problem of `docker stack deploy` overwriting versions deployed via `docker service update`.

**Workflow**:
1. CI/CD webhook deploys new version → Updates DB
2. Manual stack deploy → Fetches versions from API → Preserves deployed tags

See `CLAUDE.md` for detailed documentation and `examples/deploy.sh` for integration example.

## Production Deployment

1. Build and push Docker images to ECR:
```bash
docker build -t 264778582408.dkr.ecr.us-west-2.amazonaws.com/deploy_controller:latest ./backend
docker build -t 264778582408.dkr.ecr.us-west-2.amazonaws.com/deploy_controller_web:latest ./frontend

aws ecr get-login-password | docker login --username AWS --password-stdin 264778582408.dkr.ecr.us-west-2.amazonaws.com
docker push 264778582408.dkr.ecr.us-west-2.amazonaws.com/deploy_controller:latest
docker push 264778582408.dkr.ecr.us-west-2.amazonaws.com/deploy_controller_web:latest
```

2. Deploy to Docker Swarm cluster with `DOCKER_MODE=local` or `DOCKER_MODE=ssh`

## Documentation

This site contains the documentation for the Deployment Controller CLI.

- **[CLI Overview](cli/index.md)**: Installation and basic usage.
- **[Monorepo Guide](cli/monorepo.md)**: Configuring monorepo deployments.
- **[Publishing Guide](cli/publishing.md)**: How to publish the CLI package.
- **[Package Info](cli/package.md)**: Package structure and metadata.

External documentation files (in the repo):
- `DEPLOYMENT_GUIDE.md`: CI/CD webhook and Docker Stack deployment guide.
- `MIGRATION_GUIDE.md`: Migrating from fixed tags to unique versioned tags.
