# Newt (Pangolin Tunnel Agent) Playbook

## Overview

`newt.yml` deploys [Newt](https://github.com/fosrl/newt), the tunnel agent for the Pangolin reverse proxy platform. Newt establishes an outbound tunnel from a Docker host back to your Pangolin server, allowing Pangolin to route traffic to services on that host without opening inbound ports.

## Architecture

```
┌─────────────────────────┐         ┌──────────────────────────┐
│  Target Docker Host     │         │  Pangolin Server         │
│                         │         │  pangolin.wulfconsulting  │
│  ┌───────────────────┐  │ tunnel  │  .cloud                  │
│  │ newt container     │──────────▶│                          │
│  │ (fosrl/newt)       │  │        │  Routes traffic to sites │
│  └───────────────────┘  │        │  configured in dashboard  │
│                         │         └──────────────────────────┘
│  /opt/stacks/newt/      │
│  └── compose.yaml       │
└─────────────────────────┘
```

### Playbook structure

| Section | Purpose |
|---------|---------|
| **vars** | Sets `newt_stack_dir` (`/opt/stacks/newt`) and the default `pangolin_endpoint` |
| **pre_tasks** | Validates that `newt_id`, `newt_secret`, and `pangolin_endpoint` are provided; checks Docker is running |
| **tasks** | Creates the stack directory, writes `compose.yaml`, and deploys via `docker_compose_v2` |

The compose file defines a single service — the `fosrl/newt` image configured with three environment variables that authenticate it to the Pangolin server.

## Usage

### Required extra vars

| Variable | Source | Description |
|----------|--------|-------------|
| `newt_id` | Pangolin dashboard (per-site) | Tunnel identity |
| `newt_secret` | Pangolin dashboard (per-site) | Tunnel secret |

### Optional extra vars

| Variable | Default | Description |
|----------|---------|-------------|
| `pangolin_endpoint` | `https://pangolin.wulfconsulting.cloud` | Pangolin server URL |

### Deploy to a host

```bash
ansible-playbook playbooks/newt.yml --limit kaercher02 \
  -e newt_id=kigig6jtds5qr3a \
  -e newt_secret=9qznq1wasaapy0cwpxzzi8sji6z5r4nkukqpkt4k8lyy6jx3
```

### Override the Pangolin endpoint

```bash
ansible-playbook playbooks/newt.yml --limit somehost \
  -e newt_id=... \
  -e newt_secret=... \
  -e pangolin_endpoint=https://pangolin.other.domain
```

### Verify the container is running

```bash
ansible kaercher02 -a "docker ps --filter name=newt"
```

## Notes

- **Credentials are runtime-only.** `newt_id` and `newt_secret` are passed as extra vars and written into the compose file on the target host. They are not stored in the Ansible repo.
- **One Newt per host.** The container name is fixed to `newt`, so each host runs a single instance. If you need multiple tunnels on one host, duplicate the playbook with a different container name and stack directory.
- **`--limit` is required.** The playbook targets `all` hosts, so always use `--limit` to select which host to deploy to.