One of the most frustrating things about being a new hire, i.e. me. Is that if the company is a little small or the team is not used to seeing new faces, the process of getting started is kind of a pain. When I started I remember begging for instructions on what is going on asking if I need this tool or permission of this, or this dependency and I literally couldn't no any meaningful work for like 2-3 weeks until everything was sorted and I knew kind of what was going on... And then when you move to a different repo or a different project you have to start this process all over again.

Surely, I thought to myself. Surely there is a better way. Surely I am not going to be stuck in persistent onboarding purgatory again and again and again right?

Turns out there is!

Devcontainers

So what even is a devcontainer? The dev container spec defines a standard for any development tool to use a container as a full-featured development environment. It's not really a single download it's based on an open specification, and the core of it is a file called devcontainer.json, which is a structured JSON metadata format that tools can use to store any needed configuration required to develop inside of local or cloud-based containerized coding.

You just drop a .devcontainer folder into your repo with this config file, and it tells VS Code (or other supporting tools) how to access or create a development container with a well-defined tool and runtime stack. This container can be used to run an application or to separate tools, libraries, or runtimes needed for working with a codebase, and your workspace files are mounted from the local file system. The beautiful part? Unlike production containers that just run your deployed app, development containers include additional tools, libraries, and configurations that support the development process — they enable consistent, reproducible development environments that can be shared across team members.

Beyond repeatable setup, these same development containers provide consistency to avoid environment-specific problems across developers. So instead of me bugging everyone for three weeks asking "do I need Node 18 or 20?" and "wait, which version of Python?" — I just open the repo, the container spins up, and everything is already there. Same environment as everyone else on the team. No more onboarding purgatory.

Directory Setup

First you gotta setup your IDE, I am using VS Code so there is a dev container VS Code extension that allows you to use dev containers inside the VS Code editor.

And then setup your project directory like so:

project-root-folder
└── .devcontainer/           <-- This folder holds all the settings for your environment
    ├── devcontainer.json    <-- The main configuration file (tells VS Code how to build it)
    ├── Dockerfile           <-- Optional instructions to build the container image
    └── docker-compose.yml   <-- Optional: defines how to run services (DBs, etc.)

Devcontainer JSON

Before we get started with the JSON file, I'd recommend you first check the image repository on the devcontainers website, it contains some really useful base images that can get you started for a diverse range of development. The problem is that the ghcr links that the image advertises don't actually work all the time, I dunno why, so you gotta click into the image that takes you to the Github page where you can use the mcr links which work.

‍

Now to explain the actual JSON, here is the main structure of the devcontainer.json file:

{
  "name": "My Project Dev Environment",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:18",
  "features": {},
  "customizations": {},
  "forwardPorts": [],
  "postCreateCommand": ""
}

Common Configs

1. name — Give it a friendly name

"name": "Python 3 Development"

2. image — The base Docker image

"image": "mcr.microsoft.com/devcontainers/python:3.11"

This is the starting point — a pre-built image with your language/tools already installed. Microsoft provides many ready-to-use images.

OR use build to create a custom image:

"build": {
  "dockerfile": "Dockerfile",
  "context": ".."
}

3. features — Add extra tools (plug-and-play!)

"features": {
  "ghcr.io/devcontainers/features/git:1": {},
  "ghcr.io/devcontainers/features/docker-in-docker:2": {},
  "ghcr.io/devcontainers/features/node:1": {
    "version": "18"
  }
}

Features are modular add-ons — need Git? AWS CLI? Docker? Just add them here without writing Dockerfile commands.

4. customizations — VS Code settings & extensions

"customizations": {
  "vscode": {
    "extensions": [
      "ms-python.python",
      "esbenp.prettier-vscode",
      "dbaeumer.vscode-eslint"
    ],
    "settings": {
      "editor.formatOnSave": true,
      "python.linting.enabled": true
    }
  }
}

• extensions: Auto-install these VS Code extensions inside the container
• settings: Apply these VS Code settings automatically

5. forwardPorts — Access container services locally

"forwardPorts": [3000, 5432, 8080]

If your app runs on port 3000 inside the container, this lets you access it at localhost:3000 on your machine.

6. postCreateCommand — Run setup commands

"postCreateCommand": "npm install && npm run build"

Runs once after the container is created. Great for installing dependencies

• postCreateCommand After container is created (once)
• postAttachCommandEvery time you attach to the container
• postStartCommandEvery time container starts

7. mounts — Connect folders/files

"mounts": [
  "source=${localWorkspaceFolder}/.env,target=/app/.env,type=bind"
]

Share files between your computer and the container.

This is particularly useful for your SSH configs

8. remoteUser — Who runs commands

"remoteUser": "vscode"

The user inside the container. Usually vscode or root.

9. containerEnv — Environment variables

"containerEnv": {
  "NODE_ENV": "development",
  "API_URL": "http://localhost:8080"
}

Set environment variables available inside the container.

Complete Example

{
  "name": "Node.js + PostgreSQL",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:24",
  
  "features": {
    "ghcr.io/devcontainers/features/git:1": {}
  },
  
  "forwardPorts": [3000, 5432],
  
  "postCreateCommand": "npm install",
  
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ],
      "settings": {
        "editor.formatOnSave": true
      }
    }
  },
  
  "containerEnv": {
    "NODE_ENV": "development"
  },
  
  "remoteUser": "node"
}

Then in VS Code with the extension you can build the container and then reopen in container

Now I just gotta convince my team.