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:

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

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:

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

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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

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

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

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

docker login registry.home.deepblack.cloud

Out of Disk Space

Clean up old images and build cache:

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

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

Example GitHub Actions

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