ADR-025: terminal and workspace Connectivity Options

Status: Accepted Date: 2025-10-13 Decision Makers: Architecture Team Affected Components: theia IDE, Docker Container, File System, terminal, Git Integration

Context

Coditect AI IDE is built on Eclipse theia and supports multiple deployment scenarios:

1. Cloud deployment - Multi-tenant SaaS with isolated user workspaces
2. Local development - Developer testing and customization
3. Enterprise deployment - On-premise installations with existing infrastructure
4. Hybrid scenarios - Mix of cloud and local resources

Users need different levels of integration with their development environment:

• terminal access - Where shell commands execute (container vs. local OS vs. remote machine)
• File system access - Where files are stored and edited
• Git integration - How version control operates
• Tool availability - Access to compilers, runtimes, databases, etc.

The challenge is providing flexibility while maintaining security, isolation, and consistency across deployment modes.

Decision

We will support multiple terminal and workspace connectivity modes, each optimized for different use cases:

1. Container-Only Mode (Default for production)
2. Docker Volume Mount Mode (Local development)
3. Remote SSH Mode (Future - remote development)
4. Native Desktop Mode (Alternative - single-user)

Each mode has different characteristics for terminal execution, file access, and git integration.

Options Evaluated

Option 1: Container-Only Mode (SELECTED for Production)

Description:

• terminal runs inside Docker container (Debian from node:20-slim)
• File system is container's file system
• Git requires manual configuration
• Complete isolation between users

Pros:

• ✅ Complete isolation - Multi-tenant safe
• ✅ Consistent environment - Same OS/tools for all users
• ✅ Security - No access to host system
• ✅ Scalable - Works in Kubernetes/GKE
• ✅ Reproducible - Dockerized environment
• ✅ Cloud-ready - No local dependencies

Cons:

• ❌ No local file access - Can't edit files on user's machine
• ❌ Git setup required - Need to configure SSH keys, gitconfig
• ❌ Limited to container OS - Debian only, can't run Windows executables
• ❌ Storage ephemeral - Files lost when container stops (unless volumes)

Git Integration:

# Manual setup required in container
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
# SSH keys must be added to container

Use Cases:

• Production SaaS deployment
• Multi-tenant cloud IDE
• Isolated development environments
• CI/CD integration

---

Option 2: Docker Volume Mount Mode (SELECTED for Local Development)

Description:

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

Pros:

• ✅ Local file access - Edit files on your machine
• ✅ Git works out of box - Uses host SSH keys and config
• ✅ Persistent storage - Files survive container restart
• ✅ Tool flexibility - Can run container tools on host files
• ✅ Fast development - No need to copy files
• ✅ IDE integration - Other tools can access same files

Cons:

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

Git Integration:

# Mount git config and SSH keys from host
docker run \
  -v /home/user/projects:/workspace \
  -v /home/user/.gitconfig:/root/.gitconfig:ro \
  -v /home/user/.ssh:/root/.ssh:ro \
  ...

# Git commands in terminal work seamlessly
cd /workspace/myproject
git status  # Uses host SSH keys
git push    # Works with host authentication

Configuration Example:

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

Use Cases:

• Local development and testing
• Customizing theia extensions
• Debugging with local files
• Training and education

---

Option 3: Remote SSH Mode (FUTURE - Not Yet Implemented)

Description:

• 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

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 dev servers
• ✅ Team collaboration - Shared development environments
• ✅ Like VS Code Remote - Familiar pattern

Cons:

• ❌ Network dependency - Requires stable SSH connection
• ❌ Security complexity - SSH key management, firewall rules
• ❌ Latency - terminal lag over slow connections
• ❌ Setup required - SSH server, authentication
• ❌ Not implemented - Requires theia SSH extension

Git Integration:

# Git runs on remote machine with native config
# No special setup needed in theia

Implementation Requirements:

• theia SSH extension (like remote-ssh in VS Code)
• SSH server on target machine
• Network connectivity and firewall configuration
• Authentication (SSH keys or password)

Use Cases:

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

---

Option 4: Native Desktop Mode (ALTERNATIVE - Not Recommended for Multi-Tenant)

Description:

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

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. installed
• ❌ Not cloud-deployable - Can't scale
• ❌ Security concerns - No sandboxing

Installation:

# On user's Windows/Mac/Linux machine
npm install -g @theia/cli
theia start /path/to/workspace

Git Integration:

# Uses system git automatically
# All git aliases, GPG signing, credential helpers work

Use Cases:

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

Comparison Matrix

