Deploying Eclipse Che

Introduction

Eclipse Che is an open-source, Kubernetes-native cloud development environment platform that brings your IDE to the browser. It provides developers with reproducible, software-defined development workspaces that run on Kubernetes, supporting VS Code, JetBrains IDEs, and other popular development tools.

Key Features

☁️ Cloud-Native IDE: Run VS Code, JetBrains IDEs, and other editors in your browser
📦 Containerized Workspaces: Every workspace runs in its own Kubernetes pod with dedicated resources
🔄 Reproducible Environments: Define workspaces with Devfiles for consistent team development
🚀 Quick Onboarding: Developers click a link and start coding immediately
⚡ Fast Setup: No local configuration required—everything runs in the cloud
🎯 Production-Like Testing: Test applications in Kubernetes environment before deployment
🔌 Extensible: Support for VS Code extensions and custom plugins
🤝 Team Collaboration: Share workspaces and pair program in real-time

Tech Stack

Backend: Java-based Che server orchestrating workspaces
Frontend: TypeScript and React dashboard
Runtime: Requires Kubernetes cluster with DevWorkspace Operator
IDEs Supported: VS Code (web-based), JetBrains IDEs via Projector, Eclipse Theia
Container Runtime: Kubernetes pods with configurable compute resources

Use Cases

Remote Development Teams: Provide consistent development environments for distributed teams
Onboarding New Developers: Get new team members productive in minutes, not days
Educational Environments: Teach coding with zero-setup cloud IDEs
Large Codebases: Leverage cloud resources for faster builds and tests
Secure Development: Keep code in the cloud, not on local machines
Multi-IDE Projects: Support developers who prefer different IDEs

Important: Eclipse Che Architecture Requirements

Eclipse Che is fundamentally designed as a Kubernetes-native platform and has specific architectural requirements that differ from traditional containerized applications:

What Eclipse Che Requires

**Kubernetes Cluster**: Eclipse Che runs on Kubernetes (minikube, OpenShift, EKS, GKE, AKS, etc.)
**Che Operator**: A Kubernetes operator that manages the Che installation lifecycle
**Multiple Components**: - Che Server (orchestration and API) - PostgreSQL database (workspace metadata) - DevWorkspace Operator (workspace lifecycle management) - Plugin Registry (IDE plugins and extensions) - Devfile Registry (workspace templates) - User Dashboard (web interface)
**Persistent Volume Claims**: Dynamic volume provisioning for workspace data
**Ingress/Route Configuration**: Complex routing for multiple workspace domains
**Service Accounts & RBAC**: Kubernetes permissions for workspace pod creation

Why Klutch.sh Cannot Deploy Eclipse Che Directly

Klutch.sh is designed for deploying standalone containerized applications with the following model:

Single Docker container deployment
HTTP or TCP traffic routing to a single port
Persistent volume mounting for data
Environment variable configuration

Eclipse Che requires:

A full Kubernetes cluster with operator capabilities
Dynamic pod creation and deletion
Complex networking with ingress controllers
Service mesh for inter-component communication
Stateful sets and deployments

These architectural differences make Eclipse Che incompatible with Klutch.sh’s deployment model.

Alternative Solution: code-server on Klutch.sh

For developers seeking a browser-based VS Code experience that can be deployed on Klutch.sh, we recommend code-server—a fully functional VS Code instance that runs in the browser via a single Docker container.

Why code-server on Klutch.sh?

✅ Single Container Deployment: No Kubernetes required
✅ Full VS Code Experience: Same editor, extensions, and features as desktop VS Code
✅ Easy Setup: Deploy in minutes with a simple Dockerfile
✅ Persistent Storage: Mount volumes for your code and extensions
✅ Browser Access: Access your development environment from anywhere
✅ Lightweight: Runs efficiently on modest compute resources
✅ Self-Hosted: Full control over your development environment

code-server vs Eclipse Che Comparison

