Set up your PC to run devcontainers in VC Code

[lakruzz]

The repositories we set up are all standardized in a way that are defined by Devcontainers. While these are theoretically also supported by GitHub Code Spaces, the more satisfying — and recommended — experience is to run them locally on your PC.

Setup your PC to support Docker engine, VS Code and Git

You need your PC (host) to support:

1. VS Code — or an VC Code compliant variant you trust or like better: Cursor, Windsurf...
2. Docker engine — Any will do; Docker Desktop, Podman, OrbStack (MacOS only) pick your poison.
3. Git — probably already setup (⚠️ But on Windows using WSL with Ubuntu, you probably need to configure it...)

These are the only system requirements you have, everything else you need is self-contained in the repos.

The DevX promise

The repo (any) should be self-contained to the degree where it should be possible for any contributor to...

• Clone the repo
• Open it in the IDE
• Wait for the dev container to boot-strap itself

From this point any contributor — humans and agentic AIs alike — should be able to use all features of the development environment. Expect all of the following features to work flawlessly:

• Debugger
• Unit tests
• Static code analysis tools
• Trunk-based workflow
• Digitally signed commits
• pre-commit hook that supports the full shit-left experience

🛠️ D.I.Y — Resources

If you are an experienced developer, you probably don't want long detailed install instructions, so let's start with the bare essentials:

VS Code

OS	Installer	Command
all	Package	Download
macOS	brew	brew install --cask visual-studio-code
Windows	winget	winget install Microsoft.VisualStudioCode
Ubuntu	snap	sudo snap install code --classic

Docker Engine

Important

On windows, the Docker engine must be setup to use WSL (as opposed to Hyper-V)

Headless - No GUI