Feature	Container-Only	Volume Mount	Remote SSH	Native Desktop
Multi-tenant Safe	✅ Yes	❌ No	⚠️ Depends	❌ No
Local File Access	❌ No	✅ Yes	✅ Yes	✅ Yes
Git Integration	⚠️ Manual	✅ Host config	✅ Native	✅ Native
terminal OS	Debian	Debian	Remote OS	Host OS
Cloud Deployable	✅ Yes	❌ No	✅ Yes	❌ No
Kubernetes/GKE	✅ Yes	❌ No	⚠️ Complex	❌ No
Security Isolation	✅ High	⚠️ Medium	⚠️ Medium	❌ Low
Setup Complexity	Low	Medium	High	Low
Performance	Good	Good	Depends	Excellent
Implementation Status	✅ Ready	✅ Ready	🔲 Future	✅ Available

Decision Rationale

For Production (GKE Deployment)

Use Container-Only Mode because:

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

For Local Development

Support Volume Mount Mode because:

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

For Future (Remote Development)

Plan Remote SSH Mode because:

• Enterprise customers request it
• Enables powerful remote backends
• Similar to VS Code Remote (familiar)
• Supports complex team workflows

Not Recommended

Native Desktop Mode - While simple, it doesn't align with cloud-first architecture and multi-tenant requirements.

Consequences

Positive

1. Flexibility - Support multiple deployment scenarios
2. Developer Experience - Local development is smooth
3. Production Ready - Container-only mode is secure and scalable
4. Git Integration - Works in all modes (with varying setup)
5. Future-Proof - Can add Remote SSH later

Negative

1. Documentation Complexity - Need to document all modes
2. Testing Burden - Must test volume mount scenarios
3. Support Complexity - Different issues per mode
4. Configuration Management - Multiple docker run configurations
5. Security Considerations - Volume mounts expose host filesystem

Neutral

1. Line Ending Issues - Windows CRLF vs Linux LF (known issue)
2. File Permission Mapping - UID/GID mismatches possible
3. Platform Differences - Docker volume syntax varies

Implementation Details

Container-Only Mode (Current Implementation)

Dockerfile: Already implemented in dockerfile.local-test

Start Script:

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

Git Setup (Manual):

docker exec -it coditect-prod bash
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Volume Mount Mode (Configuration Only)

Start Script:

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

Git Configuration:

# Host .gitconfig
[user]
  name = Your Name
  email = you@example.com
[core]
  autocrlf = input  # Handle Windows line endings
[credential]
  helper = store    # Or osxkeychain, wincred

Line Ending Fix:

# In container terminal
git config --global core.autocrlf input

Remote SSH Mode (Future Implementation)

Requirements:

1. theia SSH extension (not yet integrated)
2. SSH configuration in theia settings
3. User authentication flow
4. Connection management UI

Planned Configuration:

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

Security Considerations

Container-Only Mode

• ✅ Complete isolation
• ✅ No host access
• ✅ Safe for multi-tenant
• ⚠️ SSH keys must be injected securely

Volume Mount Mode

• ⚠️ Host filesystem exposed
• ⚠️ SSH keys accessible to container
• ❌ NOT safe for multi-tenant
• ✅ Read-only mounts reduce risk

Remote SSH Mode

• ⚠️ SSH credentials management
• ⚠️ Network security
• ⚠️ Firewall configuration
• ✅ No local file access

Testing Strategy

Container-Only Mode

• ✅ Current CI/CD tests this
• ✅ Docker build successful
• ✅ Container starts and services work

Volume Mount Mode

• 🔲 Test on Windows (CRLF handling)
• 🔲 Test on Mac (case-sensitive FS)
• 🔲 Test on Linux (permission mapping)
• 🔲 Test git operations in all scenarios

Remote SSH Mode

• 🔲 Future - implement extension first

Documentation Updates

Required Documentation:

1. ✅ This ADR (ADR-025)
2. 🔲 development-modes.md - User guide
3. 🔲 docker-volume-configuration.md - Technical reference
4. 🔲 Update DEFINITIVE-V5-architecture.md - Add development modes section
5. 🔲 Update README.md - Link to development modes guide
6. 🔲 Update CLAUDE.md - Document modes for AI assistant

References

• Eclipse theia Documentation: https://theia-ide.org/docs/
• Docker Volume Mounts: https://docs.docker.com/storage/volumes/
• VS Code Remote Development: https://code.visualstudio.com/docs/remote/remote-overview
• Git Line Ending Handling: https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration

Revision History

• 2025-10-13: Initial ADR created after Docker build session completion
• Future: Will update when Remote SSH mode is implemented

---

Approved By: Architecture Team Implementation Status: Container-Only ✅ | Volume Mount ✅ | Remote SSH 🔲 | Native Desktop ⚠️