Feature	code-server	Eclipse Che
Deployment	Single Docker container	Kubernetes cluster required
Resource Requirements	1 vCPU, 2GB RAM minimum	Multi-node Kubernetes cluster
Setup Time	5 minutes	30+ minutes (cluster setup)
IDE Support	VS Code only	VS Code, JetBrains, Eclipse Theia
Multi-User	Single user per instance	Multi-user workspaces
Workspace Isolation	Container-level	Kubernetes pod-level
Best For	Individual developers	Enterprise teams
Klutch.sh Compatible	✅ Yes	❌ No

Deploying code-server on Klutch.sh

Since Eclipse Che cannot be deployed on Klutch.sh, here’s a complete guide for deploying code-server as a practical alternative for browser-based development.

Prerequisites

Before deploying code-server, ensure you have:

A Klutch.sh account
A GitHub account for repository hosting
Basic understanding of Docker and VS Code

Preparing Your code-server Repository

Create a new directory for your code-server deployment:

mkdir code-server-deployment
cd code-server-deployment

Creating the Dockerfile

Create a Dockerfile that sets up code-server with your preferred configuration:

FROM codercom/code-server:latest

# Set environment variables
ENV CODE_SERVER_PORT=8080

# Install additional development tools
USER root

# Install common development dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    wget \
    build-essential \
    python3 \
    python3-pip \
    nodejs \
    npm \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Install global Node.js tools (optional)
RUN npm install -g \
    typescript \
    ts-node \
    eslint \
    prettier \
    nodemon

# Create directories for projects and extensions
RUN mkdir -p /home/coder/projects \
    && chown -R coder:coder /home/coder

# Switch back to coder user
USER coder

# Set working directory
WORKDIR /home/coder/projects

# Expose code-server port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD curl -f http://localhost:8080/healthz || exit 1

# Start code-server
CMD ["code-server", "--bind-addr", "0.0.0.0:8080", "--auth", "password", "/home/coder/projects"]

Customized Dockerfile with Language Support

For projects requiring specific language runtimes:

Python Development:

FROM codercom/code-server:latest

USER root

# Install Python and data science tools
RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    python3-venv \
    && apt-get clean

# Install Python packages
RUN pip3 install --no-cache-dir \
    numpy \
    pandas \
    matplotlib \
    jupyter \
    flask \
    django \
    pytest

USER coder

EXPOSE 8080

CMD ["code-server", "--bind-addr", "0.0.0.0:8080", "--auth", "password", "/home/coder/projects"]

Node.js & React Development:

FROM codercom/code-server:latest

USER root

# Install Node.js LTS and Yarn
RUN curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - \
    && apt-get install -y nodejs \
    && npm install -g yarn

# Install global development tools
RUN npm install -g \
    create-react-app \
    @vue/cli \
    @angular/cli \
    typescript \
    ts-node \
    eslint \
    prettier

USER coder

EXPOSE 8080

CMD ["code-server", "--bind-addr", "0.0.0.0:8080", "--auth", "password", "/home/coder/projects"]

Go Development:

FROM codercom/code-server:latest

USER root

# Install Go
RUN wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz \
    && tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz \
    && rm go1.22.0.linux-amd64.tar.gz

# Set Go environment variables
ENV PATH=$PATH:/usr/local/go/bin
ENV GOPATH=/home/coder/go
ENV GO111MODULE=on

# Install common Go tools
RUN go install golang.org/x/tools/gopls@latest \
    && go install github.com/go-delve/delve/cmd/dlv@latest

USER coder

EXPOSE 8080

CMD ["code-server", "--bind-addr", "0.0.0.0:8080", "--auth", "password", "/home/coder/projects"]

Creating Environment Variables Configuration

Create a .env.example file for reference:

# code-server Configuration
PASSWORD=your-secure-password-here
HASHED_PASSWORD=

# Optional: Use hashed password instead of plain text
# Generate with: echo -n "your-password" | npx argon2-cli -e

# Proxy domain (if using custom domain)
PROXY_DOMAIN=code.yourdomain.com

# Disable telemetry
TELEMETRY_DISABLED=true

# Git configuration
GIT_USER_NAME=Your Name
GIT_USER_EMAIL=your.email@example.com

Installing VS Code Extensions

Create an extensions.txt file with extensions you want pre-installed:

# Language Support
ms-python.python
ms-vscode.go
dbaeumer.vscode-eslint
esbenp.prettier-vscode

