# Podman Setup

OpenGit can run shell containers with **Podman** in rootless mode. Optionally, Podman can use **gVisor (runsc)** for syscall filtering and extra isolation.

---

## Quick Install

For automated setup, use the install script in the `scripts` folder:

```bash
sudo scripts/install_podman.sh
```

The script supports **Arch Linux**, **Debian/Ubuntu**, and **Fedora**. It installs Podman, configures rootless mode with user socket activation, optionally installs gVisor (runsc), and sets up `containers.conf`. To skip gVisor installation: `INSTALL_GVISOR=0 sudo scripts/install_podman.sh`

---

## Manual Setup

### 1. Install Podman

**Arch Linux:**
```bash
sudo pacman -S --needed podman
```

**Debian/Ubuntu:**
```bash
sudo apt-get update
sudo apt-get install -y podman
```

**Fedora:**
```bash
sudo dnf install -y podman
```

### 2. Rootless prerequisites

Ensure user namespaces are enabled:

```bash
# Usually 1 on modern kernels
cat /proc/sys/kernel/unprivileged_userns_clone
```

Configure subuid/subgid for your user (replace `username`):

```bash
# /etc/subuid
username:100000:65536

# /etc/subgid
username:100000:65536
```

Use `usermod` if your distro supports it:

```bash
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER
```

Enable logind lingering so the user's Podman socket stays active when logged out:

```bash
sudo loginctl enable-linger $USER
```

### 3. Start the Podman socket

OpenGit connects to Podman via the rootless socket at `/run/user/<uid>/podman/podman.sock`. Start it with:

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

Verify:

```bash
podman info
ls -la /run/user/$(id -u)/podman/podman.sock
```

### 4. Optional: gVisor (runsc) for syscall isolation

gVisor provides an additional kernel isolation layer. Install the `runsc` binary:

**Arch Linux (AUR):**
```bash
yay -S gvisor-bin
# or: paru -S gvisor-bin
```

**Debian/Ubuntu:**
```bash
curl -fsSL https://gvisor.dev/archive.key | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main' | sudo tee /etc/apt/sources.list.d/gvisor.list
sudo apt-get update && sudo apt-get install -y runsc
```

**Fedora / generic Linux:**
```bash
curl -fsSL "https://storage.googleapis.com/gvisor/releases/release/latest/$(uname -m)/runsc" -o /tmp/runsc
sudo install -m 755 /tmp/runsc /usr/local/bin/runsc
```

### 5. Configure containers.conf

Create or edit `~/.config/containers/containers.conf`:

```ini
[containers]
runtime = "runsc"

[network]
network_backend = "netavark"
```

Omit `runtime = "runsc"` if you are not using gVisor. `network_backend = "netavark"` is recommended for compatibility.

### 6. Verify

```bash
# Without gVisor
podman run --rm alpine:latest echo "Podman OK"

# With gVisor
podman run --rm --runtime=runsc alpine:latest echo "gVisor OK"
```

---

## OpenGit Integration

OpenGit expects the Podman socket at:

```
/run/user/<uid>/podman/podman.sock
```

The OpenGit process (e.g. gunicorn) runs as a user that has access to this socket. When Podman is selected as the shell system (in first-time setup or admin), containers are created via the Podman API.

- **Podman:** Standard containers (rootless, less isolation than Kata)
- **Kata:** VM-isolated containers via Docker (stronger isolation)

See [kata.md](kata.md) for Kata setup.
