This guide documents the working setup for running the med-plan-assistant React project inside a VSCode dev container using WSL2 and Podman (no Docker Desktop). It assumes:

WSL2 is installed and configured
VSCode is installed with the Dev Containers extension on windows host and in WSL
The project repo is located at ~/git/med-plan-assistant inside WSL

📦 1. Install Podman in WSL (Ubuntu)

sudo apt update
sudo apt install -y podman

# Ensure Podman version is ≥ 4.9.3:
podman --version

⚙️ 2. Enable systemd and Podman socket

Edit /etc/wsl.conf:

[boot]
systemd=true

Then restart WSL:

wsl --shutdown

Enable Podman socket:

systemctl --user enable --now podman.socket

If podman.socket is masked or fails to start, create a custom service:

mkdir -p ~/.config/systemd/user
vim ~/.config/systemd/user/podman.service

Paste:

[Unit]
Description=Podman API Service
Requires=podman.socket
After=podman.socket

[Service]
ExecStart=/usr/bin/podman system service
Restart=on-failure
KillMode=process

[Install]
WantedBy=default.target

Reload and enable:

systemctl --user daemon-reload
systemctl --user enable --now podman.socket

Verify:

curl --unix-socket /run/user/1000/podman/podman.sock http://localhost/_ping

🧠 3. Configure Podman registry (to avoid interactive prompts)

Edit or create ~/.config/containers/registries.conf:

[registries.search]
registries = ["docker.io"]

🧰 4. Create .devcontainer Setup

Create .devcontainer folder in project root:

mkdir .devcontainer

Create .devcontainer/devcontainer.json and paste:

{
  "name": "React Dev Container",
  "build": {
    "dockerfile": "Dockerfile"
  },
  "customizations": {
    "vscode": {
      "settings": {
        "terminal.integrated.defaultProfile.linux": "zsh"
      }
    },
    "extensions": [
        "esbenp.prettier-vscode",
        "dbaeumer.vscode-eslint"
    ]
  },
  "forwardPorts": [3000],
  "postCreateCommand": "npm install",
  "remoteUser": "node"
}

Create .devcontainer/Dockerfile and paste:

FROM node:18

# Install some apt packages
RUN apt-get update && apt-get install -y zsh git vim tmux

# Variable for default user `node` to be used in the following steps
ARG USERNAME=node

# Ensure basic setup of default `node` user
# Not needed since node:18 already comes with a node user
#RUN useradd -ms /bin/zsh $USERNAME \
#    && chown -R node:node /home/$USERNAME

# Set zsh as default shell for node user
RUN chsh -s /bin/zsh node

# Ensure `node` user has access to `sudo`
RUN mkdir -p /etc/sudoers.d \
    && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME \
    && chmod 0440 /etc/sudoers.d/$USERNAME

# Set working directory
WORKDIR /workspace

# Use non-root user
USER $USERNAME

🚀 5. Reopen in Container

In WSL terminal navigate to project folder and open in VSCode:

cd ~/git/med-plan-assistant
code .

In VSCode:

Press F1 → Dev Containers: Reopen in Container
Wait for the container to build and launch
At least in case the dev container setup gets stuck, click on the Connecting to Dev Container (show log) status info in the bottom-right corner of the vscode window to open the Dev Containers console for troubleshooting.
- In case of an interactive prompt, press Enter to continue.
- Check for possible errors and fix as needed.

✅ 6. Verify Setup

Once inside the container open a new terminal and start the React app:

npm start

Access the app at http://localhost:3000

Live reload and port forwarding should work automatically.

🧩 Notes

📁 WSL Filesystem Performance

Performance is significantly better on native WSL filesystem (ext4) vs NTFS (/mnt/c/...). If you previously worked on NTFS, move or clone the repo to WSL filesystem:

git clone https://github.com/myusername/med-plan-assistant.git ~/git/med-plan-assistant
# or move existing copy (this can take many minutes especially if node_modules are present)
mv /mnt/c/Users/myusername/git/med-plan-assistant ~/git/

Then reopen in VSCode:

cd ~/git/med-plan-assistant
code .

In my case the startup time of npm start went from a startup time of more than 45 seconds on ntfs (/mnt/c/Users):

time npm start

npm start 0.06s user 0.01s system 0% cpu 47.299 total

Down to under 2 seconds on ext4 (/home):

npm start 0.13s user 0.01s system 6% cpu 1.437 total

🧠 Troubleshooting

Podman socket not active: check systemctl --user status podman.socket
Dev container build hangs: check registry config and Dev Containers log

README.devcontainer.md

🛠️ Dev Container Setup for med-plan-assistant (React App in WSL2 with Podman)