# Frameworks
bradlc.vscode-tailwindcss
dsznajder.es7-react-js-snippets
octref.vetur

# Utilities
eamodio.gitlens
formulahendry.auto-rename-tag
streetsidesoftware.code-spell-checker
usernamehw.errorlens

# Themes
PKief.material-icon-theme
Equinusocio.vsc-material-theme

Update your Dockerfile to install extensions:

FROM codercom/code-server:latest

USER root

# Install dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    && apt-get clean

USER coder

# Create extensions directory
RUN mkdir -p /home/coder/.local/share/code-server/extensions

# Copy extensions list
COPY extensions.txt /tmp/extensions.txt

# Install VS Code extensions
RUN while read extension; do \
      if [ ! -z "$extension" ] && [ "${extension:0:1}" != "#" ]; then \
        code-server --install-extension "$extension" || true; \
      fi; \
    done < /tmp/extensions.txt

EXPOSE 8080

WORKDIR /home/coder/projects

CMD ["code-server", "--bind-addr", "0.0.0.0:8080", "--auth", "password", "/home/coder/projects"]

Creating a .dockerignore File

Optimize your build with a .dockerignore file:

# Git
.git
.gitignore

# Dependencies
node_modules
venv
__pycache__

# IDE
.vscode
.idea

# Environment
.env
.env.local

# OS
.DS_Store
Thumbs.db

# Logs
*.log

Deploying code-server on Klutch.sh

Initialize a Git repository and push to GitHub:

git init
git add .
git commit -m "Initial code-server deployment"
git branch -M main
git remote add origin https://github.com/yourusername/code-server.git
git push -u origin main

Log into your Klutch.sh dashboard.
Navigate to the **Apps** section and click **"Create App"**.
Configure your code-server deployment:
- App Name: code-server (or your preferred name)
- Repository: Select your code-server GitHub repository
- Branch: main (or your deployment branch)
- Traffic Type: HTTP (for web application)
- Internal Port: 8080 (code-server’s default port)
- Region: Choose your preferred deployment region
- Compute: Minimum Shared CPU (2 vCPU, 2GB RAM recommended for development)
- Instances: 1 (code-server is designed for single-user access)

Add environment variables in the **Environment Variables** section:

Required:

PASSWORD=your-super-secure-password-here

Recommended:

TELEMETRY_DISABLED=true
GIT_USER_NAME=Your Name
GIT_USER_EMAIL=your.email@example.com

Optional (for Git integration):

GITHUB_TOKEN=your-github-personal-access-token

Configure **Persistent Volume** for your code and extensions:
Project Data Volume:
- Mount Path: /home/coder/projects
- Size: 10 GB (adjust based on your project needs)
Extensions & Configuration Volume (Optional):
- Mount Path: /home/coder/.local/share/code-server
- Size: 2 GB
Click **"Create"** to deploy. Klutch.sh will: - Build your Docker image with code-server - Install specified VS Code extensions - Provision persistent volumes - Deploy your code-server instance - Generate a unique URL: `https://your-app-name.klutch.sh`
Wait for the deployment to complete (typically 3-5 minutes).
Access your code-server instance at the provided URL.
Log in with the password you set in the environment variables.

Configuration & Customization

Authentication Options

code-server supports multiple authentication methods:

Password Authentication (Recommended for Klutch.sh):

# Plain text password
PASSWORD=your-secure-password

# Or use hashed password (more secure)
HASHED_PASSWORD=$argon2i$v=19$m=4096,t=3,p=1$hash-here

Generate a hashed password:

echo -n "your-password" | npx argon2-cli -e

Disable Authentication (NOT recommended for production):

CMD ["code-server", "--bind-addr", "0.0.0.0:8080", "--auth", "none", "/home/coder/projects"]

Git Configuration

Configure Git for your code-server instance:

Via Environment Variables:

GIT_USER_NAME=Your Name
GIT_USER_EMAIL=your.email@example.com

Via Dockerfile:

RUN git config --global user.name "Your Name" \
    && git config --global user.email "your.email@example.com"

SSH Key Setup:

