Skip to main content

Local Development with Docker CODITECT Environment

Local Development with Docker - CODITECT Environment

Purpose: Complete local development environment using Docker Reading Time: 10 minutes Difficulty: Beginner-friendly

📋 Executive Summary​

Pre-configured Docker environment providing a complete CODITECT development setup with:

  • Ubuntu 22.04 LTS (Jammy Jellyfish) - Long-term support base
  • XFCE Desktop - Lightweight, full-featured desktop environment
  • zsh + oh-my-zsh - Modern shell with jonathan theme
  • Claude Code - npm version pre-installed
  • CODITECT Framework - All components ready to use (see config/component-counts.json)
  • Development Tools - Python, Node.js, Git, and more

Quick Start Time: 5 minutes from zero to fully functional environment

🎯 What You Get​

Installed Software​

CategoryToolsVersion
OSUbuntu LTS22.04 (Jammy)
DesktopXFCE4.16+
Shellzsh + oh-my-zshLatest (jonathan theme)
Pythonpython3, pip, venv3.10+
Node.jsnode, npm18 LTS
AI ToolsClaude CodeLatest (@anthropic-ai/Claude-code)
FrameworkCODITECTv1.0.0 (see config)
Version ControlGit2.34+
Editorsvim, nanoLatest
VNCTightVNC ServerLatest

Pre-configured Features​

  • ✅ Non-root user - 'developer' with sudo access
  • ✅ zsh configured - oh-my-zsh with jonathan theme and useful plugins
  • ✅ CODITECT activated - Components ready to use
  • ✅ VNC access - Remote desktop on port 5901
  • ✅ Persistent storage - Projects and configs preserved
  • ✅ Resource limits - Controlled CPU/memory usage
  • ✅ Health monitoring - Auto-restart on failures

🚀 Quick Start (5 Minutes)​

Prerequisites​

Required​

  • Docker Desktop 20.10+ installed (Download)
  • Docker Compose 2.0+ included with Docker Desktop
  • 8GB+ RAM available for container
  • 20GB+ disk space

Optional​

  • VNC Viewer (RealVNC, TightVNC, or built-in macOS Screen Sharing)
  • Git configured on host machine

Check installation​

docker --version
# Docker version 24.0.0 or higher

docker-compose --version
# Docker Compose version 2.0.0 or higher

Step 1: Clone Repository (1 minute)​

# Clone CODITECT-CORE
git clone https://github.com/az1-ai/coditect-core.git
cd coditect-core/docker

# Or if you already have it:
cd /path/to/coditect-core/docker

Step 2: Build & Start Container (3 minutes)​

# Build and start in detached mode
docker-compose up -d --build

# Output:
# [+] Building 45.2s (25/25) FINISHED
# [+] Running 4/4
#  ✔ Network coditect-network    Created
#  ✔ Volume coditect-dev-home     Created
#  ✔ Volume coditect-dev-projects Created
#  ✔ Container coditect-dev       Started

First build takes 3-5 minutes (downloads Ubuntu, installs packages) Subsequent starts take 5-10 seconds (uses cached image)

Step 3: Access Your Environment (1 minute)​

# Open zsh shell in container
docker-compose exec coditect zsh

# You'll see:
╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║   🚀 CODITECT Development Environment                         ║
║   Ubuntu 22.04 LTS + XFCE + zsh (oh-my-zsh jonathan)        ║
║   Claude Code + CODITECT Framework Ready                     ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

📂 Directories:
   ~/projects/     - Your project workspace
   ~/.coditect/    - CODITECT framework

🔧 Tools installed:
   - Claude Code:  /usr/local/bin/claude-code
   - Python:       Python 3.10.12
   - Node.js:      v18.19.0
   - Git:          git version 2.34.1

🚀 Quick Start:
   cd ~/projects
   claude-code     # Start Claude Code

developer@coditect-dev:~$

Option B: VNC Access (For GUI applications)​

# VNC server is already running on port 5901

# Connect using VNC Viewer:
# Address: localhost:5901
# Password: coditect

# On macOS, you can use Screen Sharing:
open vnc://localhost:5901

