Why won't my fucking container start?

First, check if Docker Desktop is actually running. It lies about its status half the time - the whale icon shows green but the daemon crashed 20 minutes ago. Run `docker ps` - if you get "Cannot connect to Docker daemon", restart Docker Desktop and wait 5 minutes for it to actually boot up. On Windows, it'll sit there saying "Starting..." for ages before it works.Common errors:- `Error response from daemon: pull access denied`: You're trying to pull a private image without being logged in- `port is already allocated`: Something's already using that port. Change the port in devcontainer.json or kill whatever's using it- `no space left on device`: Docker's eaten your disk space. Run `docker system prune -a` to clean up

Why is file sync so fucking slow on Windows/Mac?

Docker Desktop on Windows and Mac uses a VM, and file sharing between your host OS and the VM is garbage. Solutions:- Use named volumes for `node_modules`: `"mounts": ["source=/workspace/node_modules,target=/workspace/node_modules,type=volume"]`- On Windows, make sure you're using WSL2 backend, not Hyper-V- On Mac, try the new VirtioFS file sharing (it's faster but still not great)- For large projects, consider developing inside WSL2 on Windows or using a cloud development environment

The container builds but VS Code won't connect

This happens a lot. Usually it's:1. The container is running but the VS Code server inside it crashed. Check the "Dev Containers" output log in VS Code.2. The firewall is blocking the connection. Try disabling it temporarily.3. VS Code is trying to connect to the wrong port. Check your `forwardPorts` config.4. The container doesn't have the VS Code server installed. Some minimal base images are too minimal.Quick fix: Close VS Code, run `docker kill $(docker ps -q)`, then try again.

Do dev containers work with our corporate VPN/proxy setup?

Sometimes. Dev containers inherit your host's network settings, so if your corporate proxy lets Docker work, dev containers should work too. Common issues:- SSL certificates aren't trusted inside the container - you'll need to copy your corporate CA certificates- Proxy settings don't get passed through - set them in your devcontainer.json- Internal package registries aren't accessible - configure npm/pip/whatever to use your internal registries

My container keeps running out of memory

Docker Desktop limits containers to 2GB RAM by default, which is fucking ridiculous for modern development. Go to Docker Desktop settings, increase the memory limit to at least 4-8GB. Also check your container for:- Memory leaks in your application- Large databases running inside the container (move them to a separate service)- Too many background processes

How do I get my SSH keys and Git credentials working?

VS Code automatically shares your Git credentials and SSH keys with dev containers if they're in the default locations (`~/.ssh`, `~/.gitconfig`). If that doesn't work:- Check that SSH agent is running on your host- Make sure your keys aren't password-protected (or use ssh-agent to cache the password)- For corporate setups, you might need to copy your corporate CA certificates into the containerDon't put secrets in your devcontainer.json file - they'll end up in git and your security team will be pissed.

What happens to my database when I rebuild the container?

If you put the database inside the dev container, it gets wiped every time you rebuild. Don't do this. Use Docker Compose to run your database in a separate container with a volume, or use a cloud database. Your devcontainer.json can start up dependent services:```json"dockerComposeFile": "docker-compose.yml","service": "app","workspaceFolder": "/workspace"```

Can I develop offline after the initial setup?

Yes, once the container is built and running, you can code, build, and test offline. But you can't:- Install new packages (npm, pip, etc.) without internet- Pull new Docker images or rebuild with new features- Use VS Code extensions that need to download additional components- Access any external APIs your app depends on (obviously)

Why is debugging not working?

Check these in order:1. Is the debug port exposed in your devcontainer.json? Add it to `forwardPorts`2. Is your debugger trying to connect to localhost? It should connect to the container IP3. Are you running the debug server inside the container? Some frameworks start it automatically, others don't4. Check the VS Code "Debug Console" for actual error messages instead of guessingFor [Python](https://code.visualstudio.com/docs/python/debugging), [Node.js](https://code.visualstudio.com/docs/nodejs/nodejs-debugging), and other languages, debugging usually "just works" once the ports are configured right.

Currently viewing the AI version

Switch to human version

Development Containers - Technical Reference Guide

Configuration Requirements

System Prerequisites

Docker Desktop: Latest version required (older versions have critical bugs)
VS Code with Dev Containers extension
RAM: 4GB+ minimum (not 1GB as documented - Docker Desktop alone uses 2GB)
Storage: 10GB+ minimum (base images are larger than claimed)

Platform-Specific Critical Issues

Windows: WSL2 backend mandatory for acceptable file performance, Hyper-V requires reboot
Mac: Docker Desktop randomly stops, file sync inherently slow
Linux: Generally stable platform

