Everything required to use Podman error-free with Dev Containers on WSL2

[worldofgeese]

This guide is intended to spark a discussion about the many papercuts Windows developers will face when configuring Podman with Dev Containers on WSL2. All steps detailed here were necessary for achieving a successful, error-free, setup.

Is there any appetite from Podman devs to do a virtual "empathy session" where we all sit down and attempt to run the example Dev Container on WSL2, starting from zero? I think it could be fun! 😄 🪿 🌎

cc @n1hility @rhatdan who I've had fruitful discussions with in the past when I first created #15338.

---

Step 1: Initialize a Podman machine

podman machine init -m 16384 --now

---

Step 2: Resolve broken podman stats

Error: stats is not supported in rootless mode without cgroups v2

Follow these steps:

1. Open your WSL2 configuration file at %UserProfile%\.wslconfig.

2. Add or update the following configuration:

   [wsl2]
   kernelCommandLine = cgroup_no_v1=all

3. Save the file.

This configuration disables cgroups v1, enabling cgroups v2, and resolves microsoft/WSL#10050.

---

Step 3: Resolve shared mount warning

If you receive this warning:

"/" is not a shared mount, this could cause issues or missing mounts with rootless containers

Run these commands:

sudo mount -o remount,shared /
podman system reset

This resolves microsoft/vscode-remote-release#9303.

---

Step 4: Resolve rootless Podman issues

To work around issues with rootless Podman (such as permissions issues creating and manipulating directories and files), set the following in devcontainer.json:

"runArgs": [
  "--userns=keep-id"
],

Step 5: Allow locally built images to be pulled

For error, Pinging container registry localhost connection refused, create a custom Podman configuration file:

mkdir -p ~/.config/containers && cat > ~/.config/containers/containers.conf << 'EOF'
[engine]
compat_api_enforce_docker_hub=false
EOF

This resolves #19856

---

Step 6: Enable VS Code to connect to Podman socket

For error, RemoteSocket: path: /mnt/wslg/runtime-dir/podman/podman.sock is not available. modify or create /etc/wsl.conf within your Podman Machine to add:

[boot]
systemd=true

This resolves #16861

For context, see #15190 (comment):

FYI, this, along with #15338 look like barriers to using devcontainers hosted in \wsl$ from VS Code.

VS Code executes docker commands within WSL itself when they are contained within the wsl filesystem. This works in Docker Desktop, which makes docker.sock available in installed WSL distributions.

The other option is to configure VS Code to run the docker commands in the podman distribution. But this does not work due to #15338.

---

Step 7: Restart WSL2

wsl --shutdown

---

Example configuration files

Utilize these configuration examples for your Dev Container setup:

docker-compose.yml

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ../..:/opt/app-root/src
    command: sleep infinity
    init: true
    user: 1001:0
    tmpfs:
      - /opt/app-root/src/backstage/node_modules:mode=777
      - /opt/app-root/src/packages/app/node_modules:mode=777
      - /opt/app-root/src/packages/backend/node_modules:mode=777
    depends_on:
      - db
    userns_mode: "keep-id"
    env_file:
      - path: ./.env

  db:
    image: postgres:14.6
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_USER: postgres
      POSTGRES_DB: postgres
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s
    shm_size: '128mb'

volumes:
  postgres_data:

Dockerfile

# syntax=docker/dockerfile:1
ARG UV_VERSION=0.6.3
ARG NODEJS_VERSION=22
ARG HADOLINT_VERSION=2.12.1-beta

FROM ghcr.io/astral-sh/uv:$UV_VERSION AS uv
FROM ghcr.io/hadolint/hadolint:$HADOLINT_VERSION AS hadolint
FROM quay.io/fedora/nodejs-$NODEJS_VERSION AS base

FROM base
COPY --from=uv --chown=1001:0 /uv /uvx /bin/
COPY --from=hadolint /bin/hadolint /bin/

ENV PATH="$HOME/.local/bin/:$PATH"

USER 0
RUN chown -R 1001:0 /opt/app-root/src && chmod -R g=u /opt/app-root/src
RUN uv pip install --system --break-system-packages \
  mkdocs-techdocs-core mkdocs-git-revision-date-localized-plugin \
  mkdocs-include-markdown-plugin mkdocs-mermaid2-plugin
USER 1001

devcontainer.json

{
  "name": "Baseplate",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/opt/app-root/src/${localWorkspaceFolderBasename}",
  "forwardPorts": [3000,3001,3007,5432,5433,7000,7007,4000],
  "containerEnv": {
    "HOST_HOME": "${localEnv:HOME}",
    "DEVCONTAINER": "true"
  },
  "postStartCommand": "npm install -g corepack; corepack enable; yarn",
  "customizations": {
    "vscode": {
      "extensions": ["esbenp.prettier-vscode","dbaeumer.vscode-eslint","Orta.vscode-jest","eamodio.gitlens"]
    }
  },
  "remoteUser": "default"
}