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 **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

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

### Optional: Using Podman (over Docker.IO)

```bash
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](https://podman.io/getting-started/installation)_

## ⚙️ 2. Optional: Using WSL2

Additional steps when using WSL2 on Windows.

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

```ini
[boot]
systemd=true
```

Then restart WSL:

```bash
wsl --shutdown
wsl
```

### Optional: Using Podman (over Docker.IO)

Enable Podman socket:

```bash
# 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:

```bash
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:

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

Verify:

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

_Also see [Podman for Windows](https://github.com/containers/podman/blob/main/docs/tutorials/podman-for-windows.md)._


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

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

```ini
[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:

```bash
mkdir .devcontainer
```

Create `.devcontainer/devcontainer.json` and paste:

```json
{
  "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:

```dockerfile
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):

```bash
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:

```bash
npm start
```

Access the app at [http://localhost:3000](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:

```bash
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:

```bash
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`):

```bash
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`