# Kata Containers Setup

OpenGit can run shell containers with **Kata Containers** for stronger isolation. Each Kata container runs in a lightweight VM, providing hardware-enforced isolation instead of shared-kernel containers.

---

## Quick Install

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

```bash
sudo scripts/install_kata.sh
```

The script supports **Arch Linux**, **Debian/Ubuntu**, and **Fedora**. It installs Docker, containerd, Kata, CNI plugins, and configures networking.

---

## Manual Setup

### Prerequisites

- **Architecture:** x86_64 (Kata does not support ARM on many configurations)
- **Hardware virtualization:** VT-x (Intel) or AMD-V must be enabled in BIOS
- **KVM:** `/dev/kvm` must exist and be accessible

### 1. Install Docker and containerd

**Arch Linux:**
```bash
sudo pacman -S --needed docker containerd qemu-common cni-plugins
```

**Debian/Ubuntu:**
```bash
# Add Docker repository, then:
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
```

**Fedora:**
```bash
sudo dnf install -y docker containerd
```

### 2. Enable IP forwarding

```bash
echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-kata-forwarding.conf
sudo sysctl --system
```

### 3. Load kernel modules

```bash
sudo modprobe vhost_net
sudo modprobe vhost_vsock
echo -e "vhost_net\nvhost_vsock" | sudo tee /etc/modules-load.d/kata.conf
```

### 4. Install Kata Containers

Download the latest static tarball from [Kata Containers releases](https://github.com/kata-containers/kata-containers/releases):

```bash
KATA_VERSION=$(curl -sL https://api.github.com/repos/kata-containers/kata-containers/releases/latest | jq -r '.tag_name')
wget "https://github.com/kata-containers/kata-containers/releases/download/${KATA_VERSION}/kata-static-${KATA_VERSION}-amd64.tar.zst"
sudo tar -xf "kata-static-${KATA_VERSION}-amd64.tar.zst" -C /
sudo ln -sf /opt/kata/bin/kata-runtime /usr/local/bin/kata-runtime
sudo ln -sf /opt/kata/bin/containerd-shim-kata-v2 /usr/local/bin/containerd-shim-kata-v2
```

### 5. Symlink QEMU ROMs

Kata expects ROM files (e.g. from `qemu-common` or `qemu-system-common`):

```bash
# Locate system QEMU dir (e.g. /usr/share/qemu)
sudo mkdir -p /opt/kata/share/qemu
sudo ln -sf /usr/share/qemu/* /opt/kata/share/qemu/
```

### 6. Configure Docker daemon

Edit `/etc/docker/daemon.json`:

```json
{
  "default-runtime": "kata",
  "runtimes": {
    "kata": {
      "runtimeType": "io.containerd.kata.v2",
      "runtimePath": "/opt/kata/bin/containerd-shim-kata-v2"
    }
  }
}
```

### 7. Configure containerd

Edit `/etc/containerd/config.toml`:

```toml
version = 2

[plugins."io.containerd.grpc.v1.cri".cni]
  bin_dir = "/opt/cni/bin"
  conf_dir = "/etc/cni/net.d"

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata]
  runtime_type = "io.containerd.kata.v2"

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata.options]
  BinaryName = "/opt/kata/bin/containerd-shim-kata-v2"
```

### 8. Configure CNI (if needed)

Create `/etc/cni/net.d/10-kata.conf` for bridge networking:

```json
{
  "cniVersion": "0.4.0",
  "name": "kata",
  "type": "bridge",
  "bridge": "kata0",
  "isGateway": true,
  "ipMasq": true,
  "ipam": {
    "type": "host-local",
    "subnet": "192.168.100.0/24",
    "routes": [{"dst": "0.0.0.0/0"}]
  }
}
```

### 9. Add user to docker group

```bash
sudo usermod -aG docker $USER
```

### 10. Restart services and reboot

```bash
sudo systemctl restart containerd
sudo systemctl restart docker
# Reboot recommended for kernel modules and networking
sudo reboot
```

### Verification

```bash
docker run --rm --runtime=kata busybox echo "Kata VM booted successfully"
```

---

## OpenGit Integration

In OpenGit's first-time setup or admin, choose **Kata** as the shell system for VM-isolated containers. Kata containers run through Docker and provide stronger isolation than standard Podman containers.

### Private repository clone in shells

When a user enables **Clone repository** on shell creation, **Git over HTTP** must be enabled. **Public** repos clone without credentials. **Private** repos receive a **short-lived HMAC-signed token** (bound to that user, repo owner, and repo name; default TTL 30 minutes). Git HTTP accepts it as HTTP Basic user `opengit-shell` with the token as the password (embedded in the clone URL inside the container). **Push is rejected** for this credential. Only the **owner** or a **repository contributor** can obtain a token (same rules as normal Git read access).
