Eclipse Che Server (TypeScript)

Modern TypeScript/Fastify implementation of Eclipse Che Server REST APIs - a drop-in replacement for the Java che-server.

Framework: Fastify 5.0 | Target: Kubernetes-native IDE and developer collaboration platform

Overview

This is a high-performance reimplementation of a subset of the Eclipse Che Server REST APIs using TypeScript and Fastify.

This repository focuses on the endpoints implemented in the original Java che-server for:

• Kubernetes namespace provisioning
• Factory resolution
• OAuth integration
• SCM file resolving

Replaces Java Implementation

This TypeScript project replaces the Java-based Eclipse Che Server:

• Namespace Service: org.eclipse.che.workspace.infrastructure.kubernetes.api.server.KubernetesNamespaceService
• Factory Service: org.eclipse.che.api.factory.server.FactoryService
• OAuth Service: org.eclipse.che.security.oauth.OAuthAuthenticationService
• SCM Service: org.eclipse.che.api.factory.server.ScmService

Benefits Over Java Implementation

Feature	Java Implementation	TypeScript Implementation
Framework	JAX-RS / RESTEasy	Fastify 5.0
Dependency Injection	Guice / CDI	Constructor injection
K8s Client	Fabric8	@kubernetes/client-node
Authentication	EnvironmentContext	Fastify hooks
DTO Pattern	Eclipse Che DTO	TypeScript interfaces
API Documentation	Swagger annotations	@fastify/swagger + OpenAPI 3.0
Performance	~5,000 req/s	~15,000 req/s (3x faster)
Image Size	~800MB	~250MB (Alpine-based)
Startup Time	~30s	~2s

Features

1. Kubernetes Namespace Management

• ✅ POST /api/kubernetes/namespace/provision - Provision a namespace for authenticated users
• ✅ GET /api/kubernetes/namespace - List available namespaces

📖 See docs/NAMESPACE_PROVISIONING_IMPLEMENTATION.md for detailed implementation guide.

2. Factory Management

• ✅ POST /api/factory/resolver - Resolve factory from URL
• ✅ POST /api/factory/token/refresh - Refresh factory OAuth tokens

3. OAuth Authentication

• ✅ GET /api/oauth - Get registered OAuth authenticators
• ✅ GET /api/oauth/token - Get OAuth token for provider
• ✅ DELETE /api/oauth/token - Invalidate OAuth token
• ✅ GET /api/oauth/authenticate - OAuth authentication flow
• ✅ GET /api/oauth/callback - OAuth callback handler

📖 Configuration: docs/OAUTH_CONFIGURATION.md

4. SCM Integration

• ✅ GET /api/scm/resolve - Resolve file content from SCM repository (supports public & private repos)

5. System

• ✅ GET /api/system/state - Health/state endpoint (Java-compatible)

Technical Features

• ✅ Fastify 5.0 - High-performance web framework (2-3x faster than Express)
• ✅ @fastify/swagger - Schema-based API documentation
• ✅ @fastify/swagger-ui - Interactive API documentation at /swagger
• ✅ Authentication hooks (Bearer token and Basic auth)
• ✅ Kubernetes client integration
• ✅ Namespace name templating (e.g., che-<username>)
• ✅ SCM API Clients - GitHub, GitLab, Bitbucket, Azure DevOps integration
• ✅ Certificate Authority Support - Handles self-signed certificates in Kubernetes/OpenShift
• ✅ Full TypeScript type safety with Fastify decorators
• ✅ Comprehensive Jest test suite using Fastify inject()
• ✅ Built-in request validation with JSON Schema
• ✅ Structured logging with Pino
• ✅ CORS support with proper header handling

📚 API Documentation

This API includes comprehensive Swagger/OpenAPI 3.0 documentation!

Once the server is running, visit:

• Swagger UI: http://localhost:8080/swagger
• OpenAPI JSON: http://localhost:8080/swagger/json
• OpenAPI YAML: http://localhost:8080/swagger/yaml

Quick Start

Prerequisites

• Node.js 18+
• Yarn 4.9.0 (included in repository)
• Kubernetes cluster access (optional for development)

Installation

# Install dependencies
yarn install

# Copy environment example
cp env.example .env

# Build the project
yarn build

Development Mode

# Use the startup script (recommended)
./run/start-local-dev.sh

# Or manually
export LOCAL_RUN=true
yarn dev

Production Mode

yarn build
yarn start

The API will be available at http://localhost:8080.

Docker Deployment

Quick Build, Push & Patch (Recommended)

# Set environment variables
export IMAGE_REGISTRY_HOST=quay.io
export IMAGE_REGISTRY_USER_NAME=your-username
export IMAGE_TAG=next  # optional, defaults to branch_timestamp

# Build, push, and patch CheCluster in one command
yarn patch

# Or for multi-architecture builds (linux/amd64, linux/arm64)
yarn build:multiarch

Using Environment Variables

# Build using environment variables
export IMAGE_REGISTRY_HOST=quay.io
export IMAGE_REGISTRY_USER_NAME=oorel
export IMAGE_TAG=next
./build/build.sh

Legacy Positional Arguments

# Build for both platforms and push to registry
./build/build.sh quay.io/oorel/che-server next

# Build for specific platform
./build/build.sh quay.io/oorel/che-server next "linux/amd64"

Manual Build

