diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md new file mode 100644 index 0000000..0dbd816 --- /dev/null +++ b/DEPLOYMENT.md @@ -0,0 +1,263 @@ +# 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-.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/) \ No newline at end of file