med-plan-assistant/docs/README.devcontainer.md

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

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