# Gitpod Self-Hosted

> Cloud development environments from Git repositories.

- Category: Development Tools
- Difficulty: advanced
- Components: gitpod, mysql, minio, registry
- Tags: gitpod, cloud-dev, ide, workspace, remote-development
- Source: https://docker.recipes/development/gitpod-complete

## Overview

Gitpod is an open-source developer platform that automates the provisioning of ready-to-code development environments. Originally developed by TypeFox and later spun off as an independent company, Gitpod eliminates the "works on my machine" problem by providing consistent, cloud-based development environments that spin up directly from Git repositories. The platform supports multiple IDEs including VS Code, IntelliJ, and Eclipse Theia, making it accessible to developers regardless of their preferred tooling.

This self-hosted Gitpod deployment combines four critical components to deliver a complete cloud development platform. MySQL serves as the primary database for storing workspace metadata, user sessions, and configuration data. MinIO provides S3-compatible object storage for workspace snapshots, prebuilds, and user uploads, while the Docker Registry handles container image storage for custom workspace images and cached layers. Together, these services enable Gitpod to manage the full lifecycle of ephemeral development environments.

This stack is ideal for organizations wanting complete control over their development infrastructure, companies with strict data residency requirements, or teams seeking to reduce cloud costs while maintaining the benefits of cloud-native development. Educational institutions, enterprise development teams, and open-source projects particularly benefit from this setup as it provides unlimited workspaces without per-seat licensing constraints while keeping sensitive code on-premises.

## Features

- Ephemeral workspace creation from any Git repository with automatic dependency installation
- MinIO S3-compatible storage for workspace snapshots and incremental prebuilds
- MySQL-backed user management with OAuth integration for GitHub, GitLab, and Bitbucket
- Private Docker Registry for custom workspace images and cached development containers
- Workspace sharing capabilities with real-time collaboration features
- Automated prebuild system that prepares development environments before code changes
- Resource quotas and usage tracking for multi-tenant development environments
- Browser-based IDE access with support for VS Code extensions and terminal sessions

## Use cases

- Enterprise development teams requiring on-premises code execution with centralized environment management
- Educational institutions providing standardized programming environments for computer science courses
- Open-source projects offering contributors instant development environments without local setup
- Remote development teams needing consistent environments across different operating systems and hardware
- Companies with strict data governance requirements preventing cloud-based development platforms
- Development agencies managing multiple client projects with isolated, reproducible environments
- Organizations implementing secure code review processes with temporary workspace provisioning

## Prerequisites

- Minimum 8GB RAM (4GB for Gitpod services, 2GB for MySQL, 2GB for MinIO operations)
- Valid domain name with DNS configuration pointing to your Docker host for HTTPS access
- Docker host with at least 50GB available storage for workspace data and container images
- SSL certificates configured for your domain (Let's Encrypt or commercial certificates)
- OAuth application credentials from your Git provider (GitHub, GitLab, or Bitbucket)
- Basic understanding of Gitpod workspace configuration and .gitpod.yml syntax

## docker-compose.yml

```yaml
services:
  gitpod:
    image: eu.gcr.io/gitpod-core-dev/build/installer:latest
    environment:
      - GITPOD_DOMAIN=${GITPOD_DOMAIN}
      - GITPOD_PROTOCOL=https
      - DB_HOST=mysql
      - DB_PORT=3306
      - DB_PASSWORD=${MYSQL_PASSWORD}
    volumes:
      - gitpod-data:/var/gitpod
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "443:443"
      - "80:80"
    depends_on:
      - mysql
      - minio
      - registry
    networks:
      - gitpod-network
    restart: unless-stopped

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=gitpod
      - MYSQL_USER=gitpod
      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - gitpod-network
    restart: unless-stopped

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      - MINIO_ROOT_USER=${MINIO_ACCESS_KEY}
      - MINIO_ROOT_PASSWORD=${MINIO_SECRET_KEY}
    volumes:
      - minio-data:/data
    networks:
      - gitpod-network
    restart: unless-stopped

  registry:
    image: registry:2
    volumes:
      - registry-data:/var/lib/registry
    networks:
      - gitpod-network
    restart: unless-stopped

volumes:
  gitpod-data:
  mysql-data:
  minio-data:
  registry-data:

networks:
  gitpod-network:
    driver: bridge
```

## .env

```bash
# Gitpod
GITPOD_DOMAIN=gitpod.localhost
MYSQL_ROOT_PASSWORD=secure_root_password
MYSQL_PASSWORD=secure_mysql_password
MINIO_ACCESS_KEY=gitpod
MINIO_SECRET_KEY=secure_minio_secret
```

## Usage notes

- Access via https://gitpod.localhost
- Configure OAuth with Git provider
- Prebuilds for faster startup
- Requires DNS configuration
- Kubernetes recommended for production

## Troubleshooting

- Gitpod workspaces failing to start: Verify Docker daemon is accessible and has sufficient disk space for workspace containers
- OAuth login redirecting to localhost: Update GITPOD_DOMAIN environment variable to match your actual domain name
- MySQL connection refused errors: Ensure MySQL container is fully initialized before Gitpod startup using health checks
- MinIO storage errors during workspace snapshots: Check MINIO_ACCESS_KEY and MINIO_SECRET_KEY match Gitpod configuration
- Registry push/pull failures: Verify registry container has write permissions to registry-data volume mount
- Workspace creation timeout: Increase Docker daemon timeout settings and verify network connectivity between containers

