Docker Development Guide
Docker Development Guide
Target Audience: Developers, DevOps engineers, AI agents Status: Production Ready
Table of Contents
- Overview
- Quick Start
- Local Development Environment
- Docker Development Reality Check
- AI Agent Workflow
- Troubleshooting
Overview
What This Guide Covers
Complete local development environment for CODITECT using Docker, including:
- Ubuntu 22.04 LTS base image with XFCE desktop
- zsh + oh-my-zsh (jonathan theme) pre-configured
- Claude Code (npm version) pre-installed
- CODITECT framework with symlinks
- VNC access for desktop environment
- PostgreSQL, Redis (optional services)
Why Docker Development?
- Consistency: Identical environment across all machines
- Isolation: No pollution of host system
- Reproducibility: Exact development environment documented
- Onboarding: New developers productive in <10 minutes
- Testing: Test deployment configurations locally
Quick Start
One-Command Setup
# One-command setup (recommended)
./submodules/core/coditect-core/scripts/start-dev-container.sh
# With options
./submodules/core/coditect-core/scripts/start-dev-container.sh --shell # Open shell after start
./submodules/core/coditect-core/scripts/start-dev-container.sh --vnc # Connect VNC after start
./submodules/core/coditect-core/scripts/start-dev-container.sh --clean --build # Fresh rebuild
Access Options
Terminal Access
docker-compose -f submodules/core/coditect-core/distribution/docker/docker-compose.yml exec coditect zsh
VNC Desktop Access
- Address:
vnc://localhost:5901 - Password:
coditect - macOS:
open vnc://localhost:5901 - Windows/Linux: Use VNC Viewer
Web Services
- http://localhost:3000 - Claude Code / Dev server
- http://localhost:8000 - Dev server 2
Local Development Environment
Docker Compose Setup
Base Configuration
# docker-compose.yml
services:
coditect:
image: coditect-dev:latest
container_name: coditect-dev
ports:
- "5901:5901" # VNC
- "3000:3000" # Claude Code / Dev
- "8000:8000" # Dev server 2
volumes:
- ./:/app
- ~/.ssh:/home/developer/.ssh:ro
- dev-projects:/home/developer/projects
environment:
- DISPLAY=:1
- VNC_PASSWORD=coditect
What's Included
| Component | Version | Purpose |
|---|---|---|
| Base OS | Ubuntu 22.04 LTS | Long-term support stability |
| Desktop | XFCE + TightVNC | Lightweight GUI environment |
| Shell | zsh + oh-my-zsh (jonathan) | Developer-friendly terminal |
| Claude Code | npm (@anthropic-ai/Claude-code) | AI-assisted development |
| CODITECT | v1.0 + UAF v2.0 | Complete framework |
| Python | 3.10+ | Framework runtime |
| Node.js | 18 LTS | JavaScript runtime |
| Git | Latest | Version control |
Container Names
| Service | Container Name | Purpose |
|---|---|---|
| Main | coditect-dev | Primary development environment |
| PostgreSQL | coditect-postgres | Database (optional) |
| Redis | coditect-redis | Cache/queue (optional) |
Mounted Paths
| Host Path | Container Path | Purpose |
|---|---|---|
./ (CODITECT-core root) | /app | Live code mounting |
./ (CODITECT-core root) | /home/developer/coditect-core | Alternate access |
~/.ssh | /home/developer/.ssh | Git authentication (read-only) |
dev-projects (volume) | /home/developer/projects | Persistent user projects |
Hot-reload enabled
- Changes to
.coditect/directory → immediate container update - No container restart needed for code changes
- CODITECT components available via symlinks
Testing Pattern
When creating deployment-related components, test in container first
# Step 1: Start container
docker-compose up -d
# Step 2: Access container
docker-compose exec coditect zsh
# Step 3: Inside container, test component
cd /app
python3 scripts/your-new-component.py --test
# Step 4: Verify results
# Check output, logs, behavior
# Step 5: Exit container
exit
# Step 6: Commit tested component
git add scripts/your-new-component.py
git commit -m "feat: Add deployment component (tested in container)"
Documentation: docs/05-deployment/LOCAL-DEVELOPMENT-Docker.md
Docker Development Reality Check
What Works
✅ Working Features
-
Docker Compose configuration exists
- Complete Docker-compose.yml
- Multi-service orchestration
- Volume management
-
Container images build successfully
- Dockerfile validated
- All dependencies installed
- CODITECT framework integrated
-
Local development environment functional
- Claude Code operational
- zsh + oh-my-zsh configured
- CODITECT components accessible
-
Hot-reload for .CODITECT directory
- Live mounting working
- Changes reflected immediately
- No restart needed
What Requires Manual Steps
⚠️ Manual Intervention Required
-
Initial container build (5-10 minutes)
# First-time build
docker-compose build
# Expected: 5-10 minute wait -
Service configuration (PostgreSQL, Redis)
# If using database services
docker-compose up -d postgres redis
# Configure connection strings in .env -
Environment variable setup
# Copy and configure
cp .env.example .env
# Edit .env with appropriate values -
Network configuration for multi-container setups
# Create custom network if needed
docker network create coditect-network
# Update docker-compose.yml accordingly
AI Agent Workflow
For Docker Tasks
AI agents should follow this workflow
1. Check existing configuration
# Read docker-compose.yml
Read(file_path="distribution/docker/docker-compose.yml")
# Read Dockerfile
Read(file_path="distribution/docker/Dockerfile")
2. Verify container status
# Use Bash to check running containers
Bash(command="docker ps | grep coditect", description="Check if coditect containers are running")
3. Request human intervention
When initial builds or infrastructure changes are needed, provide clear instructions:
🐳 DOCKER ENVIRONMENT SETUP REQUIRED
I need to test the deployment configuration in a container environment.
Please run these commands:
Build and start containers
cd /Users/halcasteel/PROJECTS/coditect-rollout-master/submodules/core/coditect-core docker-compose up -d
Verify container running
docker ps | grep coditect-dev
Access container for testing
docker-compose exec coditect zsh
Once inside the container, I can test:
- Component activation scripts
- CI/CD workflow simulation
- Deployment configuration validation
Alternative: I can create test scripts that simulate container environment locally.
4. Test in container
Once access is granted:
# Inside container
cd /app
# Test component
python3 scripts/component-to-test.py --test
# Verify behavior
# Check logs, output, side effects
5. Document setup
Update deployment documentation with findings:
## Container Testing Results
**Date:** 2025-12-04
**Component:** scripts/component-to-test.py
**Container:** coditect-dev
**Result:** PASS / FAIL
**Observations:**
- [List any issues or successful behaviors]
**Recommendations:**
- [Any configuration changes needed]
Example AI Agent Message for Docker Setup
Template for requesting Docker environment
🐳 DOCKER ENVIRONMENT SETUP REQUIRED
**Purpose:** Test [component/feature] in containerized environment
**Prerequisites:**
- Docker installed and running
- Docker Compose v2+
- At least 4GB RAM available
**Setup Commands:**
Navigate to coditect-core
cd /Users/halcasteel/PROJECTS/coditect-rollout-master/submodules/core/coditect-core
Build and start containers
docker-compose up -d
Verify services
docker-compose ps
Expected output:
NAME STATUS PORTS
coditect-dev Up 0.0.0.0:5901->5901/tcp, 0.0.0.0:3000->3000/tcp
**Testing Workflow:**
Access container
docker-compose exec coditect zsh
Navigate to test location
cd /app
Run test commands
python3 scripts/[test-script].py --test
Exit container
exit
**Expected Results:**
- Component executes without errors
- Output matches expected behavior
- Configuration validated
**Alternative Approach:**
If Docker setup is not immediately available, I can:
1. Create mock environment configuration
2. Write test scripts with container simulation
3. Document assumptions for future container testing
Troubleshooting
Issue 1: Container Won't Start
Problem: docker-compose up -d fails
Solution
# Check Docker daemon
docker info
# Check compose file syntax
docker-compose config
# Check available resources
docker system df
# Restart Docker daemon (macOS)
# Docker Desktop → Restart
# Restart Docker daemon (Linux)
sudo systemctl restart docker
Issue 2: VNC Connection Refused
Problem: Cannot connect to VNC at localhost:5901
Solution
# Verify port mapping
docker-compose ps
# Check VNC server inside container
docker-compose exec coditect ps aux | grep vnc
# Restart VNC server
docker-compose exec coditect vncserver -kill :1
docker-compose exec coditect vncserver :1 -geometry 1920x1080 -depth 24
Issue 3: Hot-Reload Not Working
Problem: Changes to .coditect/ not reflected in container
Solution
# Verify volume mount
docker inspect coditect-dev | grep Mounts -A 20
# Restart container
docker-compose restart coditect
# Verify mount inside container
docker-compose exec coditect ls -la /app/.coditect
Issue 4: Permission Issues
Problem: Cannot write files inside container
Solution
# Fix ownership (inside container)
docker-compose exec coditect chown -R developer:developer /app
# Or run as root temporarily
docker-compose exec -u root coditect chown -R developer:developer /app
Issue 5: Build Failures
Problem: docker-compose build fails
Solution
# Clean build cache
docker-compose build --no-cache
# Remove orphaned images
docker image prune -a
# Check Dockerfile syntax
docker build -t coditect-dev:test -f distribution/docker/Dockerfile .
# Review build logs
docker-compose build 2>&1 | tee build.log
🔐 License Validation in Containers
Docker containers have hardware fingerprinting limitations - MAC addresses and hostnames change on restart, causing license validation issues.
Solution: Set a stable hardware ID via environment variable:
# docker-compose.yml
environment:
- CODITECT_HARDWARE_ID=docker-dev-${USER:-developer}-main
Full documentation: See LOCAL-DEVELOPMENT-DOCKER.md#-license-validation-in-containers for:
- Authentication options (OAuth, License Key, Org API Key)
- CI/CD pipeline configuration
- Troubleshooting container licensing
- Environment variables reference
Additional Resources
Related Documentation
- Complete Docker Guide - Extended setup instructions (10 minutes)
- CI/CD Deployment Guide - Multi-agent deployment workflow
- Agent Selection for CI/CD - 6-phase deployment process
Docker Configuration Files
Location: submodules/core/coditect-core/distribution/docker/
- Dockerfile - Container image definition
- Docker-compose.yml - Service orchestration
- .dockerignore - Build exclusions
- scripts/start-dev-container.sh - Convenience startup script
Container Management Scripts
Location: submodules/core/coditect-core/scripts/
- start-dev-container.sh - Start development environment
- stop-dev-container.sh - Stop containers cleanly
- restart-dev-container.sh - Restart with reload
- clean-dev-container.sh - Remove containers and volumes
Document Status: Production Ready Last Validation: December 4, 2025 Container Version: CODITECT-dev:latest Next Review: March 2026