docker.recipes

Gitpod Self-Hosted

advanced

Cloud development environments from Git repositories.

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.

Key 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

Common Use Cases

  • 1Enterprise development teams requiring on-premises code execution with centralized environment management
  • 2Educational institutions providing standardized programming environments for computer science courses
  • 3Open-source projects offering contributors instant development environments without local setup
  • 4Remote development teams needing consistent environments across different operating systems and hardware
  • 5Companies with strict data governance requirements preventing cloud-based development platforms
  • 6Development agencies managing multiple client projects with isolated, reproducible environments
  • 7Organizations 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  gitpod: 
3    image: eu.gcr.io/gitpod-core-dev/build/installer:latest
4    environment: 
5      - GITPOD_DOMAIN=${GITPOD_DOMAIN}
6      - GITPOD_PROTOCOL=https
7      - DB_HOST=mysql
8      - DB_PORT=3306
9      - DB_PASSWORD=${MYSQL_PASSWORD}
10    volumes: 
11      - gitpod-data:/var/gitpod
12      - /var/run/docker.sock:/var/run/docker.sock
13    ports: 
14      - "443:443"
15      - "80:80"
16    depends_on: 
17      - mysql
18      - minio
19      - registry
20    networks: 
21      - gitpod-network
22    restart: unless-stopped
23
24  mysql: 
25    image: mysql:8.0
26    environment: 
27      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
28      - MYSQL_DATABASE=gitpod
29      - MYSQL_USER=gitpod
30      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
31    volumes: 
32      - mysql-data:/var/lib/mysql
33    networks: 
34      - gitpod-network
35    restart: unless-stopped
36
37  minio: 
38    image: minio/minio:latest
39    command: server /data --console-address ":9001"
40    environment: 
41      - MINIO_ROOT_USER=${MINIO_ACCESS_KEY}
42      - MINIO_ROOT_PASSWORD=${MINIO_SECRET_KEY}
43    volumes: 
44      - minio-data:/data
45    networks: 
46      - gitpod-network
47    restart: unless-stopped
48
49  registry: 
50    image: registry:2
51    volumes: 
52      - registry-data:/var/lib/registry
53    networks: 
54      - gitpod-network
55    restart: unless-stopped
56
57volumes: 
58  gitpod-data: 
59  mysql-data: 
60  minio-data: 
61  registry-data: 
62
63networks: 
64  gitpod-network: 
65    driver: bridge

.env Template

.env
1# Gitpod
2GITPOD_DOMAIN=gitpod.localhost
3MYSQL_ROOT_PASSWORD=secure_root_password
4MYSQL_PASSWORD=secure_mysql_password
5MINIO_ACCESS_KEY=gitpod
6MINIO_SECRET_KEY=secure_minio_secret

Usage Notes

  1. 1Access via https://gitpod.localhost
  2. 2Configure OAuth with Git provider
  3. 3Prebuilds for faster startup
  4. 4Requires DNS configuration
  5. 5Kubernetes recommended for production

Individual Services(4 services)

Copy individual services to mix and match with your existing compose files.

gitpod
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
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
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
registry:
  image: registry:2
  volumes:
    - registry-data:/var/lib/registry
  networks:
    - gitpod-network
  restart: unless-stopped

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  gitpod:
5    image: eu.gcr.io/gitpod-core-dev/build/installer:latest
6    environment:
7      - GITPOD_DOMAIN=${GITPOD_DOMAIN}
8      - GITPOD_PROTOCOL=https
9      - DB_HOST=mysql
10      - DB_PORT=3306
11      - DB_PASSWORD=${MYSQL_PASSWORD}
12    volumes:
13      - gitpod-data:/var/gitpod
14      - /var/run/docker.sock:/var/run/docker.sock
15    ports:
16      - "443:443"
17      - "80:80"
18    depends_on:
19      - mysql
20      - minio
21      - registry
22    networks:
23      - gitpod-network
24    restart: unless-stopped
25
26  mysql:
27    image: mysql:8.0
28    environment:
29      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
30      - MYSQL_DATABASE=gitpod
31      - MYSQL_USER=gitpod
32      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
33    volumes:
34      - mysql-data:/var/lib/mysql
35    networks:
36      - gitpod-network
37    restart: unless-stopped
38
39  minio:
40    image: minio/minio:latest
41    command: server /data --console-address ":9001"
42    environment:
43      - MINIO_ROOT_USER=${MINIO_ACCESS_KEY}
44      - MINIO_ROOT_PASSWORD=${MINIO_SECRET_KEY}
45    volumes:
46      - minio-data:/data
47    networks:
48      - gitpod-network
49    restart: unless-stopped
50
51  registry:
52    image: registry:2
53    volumes:
54      - registry-data:/var/lib/registry
55    networks:
56      - gitpod-network
57    restart: unless-stopped
58
59volumes:
60  gitpod-data:
61  mysql-data:
62  minio-data:
63  registry-data:
64
65networks:
66  gitpod-network:
67    driver: bridge
68EOF
69
70# 2. Create the .env file
71cat > .env << 'EOF'
72# Gitpod
73GITPOD_DOMAIN=gitpod.localhost
74MYSQL_ROOT_PASSWORD=secure_root_password
75MYSQL_PASSWORD=secure_mysql_password
76MINIO_ACCESS_KEY=gitpod
77MINIO_SECRET_KEY=secure_minio_secret
78EOF
79
80# 3. Start the services
81docker compose up -d
82
83# 4. View logs
84docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/gitpod-complete/run | bash

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

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

gitpodmysqlminioregistry

Tags

#gitpod#cloud-dev#ide#workspace#remote-development

Category

Development Tools

Related Recipes

Ad Space