Core Architecture Components

devcontainer.json Configuration File

Defines Docker image, VS Code extensions, port forwarding, lifecycle hooks
Must be committed to git for team consistency
Test locally before committing to avoid breaking team environments

Docker Image Foundation

Use Microsoft pre-built images (Node, Python, .NET, Java) as starting point
Custom Dockerfiles increase complexity and failure probability
Base images include OS, language runtimes, basic dev tools

Editor Integration

VS Code: Primary support, invented the standard
GitHub Codespaces: Browser-based VS Code using dev containers
Gitpod: Alternative cloud provider

Resource Requirements and Performance

Memory Allocation

Docker Desktop default 2GB limit inadequate for modern development
Increase to 4-8GB minimum through Docker Desktop settings
Monitor for memory leaks in applications and excessive background processes

File Sync Performance Issues

Critical Problem: Windows/Mac file sharing through VM extremely slow
Solutions:

Named volumes for node_modules: "mounts": ["source=/workspace/node_modules,target=/workspace/node_modules,type=volume"]
Windows: Use WSL2 backend exclusively
Mac: Enable VirtioFS file sharing (still suboptimal)

Storage Management

500MB-2GB per container plus Docker cache
Regular cleanup required: docker system prune -a
Use volumes for persistent data (databases, node_modules)

Critical Warnings and Failure Modes

Container Startup Failures

Common Issues:

Docker daemon status false positive (shows green but crashed)
Port conflicts: "port already allocated"
Disk space exhaustion
Authentication failures for private images

Diagnostic: Run docker ps to verify daemon connectivity

VS Code Connection Failures

Symptoms: Container builds but VS Code won't connect
Root Causes:

VS Code server crash inside container
Firewall blocking connection
Wrong port forwarding configuration
Minimal base images missing VS Code server

Resolution: Close VS Code, docker kill $(docker ps -q), retry

Network and Security Issues

Corporate Environment Problems:

SSL certificates not trusted in container
Proxy settings not inherited
Internal package registries inaccessible
VPN connectivity interference

Data Persistence Failures

Critical Warning: Database inside dev container gets wiped on rebuild
Solution: Use Docker Compose for separate database container with volume

Implementation Best Practices

Team Adoption Strategy

Start with single project using official template
Test on all team platforms before rollout
Address performance issues early
Commit .devcontainer/ folder to version control

Template Selection Priority

Use official language templates (Node.js, Python, Java, .NET, Go)
Customize incrementally from working base
Avoid custom Dockerfile unless absolutely necessary

Feature Management

Use pre-packaged features over custom installation scripts
150+ official features available for common tools
Community features for specialized requirements

Decision Criteria vs Alternatives

Factor	Dev Containers	Local Development	Virtual Machines	Docker Compose
Setup Time	2-5 minutes (2 hours if Docker fails)	30 minutes to abandonment	15-30 minutes + OS	5-10 minutes
Environment Consistency	Identical across machines	"Works on my machine"	Consistent but slow	Services only
Resource Usage	~100MB RAM + Docker overhead	Native speed	2-8GB+ RAM black hole	Variable service load
File Performance	Fast Linux, slow Windows/Mac	Native speed	Decent	Fast services, variable code
Team Onboarding	"Reopen in Container" button	Wiki setup instructions	VM image distribution	20-step process

Cost-Benefit Analysis

Benefits

Onboarding: 6-hour setup reduced to 5-minute container launch
Environment Isolation: Complete project separation prevents conflicts
Cross-Platform: Same Ubuntu environment regardless of host OS
Production Parity: Identical container in development and production

Costs

Learning Curve: Docker and container concepts required
Performance Overhead: File sync latency on Windows/Mac
Debugging Complexity: Additional network layer for debugging
Resource Consumption: Docker Desktop overhead

Break-Even Point

Teams with 3+ developers recover setup time investment within first month

Troubleshooting Decision Tree

Memory Issues

Increase Docker Desktop memory limit to 8GB
Check for application memory leaks
Move databases to separate containers
Reduce background processes

File Performance Issues

Implement named volumes for package directories
Enable platform-specific optimizations (WSL2, VirtioFS)
Consider cloud development environment for critical performance

Authentication/Networking

Verify SSH agent running on host
Copy corporate CA certificates if required
Configure proxy settings in devcontainer.json
Test VPN compatibility

Debugging Setup

Expose debug ports in forwardPorts configuration
Verify debugger connects to container IP, not localhost
Ensure debug server runs inside container
Check VS Code Debug Console for specific errors

Cloud Development Alternatives

When Local Fails

