Skip to main content

Development Modes Guide

Last Updated: 2025-10-13 Status: Production Ready Audience: Developers, DevOps, Enterprise Users

Overview​

Coditect AI IDE supports multiple development modes to accommodate different deployment scenarios, from cloud production to local development. This guide helps you choose and configure the right mode for your needs.

Quick Decision Matrix:

Your SituationRecommended ModeSetup Time
🚀 Production SaaS deploymentContainer-Only5 min
💻 Local development & testingVolume Mount10 min
🌐 Remote dev serverRemote SSH (Future)15 min
🖥️ Single-user local installNative Desktop20 min

See Also:

Table of Contents​

  1. Mode 1: Container-Only (Production)
  2. Mode 2: Volume Mount (Local Development)
  3. Mode 3: Remote SSH (Future)
  4. Mode 4: Native Desktop (Alternative)
  5. Comparison & Recommendations
  6. Troubleshooting
  7. FAQ

Mode 1: Container-Only (Production)​

Best For:

  • ✅ Multi-tenant SaaS deployments
  • ✅ Cloud production environments (GKE, EKS, AKS)
  • ✅ CI/CD pipelines
  • ✅ Teams requiring isolation and security

Characteristics:

  • terminal runs inside Docker container (Debian)
  • File system is container's file system
  • Complete isolation between users
  • No access to host machine

Quick Start​

1. Pull/Build Image:

# Option A: Pull from registry (future)
docker pull gcr.io/serene-voltage-464305-n2/coditect-combined:latest

# Option B: Build locally
docker build -f dockerfile.local-test -t coditect-combined:prod .

2. Start Container:

docker run -d \
  -p 8080:80 \
  --name coditect-prod \
  coditect-combined:prod

3. Access:

Git Configuration​

Since the container is isolated, you need to configure git inside the container:

# Enter container
docker exec -it coditect-prod bash

# Configure git
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# Generate SSH key (if needed)
ssh-keygen -t ed25519 -C "you@example.com"
cat ~/.ssh/id_ed25519.pub  # Add to GitHub

# Exit container
exit

Note: Git configuration will persist if you use Docker volumes for /root/.gitconfig and /root/.ssh.

Pros & Cons​

Pros:

  • ✅ Complete isolation (multi-tenant safe)
  • ✅ Consistent environment (same for all users)
  • ✅ Secure (no host access)
  • ✅ Scalable (Kubernetes-ready)
  • ✅ Cloud-deployable

Cons:

  • ❌ No local file access
  • ❌ Git setup required
  • ❌ Limited to container OS (Debian)
  • ❌ Storage ephemeral (unless volumes used)

Mode 2: Volume Mount (Local Development)​

Best For:

  • ✅ Local development and testing
  • ✅ Editing files on your machine
  • ✅ Using existing git configuration
  • ✅ Fast iteration without copying files

Characteristics:

  • terminal runs in container (Debian)
  • File system mounted from host (Windows/Mac/Linux)
  • Git uses host configuration and SSH keys
  • Hybrid: container runtime + host files

Quick Start​

1. Identify Your workspace:

# Windows (PowerShell)
$WORKSPACE = "C:\Users\Hal\v4\PROJECTS"

# Mac/Linux
WORKSPACE=/home/user/projects

2. Start Container with Volume Mounts:

Windows (PowerShell):

