$docker.recipes

DevPod Development Environments

intermediate

DevPod for codespace-like development.

[i]Overview

DevPod is an open-source client-only tool that creates reproducible developer environments on any backend, inspired by GitHub Codespaces but with vendor independence. The loftsh/devpod-provider-docker component acts as a Docker-based provider that enables DevPod to spawn development containers using local Docker infrastructure, while the Docker Registry provides a private repository for storing and managing development container images. This combination creates a self-hosted alternative to cloud-based development environments like GitHub Codespaces or GitPod. The stack operates by having the DevPod provider interface with the local Docker daemon to create isolated development containers based on devcontainer.json specifications, while the registry component ensures fast access to custom base images and reduces external dependencies. This setup appeals to development teams requiring full control over their development infrastructure, organizations with strict data sovereignty requirements, or developers working in air-gapped environments where external codespace services aren't accessible.

[*]Key Features

  • [+]Docker provider backend for creating reproducible dev containers using devcontainer.json specifications
  • [+]Private Docker registry for caching and storing custom development environment images
  • [+]Privileged container access enabling nested Docker operations and system-level development
  • [+]DevPod CLI integration supporting workspace creation, management, and SSH access
  • [+]Docker socket mounting for direct container orchestration and Docker-in-Docker scenarios
  • [+]VS Code integration through DevPod extension for direct IDE connectivity
  • [+]Vendor-agnostic development environment provisioning independent of cloud providers
  • [+]Local development container caching reducing startup times for repeated environments

[#]Common Use Cases

  • [1]Creating standardized development environments for distributed teams working on containerized applications
  • [2]Establishing secure development sandboxes in enterprise environments with strict network policies
  • [3]Building custom development toolchains with pre-configured language runtimes and debugging tools
  • [4]Testing application behavior across different development container configurations locally
  • [5]Providing consistent development environments for open-source projects with complex dependencies
  • [6]Setting up isolated development workspaces for client projects requiring different tooling versions
  • [7]Creating reproducible bug reproduction environments that match production container specifications

[!]Prerequisites

  • [!]Docker Engine 20.10+ with Docker Compose v2 support
  • [!]DevPod CLI installed on local development machine
  • [!]Minimum 4GB available RAM for concurrent development containers
  • [!]Understanding of devcontainer.json specification and VS Code development containers
  • [!]Basic knowledge of Docker registry operations and image management
  • [!]Port availability: 8080 for DevPod provider API and 5000 for Docker registry
[!]

WARNING: 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  devpod-provider: 
3    image: loftsh/devpod-provider-docker:latest
4    container_name: devpod-provider
5    restart: unless-stopped
6    privileged: true
7    ports: 
8      - "${PROVIDER_PORT:-8080}:8080"
9    volumes: 
10      - /var/run/docker.sock:/var/run/docker.sock
11      - devpod_data:/var/lib/devpod
12
13  registry: 
14    image: registry:2
15    container_name: devpod-registry
16    restart: unless-stopped
17    ports: 
18      - "${REGISTRY_PORT:-5000}:5000"
19    volumes: 
20      - registry_data:/var/lib/registry
21
22volumes: 
23  devpod_data: 
24  registry_data:

[$].env Template

[.env]
1# DevPod
2PROVIDER_PORT=8080
3REGISTRY_PORT=5000

[i]Usage Notes

  1. [1]Install DevPod CLI locally
  2. [2]Use devcontainer.json specs
  3. [3]Local registry for images
  4. [4]VS Code integration available

Individual Services(2 services)

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

devpod-provider
devpod-provider:
  image: loftsh/devpod-provider-docker:latest
  container_name: devpod-provider
  restart: unless-stopped
  privileged: true
  ports:
    - ${PROVIDER_PORT:-8080}:8080
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - devpod_data:/var/lib/devpod
registry
registry:
  image: registry:2
  container_name: devpod-registry
  restart: unless-stopped
  ports:
    - ${REGISTRY_PORT:-5000}:5000
  volumes:
    - registry_data:/var/lib/registry

[>]Quick Start

[terminal]
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  devpod-provider:
5    image: loftsh/devpod-provider-docker:latest
6    container_name: devpod-provider
7    restart: unless-stopped
8    privileged: true
9    ports:
10      - "${PROVIDER_PORT:-8080}:8080"
11    volumes:
12      - /var/run/docker.sock:/var/run/docker.sock
13      - devpod_data:/var/lib/devpod
14
15  registry:
16    image: registry:2
17    container_name: devpod-registry
18    restart: unless-stopped
19    ports:
20      - "${REGISTRY_PORT:-5000}:5000"
21    volumes:
22      - registry_data:/var/lib/registry
23
24volumes:
25  devpod_data:
26  registry_data:
27EOF
28
29# 2. Create the .env file
30cat > .env << 'EOF'
31# DevPod
32PROVIDER_PORT=8080
33REGISTRY_PORT=5000
34EOF
35
36# 3. Start the services
37docker compose up -d
38
39# 4. View logs
40docker 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/devpod-stack/run | bash

[?]Troubleshooting

  • [!]DevPod provider fails to start containers: Verify Docker socket permissions and ensure Docker daemon is accessible from within the provider container
  • [!]Registry push/pull operations timeout: Check registry_data volume permissions and ensure sufficient disk space for image storage
  • [!]VS Code cannot connect to DevPod workspace: Confirm DevPod provider is accessible on port 8080 and SSH keys are properly configured
  • [!]Development containers cannot access Docker daemon: Verify privileged flag is enabled for devpod-provider service and Docker socket is mounted correctly
  • [!]DevPod workspace creation hangs during image pull: Check registry connectivity and verify custom images exist in the local registry with correct tags
  • [!]Permission denied errors in development containers: Ensure user namespace mapping is configured correctly in devcontainer.json and container runs with appropriate user permissions

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

devpod-providerregistry

## Tags

#devpod#devcontainer#codespaces#remote-dev

## Category

Development Tools

## Related