# Pangolin

## Overview

Pangolin is a self-hosted tunneled reverse proxy with identity-aware access control. It exposes services running behind NAT or on a private LAN to the internet without port-forwarding, using its own WireGuard tunnel (`gerbil`) and a bundled Traefik instance for TLS termination and routing.

Unlike most stacks in this repo, Pangolin **is itself the edge reverse proxy** — it does not sit behind Nginx Proxy Manager. It needs its own public IP and listens directly on ports 80/443/51820.

## Project Details

* Project Repository: https://github.com/fosrl/pangolin
* Container Image: https://hub.docker.com/r/fosrl/pangolin
* Compose Example: https://github.com/fosrl/pangolin/blob/main/docker-compose.example.yml
* Documentation: https://docs.fossorial.io/
* Reverse Proxy Domain: pangolin.example.com
* Internal Service Port: 3000 (API), 3001 (internal API), 3002 (dashboard/next)

## Getting Started

1. Copy the starter config into place and edit it:
   ```bash
   mkdir -p /data/pangolin/config /data/pangolin/traefik /data/pangolin/letsencrypt /data/pangolin/gerbil
   cp config/config.yml /data/pangolin/config/config.yml
   cp config/traefik/traefik_config.yml config/traefik/dynamic_config.yml /data/pangolin/traefik/
   nano /data/pangolin/config/config.yml   # set dashboard_url, base_domain, secret, admin email/password
   nano /data/pangolin/traefik/*.yml       # replace pangolin.example.com with your real domain
   ```
2. Copy env defaults: `cp sample.env .env`
3. Start the stack: `docker compose up -d`
4. Open `https://pangolin.example.com` and log in with the admin user set in `config.yml`
5. Follow the in-app wizard to create a site (installs a `newt` client on the machine you want to expose) and add resources

## Environment Variable Notes

```
PANGOLIN_IMAGE – Docker image for the Pangolin server (default: fosrl/pangolin:latest)
PANGOLIN_RESTART – Restart policy

GERBIL_IMAGE – Docker image for the gerbil WireGuard gateway (default: fosrl/gerbil:latest)
GERBIL_RESTART – Restart policy
GERBIL_WG_PORT – UDP port for the WireGuard tunnel (default: 51820)
GERBIL_HTTP_PORT – Public HTTP port, proxied through gerbil to traefik (default: 80)
GERBIL_HTTPS_PORT – Public HTTPS port, proxied through gerbil to traefik (default: 443)

TRAEFIK_IMAGE – Docker image for Traefik (default: traefik:v3.3)
TRAEFIK_RESTART – Restart policy

VOL_PATH – Base path for config/data volumes (default: /data)
TZ – Timezone (default: America/Vancouver)
```

## Volume Notes

```
${VOL_PATH}/pangolin/config       – config.yml (required, see config/config.yml starter)
${VOL_PATH}/pangolin/gerbil       – gerbil's generated WireGuard key/state
${VOL_PATH}/pangolin/traefik      – traefik_config.yml and dynamic_config.yml (required, see config/traefik/)
${VOL_PATH}/pangolin/letsencrypt  – ACME certificate storage (acme.json)
```

## Network Notes

* **Does not sit behind NPM like other stacks in this repo** — Pangolin is its own edge reverse proxy. The `proxy` network is declared for convention but none of its services actually join it (see AGENTS.md "Known exceptions").
* `traefik` runs with `network_mode: service:gerbil`, sharing gerbil's network namespace so it can bind the ports gerbil forwards from the WireGuard tunnel.
* Only `gerbil` publishes ports to the host: `51820/udp` (WireGuard), `80/tcp`, `443/tcp`.
* Requires a public IP with 80/443/51820 open inbound (or forwarded, if behind NAT). This is a different deployment model than the LAN-only, NPM-fronted stacks elsewhere in this repo.

## Docker Run

```bash
docker run -d \
  --name=pangolin \
  -v /data/pangolin/config:/app/config \
  fosrl/pangolin:latest
```

See compose.yaml for the full multi-container setup (`pangolin` + `gerbil` + `traefik`) — Pangolin does not function correctly as a single container.

## Additional Notes / Gotchas

* All three services (`pangolin`, `gerbil`, `traefik`) must run together; gerbil needs `NET_ADMIN` and `SYS_MODULE` capabilities for WireGuard.
* `dashboard_url`, `base_domain`, and the `pangolin.example.com` references in the Traefik dynamic config must all be updated to match your real domain before first start.
* Change `secret` and the admin `password` in `config.yml` before exposing this publicly — the repo default of `ChangeThisPassword` is not safe to leave in place, since this stack is internet-facing by design.
* After a site is registered in the dashboard, exposed services are reached by installing the lightweight `newt` client on the target host — see the Pangolin docs for `newt` setup.
* Certificates are issued automatically via Traefik's ACME HTTP challenge on port 80; keep port 80 open even if you only care about HTTPS.

## Dockhand Stack, Deploy from Git

Cookbooks Repository
stackname: pangolin_dev
Compose file path: pangolin_dev/compose.yaml
Additional env file (optional): pangolin_dev/sample.env

Then "Load" pangolin_dev/sample.env into the Environmental variables in dockhand.

Ensure `config.yml`, `traefik_config.yml`, and `dynamic_config.yml` exist under `${VOL_PATH}/pangolin/` before deploying.

Create the Stack.