chorus-dev-images/docs/USAGE.md

# CHORUS Development Images - Usage Guide

## Basic Usage Patterns

### Pattern 1: Interactive Development

Use when you need to explore a codebase or debug interactively:

```bash
# Start interactive shell in Rust environment
docker run -it --rm \
  -v /path/to/repository:/workspace/input \
  -v /path/to/output:/workspace/output \
  registry.home.deepblack.cloud/chorus/rust-dev:latest
```

Inside the container:
```bash
cd /workspace/input
cargo build
cargo test
# Copy results to output
cp target/release/binary /workspace/output/
```

### Pattern 2: Single Command Execution

Use for automated agent tasks:

```bash
# Build Rust project
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  -v $(pwd)/output:/workspace/output \
  registry.home.deepblack.cloud/chorus/rust-dev:latest \
  bash -c "cd /workspace/input && cargo build --release && cp target/release/* /workspace/output/"
```

### Pattern 3: Multi-Step Workflow

Use for complex build pipelines:

```bash
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  -v $(pwd)/output:/workspace/output \
  registry.home.deepblack.cloud/chorus/python-dev:latest \
  bash -c "
    cd /workspace/input
    uv sync
    uv run pytest
    uv run ruff check
    uv run mypy .
    cp -r dist/* /workspace/output/
  "
```

## Language-Specific Examples

### Rust

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

**Format and Lint:**
```bash
docker run --rm \
  -v $(pwd):/workspace/input \
  registry.home.deepblack.cloud/chorus/rust-dev:latest \
  bash -c "cd /workspace/input && cargo fmt && cargo clippy -- -D warnings"
```

### Go

**Build Binary:**
```bash
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  -v $(pwd)/bin:/workspace/output \
  registry.home.deepblack.cloud/chorus/go-dev:latest \
  bash -c "cd /workspace/input && go build -o /workspace/output/app"
```

**Run Tests:**
```bash
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  registry.home.deepblack.cloud/chorus/go-dev:latest \
  bash -c "cd /workspace/input && go test ./..."
```

### Python

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

**Lint and Type Check:**
```bash
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  registry.home.deepblack.cloud/chorus/python-dev:latest \
  bash -c "cd /workspace/input && ruff check . && mypy ."
```

### Node.js

**Install and Build:**
```bash
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  -v $(pwd)/dist:/workspace/output \
  registry.home.deepblack.cloud/chorus/node-dev:latest \
  bash -c "cd /workspace/input && npm install && npm run build && cp -r dist/* /workspace/output/"
```

**Run Tests:**
```bash
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  registry.home.deepblack.cloud/chorus/node-dev:latest \
  bash -c "cd /workspace/input && npm install && npm test"
```

### Java

**Maven Build:**
```bash
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  -v $(pwd)/target:/workspace/output \
  registry.home.deepblack.cloud/chorus/java-dev:latest \
  bash -c "cd /workspace/input && mvn clean package && cp target/*.jar /workspace/output/"
```

**Gradle Build:**
```bash
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  -v $(pwd)/build:/workspace/output \
  registry.home.deepblack.cloud/chorus/java-dev:latest \
  bash -c "cd /workspace/input && gradle build && cp build/libs/*.jar /workspace/output/"
```

### C/C++

**CMake Build:**
```bash
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  -v $(pwd)/build:/workspace/output \
  registry.home.deepblack.cloud/chorus/cpp-dev:latest \
  bash -c "
    cd /workspace/data
    cmake /workspace/input
    make
    cp bin/* /workspace/output/
  "
```

## Advanced Usage

### Preserving Build Cache

Mount a volume for package caches to speed up subsequent builds:

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

**Python:**
```bash
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  -v pip-cache:/home/chorus/.cache/pip \
  registry.home.deepblack.cloud/chorus/python-dev:latest \
  bash -c "cd /workspace/input && pip install -r requirements.txt"
```

### Setting Environment Variables

```bash
docker run --rm \
  -v $(pwd):/workspace/input:ro \
  -e DATABASE_URL=postgres://localhost/db \
  -e API_KEY=secret \
  registry.home.deepblack.cloud/chorus/rust-dev:latest \
  bash -c "cd /workspace/input && cargo test"
```

### Resource Limits

```bash
docker run --rm \
  --memory="2g" \
  --cpus="2.0" \
  -v $(pwd):/workspace/input:ro \
  registry.home.deepblack.cloud/chorus/rust-dev:latest \
  bash -c "cd /workspace/input && cargo build --release"
```

### Network Access Control

```bash
# No network access
docker run --rm --network=none \
  -v $(pwd):/workspace/input:ro \
  registry.home.deepblack.cloud/chorus/rust-dev:latest \
  bash -c "cd /workspace/input && cargo build --offline"

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

## Troubleshooting

### Permission Issues

If you encounter permission errors with output files:

```bash
# Run with matching UID
docker run --rm \
  --user $(id -u):$(id -g) \
  -v $(pwd):/workspace/input \
  -v $(pwd)/output:/workspace/output \
  registry.home.deepblack.cloud/chorus/rust-dev:latest \
  bash -c "cd /workspace/input && cargo build"
```

### Image Not Found

Ensure you're logged into the registry:

```bash
docker login registry.home.deepblack.cloud
```

### Out of Disk Space

Clean up old images and build cache:

```bash
docker system prune -a
```

## Best Practices

1. **Use Read-Only Input**: Mount source code as read-only (`:ro`) to prevent accidental modifications
2. **Separate Output**: Use dedicated output directory for build artifacts
3. **Cache Dependencies**: Mount package cache volumes for faster rebuilds
4. **Limit Resources**: Set memory and CPU limits for production use
5. **Version Pin**: Use specific version tags (e.g., `1.0.0`) in production, not `latest`

## Integration with CI/CD

### Example GitLab CI

```yaml
test:
  image: registry.home.deepblack.cloud/chorus/rust-dev:1.0.0
  script:
    - cargo test
  artifacts:
    paths:
      - target/release/
```

### Example GitHub Actions

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: registry.home.deepblack.cloud/chorus/rust-dev:1.0.0
    steps:
      - uses: actions/checkout@v4
      - run: cargo test
```