# Fossorial Tunnel Stack (Pangolin + Gerbil)

**Status:** 💡 IDEA
**Priority:** Low
**Depends On:** Hardware upgrade (XTRM-N1 for resilience)

---

## Overview

Self-hosted tunnel solution for exposing services without Cloudflare/VPS dependency.

| Component | Purpose |
|-----------|---------|
| **Pangolin** | Central controller/dashboard |
| **Gerbil** | WireGuard peer manager |
| **Newt** | Tunnel connector agent |

---

## Why Fossorial?

Current state uses Traefik + Cloudflare DNS for external access.

Fossorial would provide:
- Independent tunneling (no Cloudflare dependency)
- Self-healing WireGuard connections
- Web-based tunnel management
- Potential for MikroTik container fallback

---

## Architecture

```
Internet (62.73.120.142)
         │
         ▼ UDP 51820
┌─────────────────────┐
│ Gerbil (WG Manager) │
│ :51820 WireGuard    │
│ :8080 API           │
└─────────┬───────────┘
          │
┌─────────▼───────────┐
│ Pangolin (Dashboard)│
│ :3000 Web UI        │
└─────────┬───────────┘
          │
┌─────────▼───────────┐
│ Newt (Connector)    │
│ Dials out to peers  │
└─────────────────────┘
```

---

## Prerequisites

- [ ] Port 51820/UDP forwarded on MikroTik
- [ ] `fossorial` Docker network created
- [ ] Secret key generated

---

## Deployment Steps

### 1. Create Network
```bash
docker network create --driver bridge fossorial
```

### 2. Deploy Pangolin
```bash
docker run -d \
  --name pangolin \
  --network fossorial \
  -p 3000:3000 \
  -v /mnt/user/appdata/pangolin/data:/app/data \
  -e PANGOLIN_BASE_URL=https://pangolin.xtrm-lab.org \
  -e PANGOLIN_SECRET_KEY=$(openssl rand -hex 32) \
  fossoriumtech/pangolin:latest
```

### 3. Deploy Gerbil
```bash
docker run -d \
  --name gerbil \
  --network fossorial \
  --cap-add=NET_ADMIN \
  -p 51820:51820/udp \
  -p 8080:8080 \
  -v /mnt/user/appdata/gerbil:/app/data \
  -e GERBIL_PUBLIC_IP=62.73.120.142 \
  -e GERBIL_PUBLIC_PORT=51820 \
  fossoriumtech/gerbil:latest
```

### 4. Deploy Newt
```bash
docker run -d \
  --name newt \
  --network fossorial \
  -v /mnt/user/appdata/newt:/app/data \
  -e NEWT_PANGOLIN_URL=https://pangolin.xtrm-lab.org \
  -e NEWT_ENDPOINT=62.73.120.142:51820 \
  fossoriumtech/newt:latest
```

### 5. MikroTik NAT
```routeros
/ip/firewall/nat add chain=dstnat \
    action=dst-nat to-addresses=192.168.31.2 to-ports=51820 \
    protocol=udp dst-port=51820 \
    comment="Fossorial WireGuard"
```

---

## Current WireGuard (Not Affected)

Existing back-to-home-vpn uses port **59188**, completely separate.

---

## Decision Points

1. **Is this needed?** Tailscale + Traefik already provides external access
2. **When to implement?** After XTRM-N1 survival node for fallback option
3. **Use case?** If Cloudflare/Tailscale goes down

---

## References

- Original planning: `archive/02-PHASE2-FOSSORIAL-STACK.md`
- GitHub: https://github.com/fossoriumtech