Generate SSH keys for GitHub/GitLab access:

Access your code-server terminal

Generate SSH key:

ssh-keygen -t ed25519 -C "your.email@example.com"

Copy public key:
Terminal window
```
cat ~/.ssh/id_ed25519.pub
```
Add to GitHub: Settings → SSH and GPG keys → New SSH key
Test connection:
Terminal window
```
ssh -T git@github.com
```

Custom Domains

To use your own domain with code-server:

Navigate to your app in the Klutch.sh dashboard
Go to **Settings** → **Domains**
Click **"Add Domain"** and enter your domain (e.g., `code.yourdomain.com`)

Add the provided CNAME record to your DNS provider:

Type: CNAME
Name: code
Value: your-app-name.klutch.sh

Wait for DNS propagation (5-30 minutes)
Update `PROXY_DOMAIN` environment variable to your custom domain
Klutch.sh will automatically provision SSL/TLS certificates

Installing Additional Extensions

Install extensions through the web interface:

Click the Extensions icon in the sidebar
Search for your desired extension
Click "Install"
Extensions are saved to your persistent volume

Or via command line in the terminal:

code-server --install-extension ms-python.python
code-server --install-extension esbenp.prettier-vscode

Workspace Settings

Customize VS Code settings by editing settings.json:

Open Command Palette: `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)
Type "Preferences: Open Settings (JSON)"

Add your configurations:

{
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,
  "files.autoSave": "afterDelay",
  "workbench.colorTheme": "Material Theme",
  "terminal.integrated.fontSize": 13,
  "git.autofetch": true,
  "eslint.autoFixOnSave": true
}

Using code-server for Development

Opening Projects

From GitHub:

Open the terminal in code-server: `Ctrl+`` (backtick)

Clone your repository:

git clone https://github.com/username/project.git
cd project

Open the folder: File → Open Folder → Select project

Upload Local Files:

Use the File Explorer
Right-click in the projects directory
Select "Upload..." to upload files or folders

Running Applications

Node.js Application:

# Install dependencies
npm install

# Start development server
npm run dev

# Application runs on localhost within the container
# Access via port forwarding or deployed URL

Python Application:

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run application
python app.py

Port Forwarding:

code-server automatically forwards ports from applications running in the container:

Start your application (e.g., `npm run dev` on port 3000)
Click "Ports" tab in the terminal panel
code-server displays forwarded port with accessible URL
Access your application at the generated URL

Debugging

code-server supports VS Code’s full debugging capabilities:

Node.js Debugging:

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/index.js"
    }
  ]
}

Python Debugging:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal"
    }
  ]
}

Production Best Practices

Security Hardening

**Strong Passwords**: Use complex passwords with 16+ characters
Terminal window
```
# Generate secure password
openssl rand -base64 32
```
**HTTPS Only**: Always use custom domains with SSL certificates (automatic with Klutch.sh)
**Regular Updates**: Keep code-server updated to latest version
```
FROM codercom/code-server:4.22.0  # Pin specific version
```
**Firewall Rules**: Limit access to specific IP ranges (configure in Klutch.sh dashboard)
**No Sensitive Data in Environment Variables**: Use Klutch.sh's secrets management
**Disable Telemetry**:
Terminal window
```
TELEMETRY_DISABLED=true
```

Performance Optimization

**Compute Resources**: Allocate sufficient resources for your workload

Light Development: 2 vCPU, 2GB RAM
Medium Projects: 4 vCPU, 4GB RAM
Heavy Development: 8 vCPU, 8GB RAM

**Volume Planning**:

Small Projects: 5-10 GB
Medium Projects: 20-50 GB
Large Monorepos: 100+ GB

**Extension Management**: Only install necessary extensions

**Workspace Settings**: Disable resource-intensive features if needed

{
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/.git/objects/**": true
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/bower_components": true,
    "**/.git": true
  }
}

Backup Strategy

Implement regular backups for your code and configuration:

Volume Snapshots:

Navigate to **Volumes** in Klutch.sh dashboard
Select your code-server project volume
Click **"Create Snapshot"** for point-in-time backups
Schedule regular snapshots (daily recommended)

