chorus-dev-images/DEPLOYMENT.md

# CHORUS Development Images - Deployment Guide

## Quick Start

The images have been created and are ready to use. Here's how to get started:

### 1. Build Images Locally

```bash
cd /home/tony/chorus/project-queues/active/chorus-dev-images

# Build all images
make build-all

# Or build specific images
make build-base
make build-rust
make build-go
# etc.
```

### 2. Test Images

```bash
# Test all images
make test-all

# Or test specific image
make test-base
make test-rust
```

### 3. Push to Registry

```bash
# Push all images to private registry
make push-all
```

## Integration Status

### ✅ Completed

- [x] Repository created on GITEA: https://gitea.chorus.services/tony/chorus-dev-images
- [x] Multi-stage Dockerfile with 7 images
- [x] Comprehensive test suite
- [x] Makefile for local builds
- [x] CI/CD pipeline configuration
- [x] Full documentation (README, USAGE, MAINTENANCE)
- [x] CHORUS engine integration (`pkg/execution/images.go`)
- [x] Automatic language detection and image selection

### 📋 Next Steps

1. **Build All Images**
   ```bash
   cd /home/tony/chorus/project-queues/active/chorus-dev-images
   make build-all  # Takes ~45 minutes for first build
   ```

2. **Push to Registry**
   ```bash
   make push-all
   ```

3. **Configure CI/CD Secrets** (for automated builds)
   - Go to: https://gitea.chorus.services/tony/chorus-dev-images/settings/secrets
   - Add secrets:
     - `REGISTRY_USERNAME`: Your registry username
     - `REGISTRY_PASSWORD`: Your registry password

4. **Verify CHORUS Integration**
   ```bash
   cd /home/tony/chorus/project-queues/active/CHORUS

   # Run Go tests
   make test

   # Or manual test
   go run cmd/chorus-agent/main.go --test-image-selection
   ```

## Usage in CHORUS Agents

Once images are pushed to the registry, CHORUS agents will automatically:

1. **Detect task language** from:
   - Explicit `language` field in task context
   - Repository URL patterns
   - Task description keywords

2. **Select appropriate image**:
   - `chorus/rust-dev` for Rust projects
   - `chorus/go-dev` for Go projects
   - `chorus/python-dev` for Python projects
   - `chorus/node-dev` for Node.js/TypeScript projects
   - `chorus/java-dev` for Java projects
   - `chorus/cpp-dev` for C/C++ projects
   - `chorus/base` as fallback

3. **Use standardized workspace**:
   - `/workspace/input` - Read-only source code
   - `/workspace/data` - Working directory for builds
   - `/workspace/output` - Deliverables and artifacts

## Example Agent Task

```go
task := &TaskExecutionRequest{
    ID: "fix-rust-bug",
    Description: "Fix compilation error in Rust project",
    Context: map[string]interface{}{
        "repository_url": "https://github.com/user/my-rust-app",
    },
}

// Engine automatically selects chorus/rust-dev:latest
result := engine.ExecuteTask(ctx, task)
```

## Manual Testing

### Test Base Image

```bash
docker run -it --rm \
  registry.home.deepblack.cloud/chorus/base:latest \
  bash
```

### Test Rust Environment

```bash
docker run -it --rm \
  -v $(pwd)/my-rust-project:/workspace/input:ro \
  registry.home.deepblack.cloud/chorus/rust-dev:latest \
  bash -c "cd /workspace/input && cargo build"
```

### Test Python Environment

```bash
docker run -it --rm \
  -v $(pwd)/my-python-project:/workspace/input:ro \
  registry.home.deepblack.cloud/chorus/python-dev:latest \
  bash -c "cd /workspace/input && uv sync && uv run pytest"
```

## Monitoring

### Check Build Status

- Automated builds: https://gitea.chorus.services/tony/chorus-dev-images/actions
- Weekly security updates: Mondays 2 AM UTC

### Check Image Sizes

```bash
# Local images
docker images | grep chorus

# Expected sizes:
# chorus/base:       ~200MB
# chorus/rust-dev:   ~1.2GB
# chorus/go-dev:     ~600MB
# chorus/python-dev: ~800MB
# chorus/node-dev:   ~700MB
# chorus/java-dev:   ~1.5GB
# chorus/cpp-dev:    ~900MB
# Total:             ~5GB (with layer sharing)
```

## Troubleshooting

### Images Not Found

If agents can't find images:

1. Ensure images are pushed to registry:
   ```bash
   docker push registry.home.deepblack.cloud/chorus/base:latest
   ```

2. Verify registry is accessible:
   ```bash
   docker pull registry.home.deepblack.cloud/chorus/base:latest
   ```

3. Check CHORUS engine configuration

### Build Failures

If builds fail:

1. Check Docker disk space: `docker system df`
2. Clean up if needed: `docker system prune -a`
3. Check network connectivity to Debian repos
4. Review build logs for specific errors

### Test Failures

If tests fail:

1. Run individual test: `bash tests/test-<image>.sh`
2. Check tool versions in Dockerfile
3. Verify tool installation succeeded

## Maintenance

### Updating Tool Versions

See [MAINTENANCE.md](docs/MAINTENANCE.md) for detailed procedures.

### Weekly Updates

Images automatically rebuild weekly to incorporate security updates. No action required.

### Manual Rebuild

For urgent security updates:

1. Go to https://gitea.chorus.services/tony/chorus-dev-images/actions
2. Click "Build and Push Development Images"
3. Click "Run workflow"
4. Check "Force rebuild all images"

## Performance Tips

### Speed Up Builds

1. **Use BuildKit**: Already enabled by default
2. **Cache layers**: First build takes ~45min, subsequent builds ~5-10min
3. **Build order**: Base image must build first, others can parallelize

### Speed Up Agent Tasks

1. **Pre-pull images** on agent nodes:
   ```bash
   docker pull registry.home.deepblack.cloud/chorus/rust-dev:latest
   docker pull registry.home.deepblack.cloud/chorus/go-dev:latest
   docker pull registry.home.deepblack.cloud/chorus/python-dev:latest
   ```

2. **Use persistent volumes** for package caches:
   ```bash
   docker volume create cargo-cache
   docker volume create go-cache
   docker volume create pip-cache
   ```

## Resources

- **Repository**: https://gitea.chorus.services/tony/chorus-dev-images
- **Registry**: registry.home.deepblack.cloud/chorus
- **Documentation**: [README.md](README.md), [USAGE.md](docs/USAGE.md), [MAINTENANCE.md](docs/MAINTENANCE.md)
- **CHORUS Integration**: `/home/tony/chorus/project-queues/active/CHORUS/pkg/execution/images.go`

## Support

For issues or questions:
- Create issue: https://gitea.chorus.services/tony/chorus-dev-images/issues
- Check documentation: [docs/](docs/)
- Review tests: [tests/](tests/)