You do not need a GUI like Podman/Docker Desktop/Orbstack.
(On windows you run the Debian command in your Ubuntu Terminal - you don't even install docker in the Windows system).

OS	Installer	Command
macOS	brew	brew install docker colima 1
Windows	N/A
Debian	apt	sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin 2

Docker Desktop

OS	Installer	Command
all	Package	Download
macOS	brew	brew install --cask docker
Windows	winget	winget install Docker.DockerDesktop
Debian	apt	sudo apt install ./docker-desktop-[ARCH].deb3

Podman

OS	Installer	Command
all	Package	Download
macOS	brew	brew install podman-desktop
Windows	winget	winget install RedHat.PodmanDesktop
Debian	apt	sudo apt install podman4

Orbstack (Mac only)

OS	Installer	Command
macOS	Package	Download
macOS	brew	brew install orbstack

Install the VS Code MCP servers and Extensions

• Open VS Code.

Install GitHub MCP server*

• Open the extensions panel (CTRL+SHIFT+X) search for @mcp, click "Enable MCP servers marketplace"
• Find the "GitHub" MCP server and install it. (It will take you to the webbrowser to authorize the app)

Or simply run...

code --add-mcp '{"name":"io.github.github/github-mcp-server","type":"http","url":"https://githubcopilot.com","gallery":"https://api.mcp.github.com","version":"0.30.3"}'

Find and install (or just verify) the following extensions.

• WSL (Microsoft)
• Remote Development (Microsoft)
• Dev Containers (Microsoft)
• GitHub Copilot Chat (GitHub)

Or simply run...

code --install-extension ms-vscode-remote.remote-wsl
code --install-extension ms-vscode-remote.vscode-remote-extensionpack
code --install-extension ms-vscode-remote.remote-containers
code --install-extension GitHub.copilot-chat

👆IF YOU ARE COOL with the D.I.Y. approach👆

You can now run the final test to verify that you are done!

---

👀 HOW TO DO THIS ON WINDOWS

It's our observation that (sometimes) Windows users aren't always confident in Linux and the setup process is also a bit more complicated, because WSL (Windows Subsystem for Linux) is required to be installed first. So we have provided a detailed setup guide – specifically for Windows users.

Here's the task list:

1. Install dependencies in Windows (using PowerShell)
2. Set Ubuntu user and passwd
3. Install additional WSL utilities
4. Initialize git with nameand email
5. Install GitHub CLI
6. Authenticate GitHub CLI
7. Store the GitHub CLI token as a variable in your .profile
8. Test that all is working

In Windows

STEP 1: Install on Windows (use PowerShell)

Using winget (the built in CLI for package installs), the installation process is very straightforward. You can run these commands in a standard PowerShell terminal (or run as Admin). If you do not run as admin Windows may prompt you for permission during the install.

• Copy and paste this entire block of code into your PowerShell terminal and hit ↵

(You can also copy the commands one by one and run then individually)

# 1. Update the winget index to get the newest packages
winget update

# 2. Install VS Code
winget install -e --id Microsoft.VisualStudioCode

# 3. Install Docker Desktop
winget install -e --id Docker.DockerDesktop

# 4. Install WSL with Ubuntu 24.04 directly
wsl --install --distribution Ubuntu-24.04

# 5. Set Ubuntu 24.04 as the default WSL distribution
wsl --set-default Ubuntu-24.04

# 6. See that all is good and ready for reboot
wsl --list --verbose

# 7. Refresh Path to recognize 'code' command immediately
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

# 8. Pre-install VS Code extensions for WSL and GitHub Copilot
code --install-extension ms-vscode-remote.remote-wsl
code --install-extension ms-vscode-remote.vscode-remote-extensionpack
code --install-extension ms-vscode-remote.remote-containers
code --install-extension GitHub.copilot-chat

# 9. Pre-configure the GitHub Cloud MCP Server
code --add-mcp '{"name":"io.github.github/github-mcp-server","type":"http","url":"https://githubcopilot.com","gallery":"https://api.mcp.github.com","version":"0.30.3"}'

Important

⚠️YOU NEED TO RESTART YOUR PC⚠️
before you run the next steps.
This is required for the WSL and Docker features to fully register in the Windows kernel.

• Restart your PC

In Ubuntu

After the install we need to install and configure more stuff in Ubuntu

Open the "Ubuntu 24.04" app from your Start menu.

The following commands must all be run from the Ubuntu teminal.

Step 2: Set Ubuntu user and passwd

First time it will be prompted to create:

• user
• password

Step 3: Install WSL utilities

Note

WSLU
An open-source collection of command-line utilities designed to seamlessly bridge the gap between a Linux environment and your host Windows system.

Ubuntu in WSL is headless and out-of-the-box it doesn't know how to start a browser from the terminal. We need that. So we will install wslu

sudo apt update \
  && sudo apt install wslu -y \
  && echo 'export BROWSER=wslview' >> ~/.bashrc \
  && source ~/.bashrc

Step 4: Initialize git

user.nameand user.email must be set, or Git will refuse to run.

Tip

Set name to your full name, and the email to one that is registered with your GitHub account
e.g. GITNAME="Lars Kruse" & GITEMAIL="lakruzz@mindovermachine.dk"

# Copy this command to the terminal, but change the variables before you run it
GITNAME="YOUR NAME" GITEMAIL="YOUR@EMAIL" 

The run

git config --global user.name "$GITNAME"
git config --global user.email "$GITEMAIL"

Step 5: Setup GitHub CLI

We also want to be able to use the GitHub Cli.

Caution

To install the GitHub CLI (gh) on Ubuntu, sudo apt install gh is valid, BUT it is best to use the official GitHub repository rather than the default Ubuntu one. The version in the standard Ubuntu "apt" library is often outdated, which can cause issues with authentication.

At time of this writing (July 2026) the standard ubuntu source will give you gh in version 2.45.0 and the second will give you version 2.97.2.

Use GitHub CLI's own repository:

(type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) \
	&& sudo mkdir -p -m 755 /etc/apt/keyrings \
	&& wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
	&& sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
	&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
	&& sudo apt update \
	&& sudo apt install gh -y

Step 6: Setup GitHub authentication

First you will authenticate against GitHub and then store the token in you Ubuntu profile, this profile is read be each docker container that starts so effectively your Docker containers will inherit the GitHub authentication from the host.

To authenticate run:

gh auth login --scopes project --web --hostname github.com --git-protocol https --clipboard

Tip

The one-time code is already copied to the clipboard, so just press enter, paste the clipboard into the browser, accept the app, close the browser again.

Note

The gh cli looks for authentication in the following places in the following order, and stops with the first it finds:

• $GH_TOKEN Environment variable
• $GITHUB_TOKEN Environment variable
• ~/.config/gh/hosts.yml

Step 7: Store the GitHub CLI token as a variable in your .profile

The way you just authenticated, Your token is now stored in your /.config/gh/hosts.yml so it's persisted between logins. But for easier integration with Dev containers we will rather pass on a Environment variables to the container than mount host files. So next we will store the token in an environment variable:

echo "export GH_TOKEN=$(gh auth token)" >> ~/.profile
source ~/.profile

If you run gh auth status you will see that you now have both.

• Exit Ubuntu (run exit)
• Reopen Ubuntu and rerun gh auth status to see that both auth sources settings are now persisted.

👉 Optimize Docker Integration 👈 (no need to go here unless you experience problems)

• Open Docker Desktop on Windows.

• Go to Settings (⚙ icon).

• > Resources > WSL Integration Ensure "Enable integration with my default WSL distro" is enabled.

• > Resources > Advanced If you find that Docker is slow to wake up when you run your first command, you can experiment with disable "Resource Saver"

• > General Make sure "Use containerd for pulling and storing images" is checked. It allows for faster image pulls and better support for multi-platform builds.

The .wslconfig file
WSL can sometimes try to "eat" all your RAM. You can cap its appetite by creating a configuration file in Windows.

• Open PowerShell and type: notepad "$env:USERPROFILE\.wslconfig"
  Paste this in (adjusting memory to about 50% of your total RAM):

Ini, TOML
[wsl2]
# Limit VM memory to 8GB (adjust to your needs)
memory=8GB
# Give it 4 cores
processors=4
# Automatically reclaim unused memory from the VM back to Windows
autoMemoryReclaim=gradual

Save and restart WSL by running wsl --shutdown in PowerShell.

Done!

🧪 The final test

Let's clone a simple, open source repo, that uses dev containers and see if we can make it work:

cd ~
mkdir -p github/mindovermachine-dev
cd github/mindovermachine-dev
gh repo clone mindovermachine-dev/regenerative-model
code regenerative-model

• When the project opens in VS Code you will be asked if you want to "Reopen in Dev Container" - choose that option.

Docker will now build the container.

When the container is up and running

•  I will probably also discover the default.code-workspace and ask if you want to work in that code space — Choose that option

The repo you have opened is the source for (model.mindovemachine.dk)[https://model.mindovemachine.dk] you can build it locally and run the dev server.

• Open the terminal and run

bundle exec rake jekyll:serve

Footnotes

1. Start the engine in the terminal with colima start ↩

2. Make sure WSL supports systemd; in /etc/wsl.conf be sure to add systemd=truein the [boot] section. ↩

3. This command is and abstraction. Installing Docker Desktop on Ubuntu requires manually downloading the .deb package for your architecture first. Alternatively, on Linux, you probably can do without the graphical UI shell, use sudo apt install docker-ce to get Docker Community Edition (CE) - it's quite sufficient (even recommended) for our purpose. ↩

4. Using apt install podman handles the core engine installation on Linux. Graphical user interface installs generally leverage Flatpak via flatpak install flathub io.podman_desktop.PodmanDesktop ↩

[lakruzz]

Tip

Use the code --add-mcp command to add MCP servers to VS Code

Instead of locating and hacking the mcp.json file directly, code --add-mcp is an in-line editor (like git config) it is a cross-platform uniform way to manipulate MCP server setup in VS Code.

• On Windows: It targets %APPDATA%\Code\User\mcp.json
• On macOS: It targets ~/Library/Application Support/Code/User/mcp.json
• On Linux: It targets ~/.config/Code/User/mcp.json

Example: (use in the instructions above)

# Configure the GitHub MCP server
code --add-mcp '{"name":"io.github.github/github-mcp-server","type":"http","url":"https://githubcopilot.com","gallery":"https://api.mcp.github.com","version":"0.30.3"}'

[lakruzz]

Caution

The previous instructions created a bit of a mess in the Windows install.
Here's how to clean up!

In the previous instructions the installation of wsl, and then installation of Ubuntu 24-04 were split in two seperate commands (in PowerShell)

wsl --install
winget install Canonical.Ubuntu.2404

But the WSL default installs Ubuntu and then manual install added Ubuntu 24.04 we ended up with two different Ubuntu distros. Which caused quite some confusion.

This is now locked in with the following step:

# 4. Install WSL with Ubuntu 24.04 directly
wsl --install --distribution Ubuntu-24.04

Here's an instruction on how to clean it up, if you ended with two distros.

# see the distros you have
wsl --list --verbose

# Set Ubuntu 24-04 as the default
wsl --set-default Ubuntu-24.04

# Unregister the one you don't need
wsl --unregister Ubuntu

...and then you may have to have to run the Ubuntu setup instructions — and the rest of the steps in the instruction — again.