docker run -d `
  -p 8080:80 `
  -p 3001:3000 `
  -v C:\Users\Hal\v4\PROJECTS:/workspace `
  -v C:\Users\Hal\.gitconfig:/root/.gitconfig:ro `
  -v C:\Users\Hal\.ssh:/root/.ssh:ro `
  --name coditect-dev `
  coditect-combined:test

Mac/Linux (Bash):

docker run -d \
  -p 8080:80 \
  -p 3001:3000 \
  -v /home/user/projects:/workspace \
  -v /home/user/.gitconfig:/root/.gitconfig:ro \
  -v /home/user/.ssh:/root/.ssh:ro \
  --name coditect-dev \
  coditect-combined:test

3. Access:

4. Open workspace: In theia, open /workspace folder to access your mounted files.

Git Configuration​

Your host git configuration is automatically used!

Verify git works:

# Enter container
docker exec -it coditect-dev bash

# Git should work immediately
cd /workspace/your-project
git status
git pull
git push

# Exit container
exit

If git doesn't work:

  1. Check SSH keys are readable: ls -la /root/.ssh
  2. Fix permissions if needed: chmod 600 /root/.ssh/id_ed25519
  3. Test SSH: ssh -T git@github.com

Line Endings (Windows)​

Issue: Windows uses CRLF (\r\n), Linux uses LF (\n)

Solution 1: Configure git (Recommended):

# On Windows host
git config --global core.autocrlf input

# Inside container
docker exec -it coditect-dev bash
git config --global core.autocrlf input
exit

Solution 2: .gitattributes:

# In your project root
echo "* text=auto eol=lf" > .gitattributes

File Permissions (Linux/Mac)​

Issue: UID/GID mismatch between host and container

Solution 1: Run container as your user:

docker run -d \
  --user $(id -u):$(id -g) \
  -v /home/user/projects:/workspace \
  ...

Solution 2: Fix ownership after changes:

# On host
sudo chown -R $USER:$USER /home/user/projects

Pros & Cons​

Pros:

  • ✅ Local file access (edit on your machine)
  • ✅ Git works out of box (uses host config)
  • ✅ Persistent storage (files survive restarts)
  • ✅ Fast development (no file copying)
  • ✅ IDE integration (other tools can access files)

Cons:

  • ❌ OS mismatch (terminal is Linux, files might be Windows)
  • ❌ Line ending issues (CRLF vs LF)
  • ❌ Permission complexities (UID/GID mapping)
  • ❌ NOT multi-tenant safe (can't use in production)
  • ❌ Platform-specific (Docker syntax differs)

Mode 3: Remote SSH (Future)​

Status: 🔲 Not Yet Implemented - Requires theia SSH extension

Best For:

  • ✅ Remote development on powerful servers
  • ✅ Accessing production-like environments
  • ✅ Team development on shared infrastructure
  • ✅ WSL/Docker development from Windows

Characteristics:

  • terminal runs on remote machine (accessed via SSH)
  • File system is on remote machine
  • Git is native on remote machine
  • theia acts as thin client

Architecture​

User Browser
  ↓ HTTPS
theia (in Docker/Cloud)
  ↓ SSH
Remote Development Server (User's machine or team server)
  ↓ Direct access
Files, Git, Tools, Databases

Planned Implementation​

Requirements:

  1. theia SSH extension (like VS Code Remote-SSH)
  2. SSH server on target machine
  3. Network connectivity and firewall configuration
  4. Authentication (SSH keys or password)

Configuration (Planned):

{
  "remote.SSH.hosts": [
    {
      "host": "dev-server.company.com",
      "user": "developer",
      "port": 22
    }
  ]
}

Workaround (Until Implemented)​

Use SSH tunneling with Volume Mount Mode:

  1. SSH into remote machine from your local machine
  2. Use SSHFS to mount remote filesystem locally
  3. Use Volume Mount Mode pointing to SSHFS mount

Example (Linux/Mac):

# Install SSHFS
sudo apt install sshfs  # Ubuntu/Debian
brew install sshfs      # Mac

# Mount remote filesystem
mkdir -p ~/remote-workspace
sshfs user@remote-server:/path/to/workspace ~/remote-workspace

# Start container with volume mount
docker run -d \
  -v ~/remote-workspace:/workspace \
  ...

# Unmount when done
fusermount -u ~/remote-workspace  # Linux
umount ~/remote-workspace         # Mac

Pros & Cons​

Pros:

  • ✅ Native OS access (run Windows/Mac/Linux commands)
  • ✅ Full tool access (any compiler, database, IDE)
  • ✅ Git native (uses remote machine's git)
  • ✅ Powerful backends (connect to beefy servers)
  • ✅ Team collaboration (shared environments)

Cons:

  • ❌ Network dependency (requires stable SSH)
  • ❌ Security complexity (SSH keys, firewalls)
  • ❌ Latency (terminal lag over slow connections)
  • ❌ Setup required (SSH server, authentication)
  • ❌ Not implemented (requires theia extension)

Mode 4: Native Desktop (Alternative)​

Best For:

  • ✅ Single-user local IDE
  • ✅ Offline development
  • ✅ Custom enterprise installations
  • ✅ Education (simple setup)

Characteristics:

  • Run theia directly on user's OS (no Docker)
  • terminal is native OS shell
  • File system is native
  • Git is native

⚠️ Not Recommended for multi-tenant or cloud deployments.

Quick Start​

1. Install Node.js:

# Requires Node.js 20+
node --version  # Should be 20.x or higher

2. Install theia CLI:

npm install -g @theia/cli

3. Start theia:

# Navigate to your workspace
cd /path/to/workspace

# Start theia
theia start

4. Access:

Git Configuration​

Git works natively! Uses your system git configuration automatically.

# Verify git is installed
git --version

# Configure if needed
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Pros & Cons​

Pros:

  • ✅ Native performance (no container overhead)
  • ✅ Perfect OS integration (everything just works)
  • ✅ Git seamless (uses system git)
  • ✅ Tool access (all local tools available)
  • ✅ Simple deployment (npm install and run)

Cons:

  • ❌ No isolation (single-user only)
  • ❌ Platform-specific (different behavior per OS)
  • ❌ Dependency hell (need Node.js, Python, etc.)
  • ❌ Not cloud-deployable (can't scale)
  • ❌ Security concerns (no sandboxing)

Comparison & Recommendations​

Feature Comparison​

FeatureContainer-OnlyVolume MountRemote SSHNative Desktop
Multi-tenant Safe✅ Yes❌ No⚠️ Depends❌ No
Local File Access❌ No✅ Yes✅ Yes✅ Yes
Git Integration⚠️ Manual✅ Host config✅ Native✅ Native
terminal OSDebianDebianRemote OSHost OS
Cloud Deployable✅ Yes❌ No✅ Yes❌ No
Kubernetes/GKE✅ Yes❌ No⚠️ Complex❌ No
Security Isolation✅ High⚠️ Medium⚠️ Medium❌ Low
Setup ComplexityLowMediumHighLow
PerformanceGoodGoodDependsExcellent
Implementation Status✅ Ready✅ Ready🔲 Future✅ Available

Recommendations by Scenario​

For Production (GKE Deployment)​

→ Use Container-Only Mode

Why:

  • Multi-tenant security is critical
  • Kubernetes requires containerization
  • Consistent environment reduces support burden
  • Cloud-native architecture

Configuration:

# Kubernetes deployment
kubectl apply -f k8s/coditect-deployment.yaml

For Local Development​

→ Use Volume Mount Mode

Why:

  • Developers need to edit local files
  • Fast iteration without copying files
  • Git integration with existing workflows
  • Familiar development experience

Configuration:

# Docker with volume mounts
docker run -d \
  -v /home/user/projects:/workspace \
  -v /home/user/.gitconfig:/root/.gitconfig:ro \
  -v /home/user/.ssh:/root/.ssh:ro \
  coditect-combined:test

For Enterprise (On-Premise)​

→ Consider Container-Only or Remote SSH (Future)

Why:

  • Security and isolation requirements
  • Integration with existing infrastructure
  • Central management and monitoring
  • Compliance requirements

Configuration:

# Docker Swarm or Kubernetes
docker stack deploy -c docker-compose.prod.yml coditect

For Education/Training​

→ Use Native Desktop or Volume Mount

Why:

  • Simple setup for students
  • No Docker knowledge required (Native)
  • Or: consistent environment (Volume Mount)
  • Easy troubleshooting

Configuration:

# Native Desktop
npm install -g @theia/cli
theia start /path/to/workspace

# OR Volume Mount
docker run -v $(pwd):/workspace coditect-combined:test

Troubleshooting​

Container-Only Mode​

Problem: Git push fails with "Permission denied (publickey)"

Solution:

# Enter container
docker exec -it coditect-prod bash

# Generate SSH key
ssh-keygen -t ed25519 -C "you@example.com"

# Display public key
cat ~/.ssh/id_ed25519.pub

# Add to GitHub: https://github.com/settings/keys

Problem: Files disappear after container restart

Solution: Use Docker volumes to persist data:

docker run -d \
  -v coditect-data:/root \
  --name coditect-prod \
  coditect-combined:prod

# Data persists in named volume
docker volume ls  # See volumes

Volume Mount Mode​

Problem: Line ending issues (CRLF vs LF) on Windows

Solution 1: Configure git autocrlf:

# On Windows host
git config --global core.autocrlf input

# Inside container
docker exec -it coditect-dev bash
git config --global core.autocrlf input

Solution 2: Use .gitattributes:

# In project root
echo "* text=auto eol=lf" > .gitattributes
git add .gitattributes
git commit -m "fix: Normalize line endings"

Problem: Permission denied when accessing files (Linux/Mac)

Solution: Run container as your user:

docker run -d \
  --user $(id -u):$(id -g) \
  -v /home/user/projects:/workspace \
  coditect-combined:test

Problem: Git commands fail with "Could not read from remote repository"

Solution: Check SSH key permissions:

docker exec -it coditect-dev bash

# Check SSH key exists
ls -la /root/.ssh/

# Fix permissions
chmod 700 /root/.ssh
chmod 600 /root/.ssh/id_ed25519
chmod 644 /root/.ssh/id_ed25519.pub

# Test SSH connection
ssh -T git@github.com

Native Desktop Mode​

Problem: "Command 'theia' not found"

Solution: Install theia CLI globally:

npm install -g @theia/cli

# Verify installation
theia --version

Problem: Port 3000 already in use

Solution: Specify different port:

theia start --port 8080

General Issues​

Problem: "Cannot connect to the Docker daemon"

Solution:

# Check Docker is running
docker --version
docker ps

# Start Docker (if not running)
# Windows: Start Docker Desktop
# Linux: sudo systemctl start docker
# Mac: Open Docker Desktop

Problem: Container not responding to HTTP requests

Solution:

# Check container is running
docker ps -a

# Check container logs
docker logs coditect-dev

# Check container health
docker inspect coditect-dev | grep -A 10 Health

# Restart container
docker restart coditect-dev

FAQ​

Can I switch between modes?​

Yes! Modes are just different ways to run the same container. You can:

  1. Stop current container:

    docker stop coditect-dev
    docker rm coditect-dev

  2. Start with different mode:

    # Switch from Container-Only to Volume Mount
    docker run -d -v /home/user/projects:/workspace ...

Do I need Docker for all modes?​

No. Only Container-Only, Volume Mount, and Remote SSH (future) require Docker.

Native Desktop Mode runs directly on your OS without Docker.

Which mode is fastest?​

Performance ranking:

  1. Native Desktop (fastest - no container overhead)
  2. Container-Only (fast - optimized container)
  3. Volume Mount (fast - slight I/O overhead for mounted files)
  4. Remote SSH (depends on network latency)

For most use cases, all modes are fast enough.

Can I use WSL2 (Windows Subsystem for Linux)?​

Yes! WSL2 works great with Volume Mount Mode:

# From Windows PowerShell (accessing WSL2 filesystem)
docker run -d `
  -v \\wsl$\Ubuntu\home\user\projects:/workspace `
  coditect-combined:test

Or run Docker inside WSL2:

# From WSL2 terminal
docker run -d \
  -v /home/user/projects:/workspace \
  coditect-combined:test

How do I backup my work?​

Container-Only Mode:

# Use Docker volumes or bind mounts
docker run -d \
  -v coditect-data:/root \
  coditect-combined:prod

# Backup volume
docker run --rm \
  -v coditect-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/coditect-backup.tar.gz /data

Volume Mount Mode: Your files are already on your host machine - use your regular backup strategy.

Native Desktop Mode: Your files are in your workspace directory - use git or regular backups.

Can I use multiple modes at the same time?​

Yes! Run multiple containers with different configurations:

# Production (port 8080)
docker run -d -p 8080:80 --name coditect-prod coditect-combined:prod

# Development (port 8081)
docker run -d -p 8081:80 -v $(pwd):/workspace --name coditect-dev coditect-combined:test

# Testing (port 8082)
docker run -d -p 8082:80 --name coditect-test coditect-combined:test

How do I update to a new version?​

Container Modes:

# Pull new image
docker pull gcr.io/serene-voltage-464305-n2/coditect-combined:latest

# Stop old container
docker stop coditect-dev

# Start with new image
docker run -d --name coditect-dev-v2 [same options] coditect-combined:latest

Native Desktop Mode:

# Update theia CLI
npm update -g @theia/cli

Additional Resources​

Documentation​

External Resources​

Support​

Last Updated: 2025-10-13 Version: 1.0.0 Status: Production Ready