Option C: VS Code Remote (If you have Remote Containers extension)​

# Open in VS Code
code --folder-uri="vscode-remote://attached-container+636f64697465637431/home/developer/projects"

🛠️ Development Workflows​

Workflow 1: Working with Claude Code​

# 1. Enter container
docker-compose exec coditect zsh

# 2. Navigate to projects directory
cd ~/projects

# 3. Create or navigate to your project
mkdir my-new-project
cd my-new-project

# 4. Start Claude Code
claude-code

# Claude Code will initialize and you can start working

Workflow 2: Using CODITECT Framework​

# 1. Enter container
docker-compose exec coditect zsh

# 2. Navigate to CODITECT directory
cd ~/coditect-core

# 3. Run init script to activate components
./scripts/init.sh

# 4. Use component activation
python3 scripts/update-component-activation.py list --activated-only

# 5. Start working with activated components
python3 scripts/activate-all-components.py

Workflow 3: Python Development​

# 1. Enter container
docker-compose exec coditect zsh

# 2. Create Python virtual environment
cd ~/projects/my-python-project
python3 -m venv venv
source venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Run your application
python app.py

Workflow 4: Node.js Development​

# 1. Enter container
docker-compose exec coditect zsh

# 2. Navigate to Node project
cd ~/projects/my-node-project

# 3. Install dependencies
npm install

# 4. Run development server
npm run dev

# Server runs on port 3000 (exposed to host)
# Access at: http://localhost:3000

Workflow 5: Git Operations​

# Git is pre-installed and configured to use your host credentials

# 1. Configure git (first time only)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 2. Clone repositories
git clone https://github.com/your-org/your-repo.git

# 3. Work normally
git add .
git commit -m "Your commit message"
git push

📁 Directory Structure​

Inside Container​

/home/developer/
├── .coditect/              # CODITECT framework (symlinked)
│   ├── agents/            # 60 AI agents
│   ├── skills/            # all production skills
│   ├── commands/          # All slash commands
│   └── scripts/           # Automation scripts
├── coditect-core/         # Full CODITECT repository (mounted)
├── projects/              # Your development projects (persistent volume)
├── .zshrc                 # zsh configuration (oh-my-zsh)
├── .vnc/                  # VNC configuration
└── .config/               # Application configs

Persistent Volumes:
- coditect-dev-home        → /home/developer (configs, zsh history)
- coditect-dev-projects    → /home/developer/projects (your work)
- coditect-dev-git-config  → /home/developer/.gitconfig (git settings)

Mounted from Host​

The Docker Compose configuration mounts your host's coditect-core directory into the container at /home/developer/coditect-core. This means:

  • ✅ Changes in container appear on host immediately
  • ✅ Changes on host appear in container immediately
  • ✅ You can use your host IDE (VS Code, etc.) and run code in container
  • ✅ No need to rebuild container for code changes

🎨 Customization​

Change VNC Password​

# 1. Enter container
docker-compose exec coditect zsh

# 2. Set new VNC password
vncpasswd

# 3. Restart VNC server
vncserver -kill :1
vncserver :1 -geometry 1920x1080 -depth 24

Change zsh Theme​

# 1. Enter container
docker-compose exec coditect zsh

# 2. Edit .zshrc
nano ~/.zshrc

# 3. Change theme (line ~11)
# From: ZSH_THEME="jonathan"
# To:   ZSH_THEME="agnoster"  # or any theme you like

# 4. Apply changes
source ~/.zshrc

Available themes: See oh-my-zsh themes

Add zsh Plugins​

# 1. Edit .zshrc
nano ~/.zshrc

# 2. Add plugins to plugins array (line ~73)
plugins=(git docker python npm node kubectl terraform aws)

# 3. Apply changes
source ~/.zshrc

Adjust Resource Limits​

Edit docker-compose.yml:

deploy:
  resources:
    limits:
      cpus: '8'      # Change from 4 to 8
      memory: 16G    # Change from 8G to 16G
    reservations:
      cpus: '4'      # Change from 2 to 4
      memory: 8G     # Change from 4G to 8G

