Introduction to .devcontainer

Introduction Did you know there is a "Development Container" specification that allows you to use containers as fully functional development environments?

IDE tools like Visual Studio Code (VSCode) and JetBrains IDEs support this specification.

I work in Visual Studio Code (VSCode), so I’d like to demonstrate how easy it is to set up such an environment for your project.

Running a development environment in a container is beneficial, at least to protect your host system from potentially malicious scripts, such as those from installed packages. Development Containers greatly simplify the configuration and use of containers through integration with IDEs.

Although IDEs offer a setup wizard you can explore on your own (open the Command Palette and type >Dev Containers), I’ll focus on a specific case in this short article.

Case

We have a Next.js application that uses a Redis database.

The goal is for VSCode to set up a "ready-to-go" environment, installing everything needed for development. Optionally, we also want our application to automatically run in development mode, rebuilding whenever the code changes.

Setup You’ll need Docker installed on your host system and the Dev Containers extension in VSCode. It might already be preinstalled.

1?? Create a .devcontainer folder in the root of your project. 2?? Create a .devcontainer/devcontainer.json file. In this file, we will define our development environment and specify the name of the main service, which we will describe later in the docker-compose.yml file. The full specification for devcontainer.json is available here.

{
	"name": "NextJS + Redis",
	"dockerComposeFile": "docker-compose.yml",
	"service": "next",
	"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
	"forwardPorts": [
		3000
	],
	"onCreateCommand": "[ ! -f .env ] && cp .env.example .env || true",,
	"postStartCommand": "npm install --include=dev && npm run dev",
	"customizations": {
		"vscode": {
			"extensions": [
				"unifiedjs.vscode-mdx",
				"esbenp.prettier-vscode",
				"ms-azuretools.vscode-docker",
				"cweijan.vscode-redis-client",
				"bradlc.vscode-tailwindcss",
				"Gruntfuggly.todo-tree"
			]
		}
	}
}         

Please note:

• onCreateCommand – This allows us to execute an operation when the container is created. Here, we copy .env.example to .env if the .env file doesn’t exist yet. This action creates the file directly on the host in the project folder, saving time for anyone cloning the project for the first time.
• postStartCommand – After everything is up and running, we can install dependencies. For demonstration purposes, I also start the application in dev mode. This step is optional—you can always run commands like npm run dev manually in the terminal.
• customizations.vscode.extensions – This defines a set of extensions that will be added to the VSCode environment. The required extensions may vary from project to project, and thanks to containerization, VSCode won’t load unnecessary plugins. For example, in this project, I use cweijan.vscode-redis-client to browse the Redis database.

3?? Create the file .devcontainer/docker-compose.yml.

version: "3.8"

services:
  next:
    build:
      context: ..
      dockerfile: .devcontainer/Dockerfile

    volumes:
      - ../..:/workspaces:cached
    network_mode: service:redis
  redis:
    image: redis:latest
        

Both containers will operate within the same network, allowing the Next.js container to access the Redis host.

4?? Create the file .devcontainer/Dockerfile.

FROM mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm
RUN apt-get update && apt-get install -y iputils-ping        

In the Dockerfile, we prepare the application environment image.

It’s important not to install dependencies or create files like .env here. We perform these operations in .devcontainer/devcontainer.json for a reason: if we do them in the Dockerfile, mounting the project folder will effectively override those installations.

As a result, we now have a .devcontainer folder in the root of the project containing three files: devcontainer.json, docker-compose.yml, and Dockerfile. Please check.

5?? Let's start our development environment.

VSCode will automatically suggest launching the environment from the .devcontainer folder by default.

If this didn’t happen, you can open the Command Palette (On Mac: ? + SHIFT + P) and type, for example, ">Dev Containers: Rebuild and Reopen in Container".

The first time you run it, it will take some time for the images and containers to be built.

After that, you will see that the application has started. In my case, it looks like this:

Once you’ve confirmed that the application is accessible at https://localhost:3000, you can stop the task in the terminal using CTRL + C.

Starting your application again will be easy—just use the VSCode terminal. All terminal sessions will run inside the Next.js container, isolated from the host system.

Exiting this mode is also simple. You just need to reopen the folder "locally." Open the Command Palette and type: >Dev Containers: Reopen Folder Locally.

Screenshots

Possible Issues

I’ve encountered situations a few times where the environment wouldn’t start due to an incomplete Docker container. This issue can be resolved by manually stopping the containers. Fortunately, the containers have clear naming conventions.

For example: