How to Run VS Code in Docker: A Complete Docker VSCode Development Environment Setup

Configuring a docker vscode workflow involves running the VS Code Server inside a Docker container orchestrated by Docker Compose, with the Remote-Containers extension forwarding port 8443 to provide a seamless local editing experience.

A docker vscode setup isolates your entire development toolchain—compilers, linters, and the Docker CLI—inside containers while maintaining the familiar IDE interface on your host machine. Using the docker/compose repository as a reference implementation, you can create reproducible development environments that mount your source code and expose the VS Code Server for remote editing. This configuration ensures all team members use identical tool versions without installing dependencies locally.

Architecture of a Docker VSCode Environment

The docker vscode architecture follows a client-server model that separates your editing interface from the execution environment.

• VS Code (Client) runs on your host machine with the Remote-Containers extension installed.
• VS Code Server executes inside the Docker container managed by Docker Compose.
• Port 8443 exposes the VS Code Server process over TCP; the extension automatically forwards this port to your local machine.
• Source Mounting synchronizes your project files between host and container using volume binds.

The docker/compose repository provides foundational files for building custom dev-container images. The main Dockerfile at the repository root demonstrates how the official Compose binary is built, while pkg/e2e/fixtures/project-volume-bind-test/docker-compose.yml illustrates volume binding syntax used in testing scenarios.

Configuring the Dev Container Files

Create a .devcontainer directory at your project root to house the configuration files that define your docker vscode environment.

Creating devcontainer.json

The devcontainer.json file tells VS Code which Docker Compose service hosts the development environment and where to locate the workspace.

{
  "name": "Docker Compose Dev Container",
  "dockerComposeFile": ["../docker-compose.yml"],
  "service": "compose-dev",
  "workspaceFolder": "/workspace",
  "settings": {
    "go.toolsManagement.checkForUpdates": "local",
    "go.useLanguageServer": true
  },
  "extensions": [
    "ms-vscode.go",
    "ms-azuretools.vscode-docker"
  ],
  "postCreateCommand": "go mod download"
}

Key configuration points include the dockerComposeFile array pointing to the parent directory's docker-compose.yml, the service key selecting the compose-dev container, and the workspaceFolder matching the mount point defined in your Dockerfile.

Building the Custom Dockerfile

Create a Dockerfile.dev that extends the official VS Code Go devcontainer base and incorporates the Compose repository's build logic.

# Use the official VS Code Go devcontainer as a base

FROM mcr.microsoft.com/vscode/devcontainers/go:1.22

# Install Docker CLI so you can run `docker compose` inside the container

RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        docker.io && \
    rm -rf /var/lib/apt/lists/*

# Copy the Compose source (optional – only needed if you want to run `docker compose` from source)

WORKDIR /workspace
COPY . /workspace

# Build the Compose binary (mirrors the repo's Dockerfile steps)

RUN make build GO_BUILDTAGS="e2e"

This Dockerfile implements the same make build process found in the official Dockerfile at lines 77-88 of the docker/compose repository. Installing the Docker CLI enables the container to communicate with the host Docker daemon via the bind-mounted socket.

Configuring docker-compose.yml

Define the development service in your project-level docker-compose.yml to orchestrate the container and its dependencies.

version: "3.9"

services:
  compose-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      # Mount the project source into the container

      - .:/workspace:cached
      # Give the container access to the host Docker daemon

      - /var/run/docker.sock:/var/run/docker.sock
    # Expose the VS Code Server port; the Remote-Containers extension will forward it automatically

    ports:
      - "8443:8443"
    # Optional: start any ancillary services (e.g., a PostgreSQL DB) here

    # depends_on:

    #   - db

The cached flag optimizes file-system performance on macOS and Linux hosts. Exposing port 8443 aligns with the default VS Code Server port, though the Remote-Containers extension can override this if necessary. The volume binding syntax follows patterns established in pkg/e2e/fixtures/project-volume-bind-test/docker-compose.yml within the docker/compose repository.

Connecting VS Code to the Container

Once your configuration files are in place, open the project folder in VS Code and execute the Remote-Containers: Reopen in Container command from the command palette (F1). VS Code performs the following actions:

1. Executes docker compose up using your defined docker-compose.yml.
2. Builds the compose-dev image using Dockerfile.dev if it does not exist.
3. Starts the VS Code Server process inside the container and forwards port 8443 to your host.
4. Mounts your source code into /workspace with cached file system optimization.

The repository's .gitignore file already excludes the /.vscode/ directory, preventing accidental commits of local IDE configuration when working in this docker vscode setup.

Key Repository Files for Reference

The docker/compose repository contains several files that inform best practices for containerized development:

• Dockerfile (root): Demonstrates the official Compose binary build process using make build, which you can replicate in your dev container.
• pkg/e2e/fixtures/project-volume-bind-test/docker-compose.yml: Provides reference syntax for volume bindings used in the test suite.
• .gitignore: Already configured to ignore .vscode/, requiring no additional changes for your docker vscode workflow.
• docs/sdk.md: Documents Go SDK entry points for importing Compose packages directly within your development container.

Summary

• Port 8443 serves as the default VS Code Server port inside the container, automatically forwarded by the Remote-Containers extension.
• The docker/compose repository provides reference implementations including the root Dockerfile (lines 77-88) and test fixtures for volume configuration.
• Mounting /var/run/docker.sock grants the container access to the host Docker daemon, enabling nested docker compose commands.
• The .gitignore file in the repository already excludes .vscode/, ensuring clean version control when using this docker vscode setup.
• Using mcr.microsoft.com/vscode/devcontainers/go as a base image provides a pre-configured Go environment that VS Code recognizes immediately.

Frequently Asked Questions

What port does VS Code Server use inside the Docker container?

VS Code Server defaults to port 8443 when running inside a container. The Remote-Containers extension automatically detects and forwards this port to your host machine, creating a seamless connection between your local VS Code client and the server process without manual configuration.

How do I enable Docker commands inside the dev container?

Mount the host Docker socket by adding - /var/run/docker.sock:/var/run/docker.sock to the volumes section of your docker-compose.yml service definition. Install the Docker CLI in your Dockerfile (as shown in the docker/compose repository's examples) to allow the container to execute docker compose commands against the host daemon.

Can I reuse existing files from the docker/compose repository?

Yes. The Dockerfile at the repository root demonstrates the make build process (lines 77-88) that you can incorporate into your dev container image. Additionally, pkg/e2e/fixtures/project-volume-bind-test/docker-compose.yml provides tested volume binding syntax suitable for development environments.

Do I need to modify .gitignore for VS Code settings when using Docker?

No. The docker/compose repository already includes /.vscode/ in its .gitignore file. This exclusion prevents local editor settings from being committed when working with the docker vscode configuration, keeping your repository clean regardless of container-specific IDE customizations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}