Devcontainers Quickstart Guide
Dev Containers provide a consistent, reproducible development environment using containerization. This guide helps you get started with Dev Containers in Visual Studio Code on Bluefin.
What are Devcontainers?
Dev Containers allow you to use a Docker container as a full-featured development environment. Your entire development environment - including tools, runtime, dependencies, extensions, and settings - is defined in configuration files that can be versioned and shared with your team.
Why Use Dev Containers?
- Consistency: Same environment across different machines and team members
- Isolation: Keep project dependencies separate from your host system
- Reproducibility: Version-controlled development environment
- Onboarding: New team members can start coding immediately
Prerequisites
Before you begin, ensure you enabled developer mode on Bluefin.
Installation and Setup
2. Verify Container Runtime
Ensure Docker or Podman is running:
# For Podman (default on Bluefin)
podman --version
# For Docker
docker --version
Getting Started
Option 1: Start with an Existing Project
- Open your project in VS Code
- Add Dev Container configuration:
- Open Command Palette (
Ctrl+Shift+P
) - Run:
Dev Containers: Add Dev Container Configuration Files...
- Choose a template that matches your technology stack
- Open Command Palette (
- Reopen in container:
- VS Code will show a notification to "Reopen in Container"
- Or use Command Palette:
Dev Containers: Reopen in Container
Option 2: Clone and Open in Container
- Clone a repository with Dev Container support:
- Open Command Palette (
Ctrl+Shift+P
) - Run:
Dev Containers: Clone Repository in Container Volume...
- Enter the repository URL
- VS Code will clone and open the project in a container
- Open Command Palette (
Option 3: Create New Project from Template
- Start from a template:
- Open Command Palette (
Ctrl+Shift+P
) - Run:
Dev Containers: New Dev Container...
- Choose a template or "Show All Definitions"
- Select your preferred technology stack
- Open Command Palette (
Understanding Dev Container Files
When you add Dev Container configuration, VS Code creates a .devcontainer
folder with:
devcontainer.json
: Main configuration fileDockerfile
(optional): Custom container definitiondocker-compose.yml
(optional): Multi-container setup
Basic devcontainer.json Example
{
"name": "Node.js",
"image": "mcr.microsoft.com/devcontainers/javascript-node:18",
"features": {
"ghcr.io/devcontainers/features/git:1": {}
},
"extensions": ["ms-vscode.vscode-typescript-next"],
"forwardPorts": [3000],
"postCreateCommand": "npm install"
}
Working with Dev Containers
Common Commands
Access these through Command Palette (Ctrl+Shift+P
):
Dev Containers: Reopen in Container
- Open current folder in containerDev Containers: Reopen Locally
- Return to local developmentDev Containers: Rebuild Container
- Rebuild after config changesDev Containers: Show Container Log
- View container build/run logsDev Containers: Open Container Configuration File
- Edit devcontainer.json
Port Forwarding
Dev Containers automatically forward ports specified in your configuration. You can also:
- Forward additional ports:
Ports
panel in VS Code - Configure in devcontainer.json: Add ports to
forwardPorts
array - Access via localhost: Forwarded ports work like local development
Extensions and Settings
- Automatic installation: Extensions listed in
devcontainer.json
install automatically - Container-specific settings: Configure VS Code settings per container
- Persistent data: Use volumes for data that should persist between rebuilds
Advanced Features
Dev Container Features
Add pre-built tools and configurations using Dev Container Features:
{
"features": {
"ghcr.io/devcontainers/features/git:1": {},
"ghcr.io/devcontainers/features/github-cli:1": {},
"ghcr.io/devcontainers/features/node:1": {
"version": "18"
}
}
}
Multi-Container Development
Use docker-compose for complex setups with databases, services, etc.:
{
"name": "App with Database",
"dockerComposeFile": "docker-compose.yml",
"service": "app",
"workspaceFolder": "/workspace"
}
Lifecycle Scripts
Automate setup with lifecycle hooks:
{
"postCreateCommand": "npm install && npm run setup",
"postStartCommand": "npm run dev",
"postAttachCommand": "echo 'Container ready!'"
}
Command Line Interface
The Dev Container CLI provides command-line access to dev container functionality, allowing you to build, run, and manage dev containers without VS Code.
Installation
Install the Dev Container CLI using homebrew:
brew install devcontainer
You can also install it via npm:
npm install -g @devcontainers/cli
Basic Usage
Build a dev container:
devcontainer build .
Run a dev container:
devcontainer up .
Execute commands in a dev container:
devcontainer exec . bash
Build and run in one command:
devcontainer up --build .
Useful Commands
devcontainer --help
- Show all available commandsdevcontainer read-configuration .
- Parse and validate devcontainer.jsondevcontainer features install
- Install dev container featuresdevcontainer templates apply
- Apply a dev container template
Integration with CI/CD
The CLI is particularly useful for CI/CD pipelines where you want to build and test your application in the same environment as your development container:
# In your CI pipeline
devcontainer build .
devcontainer exec . npm test
For more detailed information, check the official Dev Container CLI documentation.
Tips for Bluefin Users
- Podman compatibility: Dev Containers work seamlessly with Podman on Bluefin
- Performance: Use volume mounts for better I/O performance
- Updates: Container images update automatically when rebuilding
- Integration: Works with Bluefin's container-focused workflow
Troubleshooting
Common Issues
Container won't start:
- Check container runtime is running (
podman ps
ordocker ps
) - Verify devcontainer.json syntax
- Review container logs in Output panel
Extensions not loading:
- Ensure extensions are listed in devcontainer.json
- Check if extensions support remote development
- Try rebuilding the container
Port access issues:
- Verify ports are forwarded in configuration
- Check firewall settings
- Ensure application binds to
0.0.0.0
notlocalhost
Getting Help
- Check VS Code's Output panel for detailed logs
- Use Dev Containers: Show Container Log command
- Review error messages in the notification area
Learn More
Official Documentation
- Dev Containers Overview - Complete VS Code guide
- Dev Container Specification - Official specification and reference
- devcontainer.json Reference - Configuration options
- Dev Containers Tutorial - Step-by-step tutorial
Templates and Examples
- Dev Container Templates - Pre-built templates for popular frameworks
- Dev Container Features - Reusable components and tools
- Sample Dev Containers - Example configurations
VS Code Remote Development
- Remote Development Extension Pack - Complete remote development toolkit
- Remote Development Tips - Troubleshooting guide
- Working with Containers - Advanced container scenarios
Community Resources
- Dev Containers Community - Community discussions and contributions
- Awesome Dev Containers - Curated list of resources
- Dev Container Registry - Browse available features and templates