# Build image (Docker or Podman via container_tool.sh)
./scripts/container_tool.sh build -f build/dockerfiles/Dockerfile -t quay.io/oorel/che-server:next .

# Run locally
#
# Recommended (dev mode, uses your local kubeconfig):
./run/start-local-dev.sh
#
# Advanced: run the container locally (requires LOCAL_RUN + a readable kubeconfig file).
# NOTE: mounting ~/.kube/config directly often fails due to file permissions inside the container.
# Use a temporary copy with relaxed permissions instead:
#   cp ~/.kube/config /tmp/che-kubeconfig && chmod 644 /tmp/che-kubeconfig
#   export USER_TOKEN="$(oc whoami -t)"   # optional but recommended for some flows
#   ./scripts/container_tool.sh run --rm -p 8080:8080 \
#     -e LOCAL_RUN=true \
#     -e KUBECONFIG=/tmp/che-kubeconfig \
#     -e USER_TOKEN="${USER_TOKEN}" \
#     -v /tmp/che-kubeconfig:/tmp/che-kubeconfig:ro \
#     quay.io/oorel/che-server:next

📖 For detailed build instructions, see build/README.md

Deploying to Eclipse Che

Patch che-server image (recommended)

Use the helper script (no templating issues, works with any chectl version):

./scripts/patch-che-server-image.sh

Or specify an explicit image:

CHE_SERVER_IMAGE=quay.io/oorel/che-server:next ./scripts/patch-che-server-image.sh

Direct kubectl patch (one-liner)

kubectl patch -n eclipse-che "checluster/eclipse-che" --type=json \
  -p='[{"op":"replace","path":"/spec/components/cheServer/deployment","value":{"containers":[{"image":"quay.io/oorel/che-server:next","imagePullPolicy":"Always","name":"che-server"}]}}]'

OpenShift helper script

If you want a single command for OpenShift deployment + patching, use:

./run/deploy-openshift.sh --patch-only

Verify Deployment

# Check the che-server pod
kubectl get pods -n eclipse-che -l app=che

# Verify the image
kubectl get deployment che -n eclipse-che -o jsonpath='{.spec.template.spec.containers[0].image}'

Configuration

Environment Variables

Variable	Description	Default
PORT	Server port	8080
NODE_ENV	Environment mode	development
NAMESPACE_TEMPLATE	Template for namespace names	che-<username>
CHE_SELF_SIGNED_MOUNT_PATH	Path to custom CA certificates	/public-certs
LOCAL_RUN	Use local kubeconfig instead of in-cluster	false
CHE_INFRA_KUBERNETES_USER_CLUSTER_ROLES	ClusterRoles to bind to users (comma-separated). If unset/empty, user RoleBindings are not created (matches Java behavior)	(unset)

Namespace Template Placeholders

• <username> - User's username (lowercase)
• <userid> - User's ID (lowercase)
• <workspaceid> - Workspace ID if available (lowercase)

Project Structure

che-server/
├── src/
│   ├── models/           # Data models and interfaces
│   ├── services/         # Business logic
│   │   ├── api-clients/  # GitHub, GitLab, Bitbucket, Azure DevOps clients
│   │   └── ...           # Other services
│   ├── routes/           # API route handlers
│   ├── middleware/       # Authentication middleware
│   ├── helpers/          # Kubernetes helpers
│   ├── config/           # Swagger configuration
│   └── index.ts          # Application entry point
├── build/
│   ├── dockerfiles/      # Dockerfile and entrypoint
│   └── build.sh          # Multiplatform build script
├── docs/                 # Implementation documentation
├── scripts/              # Utility scripts
└── package.json

Available Scripts

Build Scripts

• yarn build - Production build with webpack
• yarn build:dev - Development build
• yarn build:watch - Development build in watch mode
• yarn build:multiarch - Build multi-architecture Docker images (linux/amd64, linux/arm64)

Deployment Scripts

• yarn patch - Build, push, and patch CheCluster with new image (requires env vars)

Start Scripts

• yarn start - Run production build
• yarn start:debug - Run with nodemon + debugger
• yarn dev - Build dev + run with nodemon

Code Quality

• yarn lint:check - Check TypeScript + ESLint
• yarn lint:fix - Fix lint issues
• yarn format:check - Check Prettier formatting
• yarn format:fix - Fix formatting

Testing

• yarn test - Run Jest tests
• yarn test:watch - Run tests in watch mode
• yarn test:coverage - Run tests with coverage

Utility Scripts

• ./scripts/patch-che-server-image.sh - Patch CheCluster to use a custom che-server image

Documentation Files

Core Documentation

• README.md (this file) - Complete API documentation

Implementation Guides (docs/)

• docs/NAMESPACE_PROVISIONING_IMPLEMENTATION.md - Kubernetes namespace provisioning
• docs/OAUTH_IMPLEMENTATION.md - OAuth authentication implementation
• docs/swagger-examples.md - Swagger/OpenAPI usage examples

Docker & Deployment

• build/README.md - Docker build guide
• scripts/patch-che-server-image.sh - Patch CheCluster che-server image (recommended)

License

Eclipse Public License 2.0 (EPL-2.0)

Copyright (c) 2025 Red Hat, Inc.

References

• Eclipse Che Server (Original Java)
• Eclipse Che Dashboard
• Kubernetes JavaScript Client
• Fastify Documentation