chorus-dev-images/README.md

# CHORUS Development Images

Official Docker images for CHORUS autonomous agent development environments.

[![Build Status](https://gitea.chorus.services/tony/chorus-dev-images/actions/workflows/build-and-push.yml/badge.svg)](https://gitea.chorus.services/tony/chorus-dev-images/actions)

## Overview

CHORUS Development Images provide standardized, pre-configured development environments for autonomous agents. Each image follows a consistent workspace structure and includes language-specific toolchains optimized for agent-driven software development.

## Available Images

| Image | Base | Approx Size | Key Tools |
|-------|------|-------------|-----------|
| `chorus/base` | Debian Bookworm | ~200MB | git, curl, build-essential, vim, jq |
| `chorus/rust-dev` | base | ~1.2GB | rustc 1.77+, cargo, clippy, rustfmt, ripgrep |
| `chorus/go-dev` | base | ~600MB | go1.22, gopls, delve, staticcheck, golangci-lint |
| `chorus/python-dev` | base | ~800MB | python3.11, uv, ruff, black, pytest, mypy |
| `chorus/node-dev` | base | ~700MB | node20, pnpm, yarn, typescript, eslint, prettier |
| `chorus/java-dev` | base | ~1.5GB | openjdk-17, maven, gradle |
| `chorus/cpp-dev` | base | ~900MB | gcc, g++, clang, cmake, ninja, gdb, valgrind |

**Total storage:** ~5GB for all images (with layer sharing)

## Quick Start

### Pull an Image

```bash
docker pull registry.home.deepblack.cloud/chorus/rust-dev:latest
```

### Run Interactive Shell

```bash
docker run -it --rm \
  -v $(pwd):/workspace/input:ro \
  registry.home.deepblack.cloud/chorus/rust-dev:latest
```

### Execute Specific Command

```bash
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  -v $(pwd)/output:/workspace/output \
  registry.home.deepblack.cloud/chorus/rust-dev:latest \
  cargo build --release
```

## Workspace Structure

All images use a standardized three-directory workspace layout:

```
/workspace/
├── input/   - Task requirements, repository checkout (typically read-only)
├── data/    - Working directory for builds, compilation, temporary files
└── output/  - Deliverables, artifacts, reports, patches
```

**Environment Variables:**
- `WORKSPACE_ROOT=/workspace`
- `WORKSPACE_INPUT=/workspace/input`
- `WORKSPACE_DATA=/workspace/data` (default working directory)
- `WORKSPACE_OUTPUT=/workspace/output`

## Image Details

### Base Image (`chorus/base`)

Foundation for all language-specific images with:
- Debian Bookworm (stable)
- Essential development tools
- Git with LFS support
- Standardized workspace structure
- Non-root `chorus` user (UID 1000)

### Rust Development (`chorus/rust-dev`)

- **Toolchain:** Stable Rust with rustup
- **Components:** rustfmt, clippy, rust-analyzer
- **Tools:** cargo-edit, cargo-audit, cargo-watch, ripgrep, fd-find
- **Libraries:** libssl-dev, libpq-dev, libsqlite3-dev

### Go Development (`chorus/go-dev`)

- **Version:** Go 1.22.2
- **Tools:** gopls (LSP), delve (debugger), staticcheck, golangci-lint
- **Environment:** GOROOT, GOPATH pre-configured

### Python Development (`chorus/python-dev`)

- **Version:** Python 3.11
- **Package Managers:** uv, pip-tools
- **Linters:** ruff, black, pylint, mypy
- **Testing:** pytest, pytest-cov, pytest-asyncio
- **REPL:** ipython

### Node.js Development (`chorus/node-dev`)

- **Version:** Node 20 LTS
- **Package Managers:** npm, pnpm, yarn
- **TypeScript:** Full TypeScript support
- **Tools:** eslint, prettier, nodemon, pm2

### Java Development (`chorus/java-dev`)

- **JDK:** OpenJDK 17
- **Build Tools:** Maven, Gradle
- **Pre-configured:** Maven local repository

### C/C++ Development (`chorus/cpp-dev`)

- **Compilers:** gcc, g++, clang
- **Build Systems:** cmake, ninja, autotools
- **Libraries:** boost
- **Debug Tools:** gdb, valgrind
- **Documentation:** doxygen

## Building Locally

### Prerequisites

- Docker 20.10+
- GNU Make

### Build Commands

```bash
# Build all images
make build-all

# Build specific image
make build-rust
make build-go
make build-python
make build-node
make build-java
make build-cpp

# Run tests
make test-all

# Push to registry (after building and testing)
make push-all

# Clean local images
make clean
```

## Versioning

Images are tagged with:
- **`latest`** - Most recent stable build
- **`<version>`** - Semantic version (e.g., `1.0.0`)

### Version History

- **1.0.0** (2025-09-30) - Initial release
  - Base Debian Bookworm image
  - 6 language-specific development environments
  - Standardized workspace structure

## Automated Builds

Images automatically rebuild:
- On changes to image source files (push to `main`)
- Weekly security update schedule (Mondays 2 AM UTC)
- Manual workflow dispatch

## Integration with CHORUS

The CHORUS execution engine automatically selects appropriate images based on task language:

```go
// Example: CHORUS engine auto-selects image
task := &TaskExecutionRequest{
    Description: "Fix Rust compilation error",
}
// Engine detects "Rust" and uses chorus/rust-dev:latest
```

## Contributing

### Adding a New Tool

1. Edit `images/base/Dockerfile`
2. Add tool installation to appropriate image stage
3. Update tests in `tests/test-<image>.sh`
4. Update this README
5. Submit pull request

### Reporting Issues

Please report issues at: https://gitea.chorus.services/tony/chorus-dev-images/issues

## License

Copyright © 2025 CHORUS Services. All rights reserved.

## Links

- **Source:** https://gitea.chorus.services/tony/chorus-dev-images
- **Registry:** registry.home.deepblack.cloud/chorus
- **Documentation:** [docs/](docs/)
- **Main Project:** https://gitea.chorus.services/tony/CHORUS