med-plan-assistant/docs

🛠️ 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 Ubuntu Linux and Docker. or optionally WSL2 and/or Podman. It assumes the following for the linux host (or optionally WSL):

• Ubuntu Linux is istalled and configured
• VSCode is installed with the Dev Containers extension on the host system
• The project repo is located in ~/git/med-plan-assistant

📦 1. Install Docker Service in Ubuntu

Using Docker.IO

sudo apt-get install -y docker.io
sudo usermod -a -G docker $(whoami)

Optional: Using Podman (over Docker.IO)

sudo apt update
sudo apt install -y podman

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

# Add current user to uucp group for Podman socket access
#sudo usermod -a -G uucp $(whoami)

Also see: Podman installation guide

⚙️ 2. Optional: Using WSL2

Additional steps when using WSL2 on Windows.

Enable systemd for WSL2 adding the following settings to /etc/wsl.conf:

[boot]
systemd=true

Then restart WSL:

wsl --shutdown
wsl

Optional: Using Podman (over Docker.IO)

Enable Podman socket:

# Enable linger to allow user services to run without active login
# Without this, the command below may return: Failed to connect to bus: No such file or directory
loginctl enable-linger $USER

systemctl --user enable --now podman.socket

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

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/podman.service <<EOF
[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
EOF

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

Also see Podman for Windows.

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

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

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

🧰 4. Create .devcontainer Setup

This is allready pre-configured in the repo, but in case you want to set it up manually, follow these steps as a starting point.

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

Open the project directory in VSCode (in Ubuntu/WSL2):

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

🪟 When Using WSL2

Filesystem Performance

Performance is significantly better on native WSL2 filesystem (ext4) vs NTFS (/mnt/c/...). If you previously worked on NTFS, move or clone the repo to WSL2 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

• Dev container build hangs: check registry config and Dev Containers log

When Using Podman

• Podman socket not active: check systemctl --user status podman.socket