Overview
Gitpod fully supports Development Containers, allowing you to standardize development environments across your team. Define your setup in a devcontainer.json
file to ensure consistent tools, dependencies, and configurations for all developers.
Benefits
Using Dev Containers with Gitpod provides several advantages:
- Standardized environments across all team members
- Consistent tooling with precisely defined dependency versions
- Isolated Linux VM environments, even when running locally
- Support for both single and multi-container development setups
- Version-controlled configuration that lives with your codebase
- Integration with VS Code and other supported editors
- Separation of development environment from local machine configuration
Configuration
File Location
Place your devcontainer.json
file in one of these standard locations:
.devcontainer/devcontainer.json
.devcontainer.json
Basic Configuration Example
This configuration:
- Uses a base Ubuntu image
- Adds Node.js LTS
- Includes ESLint and Prettier VS Code extensions
- Configures auto-formatting on save
- Forwards ports 3000 and 8080
Multiple Dev Container Configurations
You can manage multiple Dev Container configurations using Gitpod’s project feature. This allows you to define different environments for:
- Different branches or repositories
- Various development scenarios
- Specialized tasks requiring specific tools
Migration from .gitpod.yml
If you’re already using a .gitpod.yml
file, Gitpod provides tools to convert your existing configuration to the Dev Container format. Dev Containers offer a more standardized approach that works across multiple platforms and tools.
Known Limitations
When using Dev Containers with Gitpod, be aware of these limitations:
- Platform-specific features may not work with Gitpod Desktop
- Conflicting features can cause build failures (Gitpod will display an error message)
- Some Dev Container commands might behave differently in Gitpod’s environment
- When build errors occur, recovery mode is engaged, requiring manual intervention
Recommended Images
Microsoft provides well-maintained Dev Container base images for popular development stacks:
mcr.microsoft.com/devcontainers/base:ubuntu
- Ubuntu base imagemcr.microsoft.com/devcontainers/javascript-node
- Node.js developmentmcr.microsoft.com/devcontainers/python
- Python developmentmcr.microsoft.com/devcontainers/java
- Java developmentmcr.microsoft.com/devcontainers/go
- Go development
Advanced Configuration
Multi-Container Development
For more complex setups, you can define multiple containers using Docker Compose:
Adding Custom Features
Dev Container Features are self-contained, shareable units of installation code and configuration that let you quickly add tooling, runtimes, or libraries to your development container.
You can add features to your Dev Container by adding them to the features
section of your devcontainer.json
file:
Gitpod works well with many Dev Container Features, especially official ones that are designed with remote development environments in mind. Linux-based runners generally provide best compatibility with most Dev Container Features. Here’s what you should know:
- Community-supported features might require additional testing, as they may have been developed without specific consideration for compatibility.
- When using the Gitpod Desktop’s Mac runner, some features might not work right away with the Rosetta virtualization layer. See troubleshooting section
- Feature behavior can vary depending on base images, other installed features, and specific configurations in your setup.
Troubleshooting
If your Dev Container fails to build:
-
Check the Gitpod console for specific error messages
-
Verify that all specified features are compatible
-
Ensure image versions are correctly specified
-
Try rebuilding in recovery mode to debug the issue
Next Steps
- Explore the full Dev Container specification for advanced configurations
- Check out the Dev Container Feature catalog for additional tools and utilities
- Learn about Gitpod projects to manage multiple environments
Was this page helpful?