Git-Based Backups:

Commit and push code regularly:

git add .
git commit -m "Work in progress"
git push origin main

Use Git hooks for automatic commits
Enable auto-save in VS Code settings

Manual Backups:

Access Klutch.sh volume browser
Download `/home/coder/projects` directory
Store backup locally or in cloud storage

Monitoring & Health Checks

Monitor your code-server instance:

Health Check Endpoint:

curl https://your-app-name.klutch.sh/healthz

Resource Monitoring:

Check Klutch.sh dashboard for: - CPU usage - Memory consumption - Network traffic - Volume usage
Set up alerts for high resource usage

Application Logs:

View logs in Klutch.sh dashboard under **Logs** tab
Monitor for errors or warnings
Check startup messages for configuration issues

Troubleshooting

Cannot Access code-server

Symptoms: URL returns 502 or connection timeout

Solutions:

Verify app is running in Klutch.sh dashboard
Check internal port is set to **8080**
Ensure traffic type is **HTTP** (not TCP)

Review logs for startup errors:

# Common errors to look for
Failed to bind to port 8080
Permission denied
Configuration error

Restart the application if needed

Authentication Issues

Symptoms: Cannot log in with password

Solutions:

Verify `PASSWORD` environment variable is set correctly
Check for typos or special characters in password
If using `HASHED_PASSWORD`, ensure it's properly generated:
Terminal window
```
echo -n "your-password" | npx argon2-cli -e
```
Review logs for authentication errors
Try resetting password by updating environment variable and restarting

Extensions Not Installing

Symptoms: Extensions fail to install or don’t appear

Solutions:

Check internet connectivity from container
Verify sufficient disk space on extensions volume

Try manual installation:

code-server --install-extension extension-id

Check extension marketplace is accessible
Review logs for specific error messages

High CPU or Memory Usage

Symptoms: Slow performance, container restarts

Solutions:

Increase compute resources in Klutch.sh dashboard
Close unused tabs and terminate inactive terminals
Disable resource-intensive extensions

Limit TypeScript/ESLint workspace scanning:

{
  "typescript.disableAutomaticTypeAcquisition": true,
  "eslint.runtime": "node",
  "eslint.options": {
    "cache": true
  }
}

Consider splitting large projects into smaller workspaces

Git Operations Fail

Symptoms: Cannot push/pull from repositories

Solutions:

Verify Git configuration:

git config --global user.name
git config --global user.email

Check SSH key setup:
Terminal window
```
ssh -T git@github.com
```

For HTTPS, cache credentials:

git config --global credential.helper store

Verify network connectivity
Check repository permissions

Port Forwarding Not Working

Symptoms: Cannot access applications running in code-server

Solutions:

Verify application is running:
Terminal window
```
netstat -tuln | grep <port>
```
Check Ports tab in terminal panel shows the port

Ensure application binds to `0.0.0.0` not `localhost`:

// Node.js example
app.listen(3000, '0.0.0.0', () => {
  console.log('Server running');
});

Try accessing via forwarded URL in Ports panel
Check firewall rules in Klutch.sh dashboard

Workspace Data Lost

Symptoms: Projects or files disappear after restart

Solutions:

Verify persistent volume is attached correctly: - Check mount path: `/home/coder/projects` - Verify volume size and usage
Always save files before closing tabs

Enable auto-save:

{
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000
}

Restore from volume snapshot if available
Pull from Git repository if code was committed

Eclipse Che for Enterprise Teams

While code-server provides an excellent single-user cloud IDE experience on Klutch.sh, Eclipse Che remains the superior choice for enterprise teams that require:

When to Use Eclipse Che

**Multi-User Workspaces**: Teams need shared development environments with role-based access
**Kubernetes-Native Development**: Applications are deployed on Kubernetes and developers need to test in production-like environments
**Multiple IDE Support**: Team members use different IDEs (VS Code, JetBrains, Eclipse)
**Enterprise Security**: Advanced security requirements including SSO, LDAP, and audit logging
**Workspace Templates**: Standardized development environments across large teams using Devfiles
**Resource Isolation**: Each developer needs dedicated Kubernetes pods with custom resource limits