# Pangolin — een publiek adres voor je apps

[Pangolin](https://github.com/fosrl/pangolin) is een reverse proxy met tunnel:
je apps blijven thuis draaien en krijgen toch een adres op internet, zónder dat
je poorten hoeft open te zetten in je router. Server Up kan die adressen voor je
aanmaken, zodat je dat niet per app in de Pangolin-interface hoeft te doen.

> **Server Up installeert Pangolin niet.** Je hebt een draaiende Pangolin-server
> nodig (in de cloud of op een VPS) en een Newt-site die vanaf je thuisnetwerk
> naar buiten verbindt. Server Up praat alleen met de API.

---

## Instellen

Onder **Instellingen → Pangolin**:

| Veld | Waar vind je dat |
|---|---|
| Adres | De URL van je Pangolin-server, bijvoorbeeld `https://pangolin.voorbeeld.nl` |
| API-sleutel | In Pangolin onder **Settings → API Keys**. Geef hem rechten om resources en targets te maken. |
| Organisatie-id | Staat in de URL als je in Pangolin bent ingelogd |
| Site | Wordt opgehaald zodra de sleutel werkt; dit is je Newt-verbinding |
| Domein | Wordt opgehaald zodra de sleutel werkt |

Klik daarna op **Verbinding testen**. Lukt het, dan staat er hoeveel sites er
gevonden zijn. De API-sleutel is write-only: je kunt hem instellen, maar de API
geeft hem nooit terug.

---

## Een URL aanmaken

Open **Inloggegevens** op de stackkaart en klik op **Publieke URL aanmaken**.
Server Up doet dan twee dingen:

1. een *resource* aanmaken — het publieke adres, standaard `<stacknaam>.<domein>`;
2. een *target* aanmaken — waar dat adres naartoe wijst.

Het doel wordt afgeleid: heeft de container een eigen IP-adres (macvlan), dan dat;
anders het adres van de host met de gepubliceerde poort. De URL wordt bij de
stack bewaard en daarna in het paneel getoond.

**Bij een stack met meerdere webinterfaces publiceer je per container.** De
ARR-stack heeft er twintig; die krijgen elk hun eigen adres
(`sonarr.<domein>`, `radarr.<domein>`, …) in plaats van dat de eerste poort in
het bestand de URL opslokt. Server Up haalt de juiste poort uit de gegevens die
bij het installeren zijn bewaard.

---

## Als het misgaat

**"De API-sleutel wordt geweigerd (401)"** — de sleutel is verlopen of heeft te
weinig rechten.

**"Organisatie niet gevonden (404)"** — het organisatie-id klopt niet. Het is de
korte naam uit de URL, niet de weergavenaam.

**"Geen site gevonden; installeer eerst Newt"** — Pangolin heeft een tunnel naar
je netwerk nodig. Zet Newt op je thuisserver en koppel die als site.

**"Aanmaken mislukt"** met twee HTTP-codes — de API van Pangolin is in versie
1.9 veranderd: een resource hing eerst onder een site
(`PUT /org/<org>/site/<site>/resource`) en staat sindsdien los
(`PUT /org/<org>/resource`). Server Up probeert allebei en toont beide
foutmeldingen, zodat je ziet welke route jouw versie verwacht. Zie
[fosrl/pangolin#1344](https://github.com/fosrl/pangolin/issues/1344).

---

## Wat er níét gebeurt

- Server Up beheert de URL niet verder: verwijder je de stack, dan blijft de
  resource in Pangolin staan. Ruim die daar zelf op.
- Er wordt geen authenticatie voor de resource ingesteld. Wil je dat het adres
  niet voor de hele wereld open staat, zet dan in Pangolin zelf een
  toegangsregel of SSO op die resource.
- Meerdere targets per resource (load balancing) valt hierbuiten.

> **Deze integratie is getest tegen een nagebouwde API, niet tegen een echte
> Pangolin-server.** Dat de juiste verzoeken verstuurd worden ligt vast in de
> tests; of jouw versie ze accepteert, blijkt bij de eerste poging. De
> foutmeldingen zijn daarom zo volledig mogelijk gehouden.