GitHub Codespaces: VS Code in browser, $10/month cost
Gitpod: Alternative cloud provider
DevPod: Open source option (early development)

Use Cases for Cloud

Local Docker issues persistent
Team members on incompatible hardware
Need for consistent high-performance environment
Corporate restrictions on local virtualization

Useful Links for Further Investigation

Resources That Don't Suck

Link	Description
Dev Containers Spec	The official spec. Dry but accurate, unlike most documentation. This is where the JSON schema lives and where you go when VS Code does something weird.
VS Code Dev Containers	Microsoft's docs are actually good for once. Has real examples that work, not the usual "hello world" bullshit. Start here if you're new to this.
GitHub Codespaces Guide	If you're paying for Codespaces, this tells you how to not waste money on it. Decent coverage of the billing gotchas.
Official Templates	Pre-built configs that save you hours of YAML hell. Use these unless you enjoy pain. The Node, Python, and Java ones actually work out of the box.
Dev Container Images	Base images that won't break randomly. Microsoft maintains these so they actually get updated. Better than some random Dockerfile you found on Stack Overflow.
Features Registry	LEGO blocks for your container. Want Node 18? There's a feature. Want to install kubectl? There's a feature. Beats writing shell scripts that break on different architectures.
GitHub Codespaces	VS Code in the browser. Costs money but your time is worth more than $10/month. Works better than trying to debug Docker Desktop on a Thursday afternoon.
Gitpod	Same idea, different company. Both work better than spending 2 hours fixing your local Docker install because it decided to shit the bed.
DevPod	Open source version of the above. Still in early days but might be worth watching if you don't trust Microsoft or Gitpod with your code.
VS Code Remote Troubleshooting	Bookmark this. You'll need it when containers won't start, ports won't forward, or VS Code just stops connecting for no fucking reason.
Docker Performance on Mac/Windows	File sync is slow, Docker Desktop uses too much memory, and your laptop sounds like a jet engine. This page explains why and what you can do about it (spoiler: not much).
DevContainers GitHub	Where the magic happens. Issues, discussions, and the occasional useful community template. Most of the time it's people asking why their container won't start.
Dev Container CLI	Command-line tool for when you don't want to use VS Code. Good for CI/CD or if you're one of those Vim people who refuses to admit editors have evolved.

Development Containers - Technical Reference Guide

Configuration Requirements

System Prerequisites

Platform-Specific Critical Issues

Core Architecture Components

devcontainer.json Configuration File

Docker Image Foundation

Editor Integration

Resource Requirements and Performance

Memory Allocation

File Sync Performance Issues

Storage Management

Critical Warnings and Failure Modes

Container Startup Failures

VS Code Connection Failures

Network and Security Issues

Data Persistence Failures

Implementation Best Practices

Team Adoption Strategy

Template Selection Priority

Feature Management

Decision Criteria vs Alternatives

Cost-Benefit Analysis

Benefits

Costs

Break-Even Point

Troubleshooting Decision Tree

Memory Issues

File Performance Issues

Authentication/Networking

Debugging Setup

Cloud Development Alternatives

When Local Fails

Use Cases for Cloud

Useful Links for Further Investigation

Resources That Don't Suck

Related Tools & Recommendations

VS Code Settings Are Probably Fucked - Here's How to Fix Them

VS Code Alternatives That Don't Suck - What Actually Works in 2024

VS Code Performance Troubleshooting Guide

GitOps Integration Hell: Docker + Kubernetes + ArgoCD + Prometheus

Ona (formerly Gitpod) - Linux Development Environments in the Cloud

Docker Desktop Critical Vulnerability Exposes Host Systems

Docker Desktop Became Expensive Bloatware Overnight - Here's How to Escape

Docker Desktop Security Problems That'll Ruin Your Day

CodeSandbox - Browser-Based Dev Environment That Actually Doesn't Suck

jQuery - The Library That Won't Die

AWS RDS Blue/Green Deployments - Zero-Downtime Database Updates

Podman - The Container Tool That Doesn't Need Root

Docker, Podman & Kubernetes Enterprise Pricing - What These Platforms Actually Cost (Hint: Your CFO Will Hate You)

Podman Desktop - Free Docker Desktop Alternative

Nix Production Deployment - Beyond the Dev Environment

Nix - Package Manager That Actually Works

KrakenD Production Troubleshooting - Fix the 3AM Problems

Fix Kubernetes ImagePullBackOff Error - The Complete Battle-Tested Guide

DeepSeek Coder - The First Open-Source Coding AI That Doesn't Completely Suck

RAG on Kubernetes: Why You Probably Don't Need It (But If You Do, Here's How)