Then restart:

docker-compose down
docker-compose up -d

🔧 Common Operations​

Start/Stop Container​

# Start (if stopped)
docker-compose up -d

# Stop (keeps volumes)
docker-compose stop

# Stop and remove container (keeps volumes)
docker-compose down

# Stop and remove everything (INCLUDING VOLUMES - data loss!)
docker-compose down -v  # ⚠️ WARNING: Deletes all your projects!

View Logs​

# View all logs
docker-compose logs

# Follow logs in real-time
docker-compose logs -f

# View last 50 lines
docker-compose logs --tail=50

# View logs for specific service
docker-compose logs coditect

Restart Container​

# Restart container
docker-compose restart

# Rebuild and restart (after Dockerfile changes)
docker-compose up -d --build

Execute Commands​

# Run single command
docker-compose exec coditect ls -la

# Run command as root
docker-compose exec -u root coditect apt-get update

# Run Python script
docker-compose exec coditect python3 /path/to/script.py

Access as Root​

# Get root shell
docker-compose exec -u root coditect bash

# Install system packages
apt-get update
apt-get install -y package-name

🐛 Troubleshooting​

Issue 1: Container Won't Start​

Symptom​

Error: Cannot start service coditect: driver failed programming external connectivity

Cause: Port 5901 or 3000 already in use

Solution​

# Check what's using the port
lsof -i :5901
lsof -i :3000

# Kill the process or change port in docker-compose.yml
ports:
  - "5902:5901"  # Changed from 5901:5901

Issue 2: VNC Connection Refused​

Symptom: Cannot connect to VNC server

Diagnosis​

# Check if VNC is running
docker-compose exec coditect ps aux | grep vnc

# Check VNC logs
docker-compose exec coditect cat ~/.vnc/*.log

Solution​

# Restart VNC server
docker-compose exec coditect vncserver -kill :1
docker-compose exec coditect vncserver :1 -geometry 1920x1080 -depth 24

Issue 3: Changes Not Persisting​

Symptom: Files disappear after container restart

Cause: Working in non-persistent directory

Solution​

# Always work in persistent directories:
# ✅ /home/developer/projects/     (persistent volume)
# ✅ /home/developer/coditect-core/ (mounted from host)
# ❌ /tmp/                          (NOT persistent)
# ❌ /var/                          (NOT persistent)

# Check your volumes
docker volume ls | grep coditect

Issue 4: Out of Disk Space​

Symptom​

Error: No space left on device

Solution​

# Clean up Docker
docker system prune -a --volumes

# Remove unused images
docker image prune -a

# Check disk usage
docker system df

Issue 5: Slow Performance​

Cause: Insufficient resources allocated

Solution​

  1. Increase Docker Desktop resources:

    • Open Docker Desktop
    • Settings → Resources
    • Increase CPUs to 4-8
    • Increase Memory to 8-16GB
    • Apply & Restart

  2. Adjust container limits in docker-compose.yml (see Customization section)

  3. Use volume caching:

    volumes:
      - ../:/home/developer/coditect-core:cached  # ✅ Already configured

---

## 📊 Resource Usage

### Typical Resource Consumption

| Resource | Idle | Light Use | Heavy Use |
| ---------- | ------ | ----------- | ----------- |
| **CPU** | 5-10% | 25-50% | 80-100% |
| **Memory** | 2-3GB | 4-6GB | 6-8GB |
| **Disk** | 5GB | 10GB | 20GB+ |

### Monitor Resource Usage

```bash
# Real-time stats
docker stats coditect-dev

# Output:
# CONTAINER ID   NAME           CPU %   MEM USAGE / LIMIT   MEM %
# abc123def456   coditect-dev   12.5%   4.2GB / 8GB        52.5%

🔒 Security Considerations​

Best Practices​

  1. Change VNC password immediately after first start

  2. Don't run as root - use the 'developer' user

  3. Keep container updated:

    docker-compose pull
    docker-compose up -d --build

  4. Use secrets for sensitive data:

    # Don't hardcode in docker-compose.yml
    # Use environment files
    docker-compose --env-file .env.production up -d

### Network Security

The container exposes ports:

- `5901` - VNC (password protected)
- `3000` - Development server (for your apps)
- `8000`, `8080` - Additional dev servers

**For production:** Disable VNC, use SSH instead:

```yaml
ports:
  # - "5901:5901"  # Disable VNC
  - "22:22"        # Enable SSH

🚀 Advanced Usage​

Multiple Containers​

Run multiple CODITECT environments for different projects:

# Project 1
cd project1/
docker-compose -p coditect-project1 up -d

# Project 2
cd project2/
docker-compose -p coditect-project2 up -d

# Access Project 1
docker-compose -p coditect-project1 exec coditect zsh

# Access Project 2
docker-compose -p coditect-project2 exec coditect zsh

Docker-in-Docker​

Enable Docker inside the container:

  1. Uncomment in docker-compose.yml:

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

  2. Install Docker CLI in container:

    docker-compose exec -u root coditect bash
    curl -fsSL https://get.docker.com | sh
    usermod -aG docker developer

  3. Restart and test:

    docker-compose restart
    docker-compose exec coditect docker ps

### CI/CD Integration

Use this container in CI/CD pipelines:

```yaml
# .github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: coditect/dev-environment:latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: |
          cd ~/projects
          python3 -m pytest

🔐 License Validation in Containers​

The Problem: Hardware Fingerprinting Limitations​

CODITECT uses hardware fingerprinting to bind licenses to specific machines. This creates challenges in Docker containers because:

  • MAC addresses change on container restart
  • Hostnames are randomly generated by default
  • Machine identifiers aren't stable across container lifecycles
  • Ephemeral containers in CI/CD have no persistent identity

Without intervention, each container restart would appear as a "new device" and consume license activations.

The Solution: Environment Variable Mode​

Set a stable hardware ID via environment variable to bypass automatic fingerprinting:

# Set stable hardware ID for containers
export CODITECT_HARDWARE_ID="docker-dev-<unique-identifier>"

Naming Convention:

  • Local dev: docker-dev-<username>-<project>
  • CI/CD: ci-<org>-<repo>-<runner-id>
  • Team shared: team-<team-name>-<purpose>

Docker Compose Configuration​

# docker-compose.yml
services:
  coditect:
    image: coditect-dev:latest
    environment:
      # Stable hardware ID for license validation
      - CODITECT_HARDWARE_ID=docker-dev-${USER:-developer}-main

      # License server URL (default: https://api.coditect.ai)
      - CODITECT_LICENSE_SERVER_URL=https://api.coditect.ai

      # Optional: Disable telemetry in dev containers
      - CODITECT_TELEMETRY_ENABLED=false
    volumes:
      - ./:/app
      # Mount credentials from host (if using OAuth login)
      - ~/.coditect/credentials.json:/home/developer/.coditect/credentials.json:ro

Authentication Options for Containers​

Option 1: OAuth Login (Interactive Development)​

# Login on host first, then mount credentials
coditect login --provider google

# Credentials stored at ~/.coditect/credentials.json
# Mount into container (see docker-compose.yml above)

Option 2: License Key (Non-Interactive / CI)​

# Set license key directly
export CODITECT_LICENSE_KEY="CODITECT-PILOT-XXXX-XXXX-XXXX"

# Or in docker-compose.yml
environment:
  - CODITECT_LICENSE_KEY=${CODITECT_LICENSE_KEY}

Option 3: Organization API Key (CI/CD Runners)​

# For CI/CD pipelines - use organization API keys
environment:
  - CODITECT_ORG_API_KEY=${CODITECT_ORG_API_KEY}
  - CODITECT_HARDWARE_ID=ci-myorg-myrepo-${CI_RUNNER_ID}

Offline Grace Period​

Containers support the same 72-hour offline grace period as desktop installations:

ScenarioBehavior
Network availableValidates license online, caches result
Network unavailableUses cached validation for up to 72 hours
Cache expired + no networkLicense validation fails
New container + no networkLicense validation fails (no cache)

Best Practice: Ensure first container start has network access to establish initial license cache.

CI/CD Pipeline Example​

# .github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: coditect/dev-environment:latest
    env:
      CODITECT_ORG_API_KEY: ${{ secrets.CODITECT_ORG_API_KEY }}
      CODITECT_HARDWARE_ID: ci-${{ github.repository_owner }}-${{ github.repository }}-${{ github.run_id }}
    steps:
      - uses: actions/checkout@v4
      - name: Verify license
        run: coditect license status
      - name: Run tests
        run: python3 -m pytest

Troubleshooting Container Licensing​

Issue: "License bound to different machine"​

Cause: Hardware ID changed between container runs

Solution:

# Verify CODITECT_HARDWARE_ID is set
docker-compose exec coditect env | grep CODITECT_HARDWARE_ID

# If not set, add to docker-compose.yml or .env file
echo "CODITECT_HARDWARE_ID=docker-dev-$(whoami)-main" >> .env

Issue: "Maximum activations reached"​

Cause: Too many unique hardware IDs registered

Solution:

# List active devices
coditect license status --show-devices

# Deactivate old container IDs
coditect deactivate --hardware-id "docker-dev-old-container"

Issue: "License validation failed" in CI​

Cause: Missing or invalid API key

Solution:

# Verify secret is set in CI environment
echo "Key length: ${#CODITECT_ORG_API_KEY}"

# Test locally with same key
export CODITECT_ORG_API_KEY="your-key"
coditect license status

Environment Variables Reference​

VariableRequiredDefaultDescription
CODITECT_HARDWARE_IDYes (containers)Auto-generatedStable identifier for license binding
CODITECT_LICENSE_KEYNoNoneDirect license key (alternative to OAuth)
CODITECT_ORG_API_KEYNoNoneOrganization API key for CI/CD
CODITECT_LICENSE_SERVER_URLNohttps://api.coditect.aiLicense server endpoint
CODITECT_OFFLINE_GRACE_DAYSNo3Offline validation grace period
CODITECT_TELEMETRY_ENABLEDNofalseUsage telemetry opt-in

📚 Next Steps​

After Setup​

  1. Explore CODITECT:

    cd ~/coditect-core
    cat README.md
    ./scripts/init.sh

  2. Try Claude Code:

    cd ~/projects
    claude-code

  3. Read Documentation:

  4. Start Your First Project:

    cd ~/projects
    mkdir my-first-coditect-project
    cd my-first-coditect-project
    # Follow CODITECT quick start guide

---

## 📞 Support

### Issues

- Check [Troubleshooting](#-troubleshooting) section
- View logs: `docker-compose logs -f`
- Check container health: `docker ps`
- Restart container: `docker-compose restart`

#### Need Help

- GitHub Issues: <https://github.com/az1-ai/coditect-core/issues>
- Documentation: See `docs/` directory
- Community: [Discord/Slack link]

---

## 📄 Technical Specifications

### Docker Image Details

```yaml
Base Image:      ubuntu:22.04
Image Size:      ~4.5GB (compressed: ~1.8GB)
Build Time:      3-5 minutes (first time)
Platforms:       linux/amd64, linux/arm64
Dockerfile:      distribution/docker/Dockerfile
Compose File:    distribution/docker/docker-compose.yml
Entrypoint:      distribution/docker/entrypoint.sh

Environment Variables​

VariableDefaultDescription
CODITECT_REPOhttps://github.com/az1-ai/coditect-core.gitRepository to clone
INIT_COMPONENTStrueAuto-initialize CODITECT components
START_VNCtrueStart VNC server on startup
NODE_ENVdevelopmentNode.js environment
TZAmerica/New_YorkTimezone
DISPLAY:1X11 display number

Ports Exposed​

PortServiceAccess
5901VNC Serverlocalhost:5901
3000Claude Code / Dev Serverlocalhost:3000
8000Development Serverlocalhost:8000
8080Alternative Dev Serverlocalhost:8080

Created: 2025-11-29 Version: 1.0.0 Status: Production Ready Tested On: Docker Desktop 24.0+, macOS Sonoma, Ubuntu 22.04