pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-09-08 23:21:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

update common api routes, reduce newt references, and improve how to update

Browse Source
This commit is contained in:
miloschwartz
2026-09-08 16:43:09 -04:00
parent 40feb4d220
commit 3590064dfc
11 changed files with 75 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
development/system-architecture.mdx
View File

@@ -64,14 +64,14 @@ The control plane writes certificates, Traefik router definitions, and WireGuard
A **site connector** runs on a remote network (server, VM, container, or appliance) and is the bridge between your private LAN and the platform. For public resources it maintains persistent **outbound** connections to a Pangolin node so ingress can reverse-proxy into the LAN. For private resources, clients form a **peer-to-peer** path to the connector; the node is only in that data path as a relay when hole punching fails.
The primary connector implementation is **Newt** (codename). Newt opens:
The primary connector is a **Pangolin Site**. In engineering contexts it is referred to as Newt. The site opens:
1. A **WebSocket** to the control plane for configuration, health, and coordination
2. A **WireGuard** tunnel to the node's tunnel manager (Gerbil) for encrypted data traffic
Site connectors are deny-by-default proxies. Deploying one does not expose hosts on the network; traffic is forwarded only for [resources](/manage/resources/understanding-resources) you define and grant access to. The connector resolves backend targets on the remote network and delivers packets there.
Newt sites support the full feature set: public and private resources, protocol-aware proxies, multi-site routing, health checks, and edge TLS for private HTTP. Other connector types ([local](/manage/sites/understanding-sites#local-site) and [basic WireGuard](/manage/sites/understanding-sites#basic-wireguard-site)) exist for specialized self-hosted cases.
Pangolin Sites support the full feature set: public and private resources, protocol-aware proxies, multi-site routing, health checks, and edge TLS for private HTTP. Other connector types ([local](/manage/sites/understanding-sites#local-site) and [basic WireGuard](/manage/sites/understanding-sites#basic-wireguard-site)) exist for specialized self-hosted cases.
<Card title="Understanding sites" icon="plug" href="/manage/sites/understanding-sites">
Site types, deployment models, and connector capabilities.

10
docs.json
View File

@@ -370,15 +370,15 @@
],
"global": {
"anchors": [
{
"anchor": "Slack",
"href": "https://pangolin.net/slack",
"icon": "slack"
},
{
"anchor": "Discord",
"href": "https://pangolin.net/discord",
"icon": "discord"
},
{
"anchor": "Slack",
"href": "https://pangolin.net/slack",
"icon": "slack"
}
]
}

2
manage/ai/providers/custom.mdx
View File

@@ -21,7 +21,7 @@ See [AI Providers](/manage/ai/providers/overview) if you haven't created a provi
## Reach a Self-Hosted API
Site Targets send the request over a Pangolin tunnel to a host Newt can reach. [Install a site](/manage/sites/install-site) on the same network as the model server so the gateway can route to that API over the tunnel. See [Understanding Sites](/manage/sites/understanding-sites).
Site Targets send the request over a Pangolin tunnel to a host the site can reach. [Install a site](/manage/sites/install-site) on the same network as the model server so the gateway can route to that API over the tunnel. See [Understanding Sites](/manage/sites/understanding-sites).
After the site is connected, add the process as a target on the provider's **Network** tab (host, port, HTTP or HTTPS). Worked examples: [Ollama](/manage/ai/providers/custom/ollama), [vLLM](/manage/ai/providers/custom/vllm), and [Bifrost](/manage/ai/providers/custom/bifrost).

2
manage/ai/providers/custom/cloud-apis-through-a-site.mdx
View File

@@ -3,7 +3,7 @@ title: "Cloud APIs Through a Site"
description: "Send OpenAI or Anthropic traffic out through a Pangolin site so the vendor sees a fixed egress IP"
---
Typed [OpenAI](/manage/ai/providers/openai) and [Anthropic](/manage/ai/providers/anthropic) providers send requests from the Pangolin node's own egress. A [Custom](/manage/ai/providers/custom) provider with **Site Targets** sends the same APIs out through a chosen site (Newt), so OpenAI or Anthropic see that site's public IP.
Typed [OpenAI](/manage/ai/providers/openai) and [Anthropic](/manage/ai/providers/anthropic) providers send requests from the Pangolin node's own egress. A [Custom](/manage/ai/providers/custom) provider with **Site Targets** sends the same APIs out through a chosen site, so OpenAI or Anthropic see that site's public IP.
Use this when the vendor allowlists IPs, or all inference must leave from one network. The site is only the egress path. Auth still lives on the provider: paste the real vendor key.

20
manage/blueprints.mdx
View File

@@ -54,7 +54,7 @@ Pangolin supports two blueprint formats:
### YAML
Use YAML when you want a readable file that can be committed to git, applied through Newt, pasted into the UI, or sent through the API.
Use YAML when you want a readable file that can be committed to git, applied through a site, pasted into the UI, or sent through the API.
### Container Labels
@@ -70,8 +70,8 @@ Use container labels when the resource definition should live inside your Compos
</Frame>
</Card>
<Card title="Newt">
Run Newt with `--blueprint-file` to keep the file declarative and continuously applied:
<Card title="Site">
Run a site with `--blueprint-file` to keep the file declarative and continuously applied:
```bash
newt --blueprint-file /path/to/blueprint.yaml <other-args>
@@ -140,7 +140,7 @@ Use container labels when the resource definition should live inside your Compos
</Card>
<Note>
`--blueprint-file` in Newt and container labels behave as an ongoing source of truth. Dashboard edits can be overwritten the next time the blueprint is applied. UI, API, and CLI applies are typically one-off operations.
`--blueprint-file` on a site and container labels behave as an ongoing source of truth. Dashboard edits can be overwritten the next time the blueprint is applied. UI, API, and CLI applies are typically one-off operations.
</Note>
## Quick Start YAML Example
@@ -229,7 +229,7 @@ public-resources:
```
<Note>
When applying a blueprint via Newt (using `--blueprint-file` or container labels), `site` on each target is optional. If omitted, the target is assigned to the site of the Newt that applied the blueprint.
When applying a blueprint from a site (using `--blueprint-file` or container labels), `site` on each target is optional. If omitted, the target is assigned to the site that applied the blueprint.
</Note>
### Raw TCP Or UDP Example
@@ -364,7 +364,7 @@ Private resources define what Pangolin clients can reach after they connect to y
- Use **`mode: inference`** for a private [AI Gateway](/manage/ai/overview) resource reachable only by Pangolin clients, not the public internet
<Note>
When applying a blueprint via Newt (using `--blueprint-file` or container labels), `sites` is optional. If omitted, the resource is assigned to the site of the Newt that applied the blueprint.
When applying a blueprint from a site (using `--blueprint-file` or container labels), `sites` is optional. If omitted, the resource is assigned to the site that applied the blueprint.
</Note>
```yaml
@@ -457,7 +457,7 @@ Container labels are continuously applied. Treat the Compose file as the source
### Enable Container Label Discovery
To use container labels, Newt must be able to read the Docker socket:
To use container labels, the site must be able to read the Docker socket:
```bash
newt --docker-socket /var/run/docker.sock <other-args>
@@ -524,7 +524,7 @@ This creates a single Pangolin resource with multiple targets:
</Card>
<Card title="Site Assignment">
If no `site` is specified on a target (public resource) or on a private resource, it is assigned to the site of the Newt that applied the blueprint — whether through container labels or `--blueprint-file`.
If no `site` is specified on a target (public resource) or on a private resource, it is assigned to the site that applied the blueprint, whether through container labels or `--blueprint-file`.
</Card>
<Card title="Merged Configuration">
@@ -1146,7 +1146,7 @@ public-resources:
<Expandable title="Target object">
<ResponseField name="site" type="string">
Site that hosts the target. Optional when deploying from a Newt — if omitted, the target is assigned to the site of the Newt that applied the blueprint.
Site that hosts the target. Optional when deploying from a site. If omitted, the target is assigned to the site that applied the blueprint.
YAML: `site: my-site`
Container label: `pangolin.public-resources.web-app.targets[0].site=my-site`
@@ -1380,7 +1380,7 @@ private-resources:
</ResponseField>
<ResponseField name="sites" type="array of strings">
Sites that host the resource. Optional when deploying from a Newt — if omitted, the resource is assigned to the site of the Newt that applied the blueprint.
Sites that host the resource. Optional when deploying from a site. If omitted, the resource is assigned to the site that applied the blueprint.
Container labels for arrays must include an index (`[0]`, `[1]`, ...).

6
manage/clients/nat-traversal.mdx
View File

@@ -10,7 +10,7 @@ When a client and site share the same local network, they detect this and connec
Same-network connections typically offer the lowest latency because traffic never leaves the LAN.
Newt collects IP addresses from the host's network interfaces and uses them to send UDP test packets to the client. If Newt runs inside a Docker container, it only sees the container's internal network, so run it on the host itself to ensure it can detect the host's real IP addresses. This detection also works across VLANs—if a client and site are on different VLANs but routing between them is configured correctly, the connection should still succeed.
The site collects IP addresses from the host's network interfaces and uses them to send UDP test packets to the client. If the site runs inside a Docker container, it only sees the container's internal network, so run it on the host itself to ensure it can detect the host's real IP addresses. This detection also works across VLANs. If a client and site are on different VLANs but routing between them is configured correctly, the connection should still succeed.
## NAT Hole Punching
@@ -27,7 +27,7 @@ Direct connections typically offer:
If the site and client are unable to hole punch, they fall back to relaying through your Pangolin server.
Clients can relay traffic through a Pangolin server—through Gerbil specifically. Gerbil listens on UDP port 21820 for new WireGuard connections and forwards the packets down the Newt site tunnels to the right peers. This means your connections back to your site do not require firewall config and uses the existing NAT hole punching capabilities of Newt.
Clients can relay traffic through a Pangolin server, through the Gerbil service specifically. Gerbil listens on UDP port 21820 for new WireGuard connections and forwards the packets down the site tunnels to the right peers. This means your connections back to your site do not require firewall config and uses the existing NAT hole punching capabilities of the site.
Relaying is reliable when direct paths are blocked by NAT or firewall rules, but traffic passes through your Pangolin node instead of traveling directly between the client and site.
@@ -99,7 +99,7 @@ Use either view when troubleshooting hole punching or verifying that configurati
## Improve Hole Punching Reliability
Newt supports NAT traversal to allow clients to connect directly to Newt sites without relaying through the Pangolin server, improving performance and reducing latency.
Pangolin Sites support NAT traversal so clients can connect directly without relaying through the Pangolin server, improving performance and reducing latency.
In some environments, depending on the NAT type and firewall, you may need to tweak settings to get optimal connectivity in the firewall itself. See [Firewall Integrations](/manage/clients/firewalls) for Pangolin-specific guidance for common platforms.

30
manage/common-api-routes.mdx
View File

@@ -121,7 +121,7 @@ Returns values you pass into the create-site endpoint.
## Create public HTTP resource
You need a **domain ID** before creating a resource. List your org's domains, then create the resource with the chosen domain. For all Resource endpoints, see [Resource API (Swagger)](https://api.pangolin.net/v1/docs/#/Resource).
You need a **domain ID** before creating a resource. List your org's domains, then create the resource with the chosen domain. For all public resource endpoints, see [Public Resource API (Swagger)](https://api.pangolin.net/v1/docs/#/Public%20Resource).
<Steps>
<Step title="List domains">
@@ -183,7 +183,7 @@ Returns all domains for the organization. Use `domainId` from a domain when crea
### Create public HTTP resource
**PUT** `/org/{orgId}/resource`
**PUT** `/org/{orgId}/public-resource`
**Path**
- `orgId` (string) — organization ID
@@ -242,9 +242,9 @@ The `subdomain` value is combined with the base domain from `domainId` to form t
### Add targets to the resource
**PUT** `/resource/{resourceId}/target`
**PUT** `/public-resource/{resourceId}/target`
Add a target (backend) to a resource. Use the numeric `resourceId` from the create-resource response. The target is the site and address (ip + port) that will receive traffic for the resource. For all Target endpoints, see [Target API (Swagger)](https://api.pangolin.net/v1/docs/#/Target).
Add a target (backend) to a resource. Use the numeric `resourceId` from the create-resource response. The target is the site and address (ip + port) that will receive traffic for the resource. For all target endpoints, see [Resource Target API (Swagger)](https://api.pangolin.net/v1/docs/#/Resource%20Target).
**Path**
- `resourceId` (number) — From create-resource response (e.g. `9943`)
@@ -287,11 +287,11 @@ Add a target (backend) to a resource. Use the numeric `resourceId` from the crea
## Create private resource
In the API Private Resources are called **site resources**. You need an existing site. For more endpoints, see [API docs (Swagger)](https://api.pangolin.net/v1/docs/#/Resource).
You need an existing site. For more endpoints, see [Private Resource API (Swagger)](https://api.pangolin.net/v1/docs/#/Private%20Resource).
### Create site resource
### Create private resource
**PUT** `/org/{orgId}/site-resource`
**PUT** `/org/{orgId}/private-resource`
**Path**
- `orgId` (string) — organization ID
@@ -364,7 +364,7 @@ If you omit `roleIds`/`userIds`, the org admin role is granted access by default
## Assign users and roles to a resource (public or private)
You can grant access to a **public resource** or a **private (site) resource** by adding roles or users. First list roles and users in the org to get IDs, then call the add endpoints. The Admin role cannot be assigned via these endpoints.
You can grant access to a **public resource** or a **private resource** by adding roles or users. First list roles and users in the org to get IDs, then call the add endpoints. The Admin role cannot be assigned via these endpoints.
### Get role and user IDs
@@ -372,18 +372,18 @@ You can grant access to a **public resource** or a **private (site) resource** b
**GET** `/org/{orgId}/users` — Returns users in the org. Use `id` (string) as `userId` when adding a user to a resource. Query: `limit`, `offset` (optional).
### Public resource (HTTP/resources)
### Public resource
**POST** `/resource/{resourceId}/roles/add` — **Path:** `resourceId` (number, from create-resource). **Body:** `{ "roleId": number }`. Admin role not allowed.
**POST** `/public-resource/{resourceId}/roles/add` — **Path:** `resourceId` (number, from create public-resource). **Body:** `{ "roleId": number }`. Admin role not allowed.
**POST** `/resource/{resourceId}/users/add` — **Path:** `resourceId` (number). **Body:** `{ "userId": string }`.
**POST** `/public-resource/{resourceId}/users/add` — **Path:** `resourceId` (number). **Body:** `{ "userId": string }`.
Both return `{ "data": {}, "success": true, "error": false, "message": "...", "status": 201 }`.
### Private resource (site resource)
### Private resource
**POST** `/site-resource/{siteResourceId}/roles/add` — **Path:** `siteResourceId` (number, from create site-resource). **Body:** `{ "roleId": number }`. Admin role not allowed.
**POST** `/private-resource/{siteResourceId}/roles/add` — **Path:** `siteResourceId` (number, from create private-resource). **Body:** `{ "roleId": number }`. Admin role not allowed.
**POST** `/site-resource/{siteResourceId}/users/add` — **Path:** `siteResourceId` (number). **Body:** `{ "userId": string }`.
**POST** `/private-resource/{siteResourceId}/users/add` — **Path:** `siteResourceId` (number). **Body:** `{ "userId": string }`.
Same response shape as above. Role must belong to the same org as the site resource. For more endpoints (list/remove), see [Resource API](https://api.pangolin.net/v1/docs/#/Resource).
Same response shape as above. Role must belong to the same org as the private resource. For more endpoints (list/remove), see [Public Resource API](https://api.pangolin.net/v1/docs/#/Public%20Resource) and [Private Resource API](https://api.pangolin.net/v1/docs/#/Private%20Resource).

4
manage/remote-node/backhaul.mdx
View File

@@ -6,7 +6,7 @@ description: "Turn a remote node into a network concentrator that routes traffic
Site to cloud is an advanced [remote node](/manage/remote-node/understanding-nodes) configuration available in [Pangolin Cloud](https://app.pangolin.net/auth/signup).
</Note>
A standard remote node terminates WireGuard tunnels and proxies HTTP(S) traffic to your resources. A **backhaul** node goes a step further: it acts as an IP router between an entire network, such as a cloud VPC, and your Pangolin sites. Instead of just forwarding individual resource connections, the node forwards whole subnets, letting hosts on either side reach each other without installing Newt on every machine.
A standard remote node terminates WireGuard tunnels and proxies HTTP(S) traffic to your resources. A **backhaul** node goes a step further: it acts as an IP router between an entire network, such as a cloud VPC, and your Pangolin sites. Instead of just forwarding individual resource connections, the node forwards whole subnets, letting hosts on either side reach each other without installing a site on every machine.
This is useful when you want to bridge a cloud network (for example, an AWS VPC) with your on-prem or office network through Pangolin, using a node running in that VPC as the concentrator.
@@ -19,7 +19,7 @@ This is useful when you want to bridge a cloud network (for example, an AWS VPC)
- **The node routes, it doesn't just proxy.** Gerbil creates the WireGuard interface directly on the host and Docker forwards packets between it and the host's network, rather than isolating traffic inside a container network namespace.
- **The cloud network learns to route to the node.** You add a route in your VPC (or other network) so that traffic destined for the Pangolin overlay is sent to the node.
- **The node learns to route to the cloud network.** You register the VPC's CIDR on the node so it's pushed down to your sites as a route.
- **Sites route natively.** Sites connect with Newt's native routing mode so the tunnel subnet is a real route on the site's host, not just an application-layer proxy.
- **Sites route natively.** Sites connect with native routing mode so the tunnel subnet is a real route on the site's host, not just an application-layer proxy.
## Prerequisites

2
manage/resources/public/raw-resources.mdx
View File

@@ -24,7 +24,7 @@ TCP and UDP resources use **[targets](/manage/resources/public/targets)** like H
This feature is only available in self-hosted Pangolin instances. If you're using Pangolin Cloud, you will need to deploy a remote node.
</Note>
Pangolin supports raw TCP and UDP traffic because Newt can pass anything through the tunnel.
Pangolin supports raw TCP and UDP traffic because a site can pass anything through the tunnel.
In Community Edition or Enterprise Edition, ensure you have the flag enabled in the config file:

2
manage/resources/public/targets.mdx
View File

@@ -12,7 +12,7 @@ Targets function as destination endpoints for your resources:
1. **Resource Creation**: When you create a resource, you configure one or more targets
2. **Traffic Routing**: Incoming traffic is routed to the appropriate target based on your configuration
3. **Network Access**: Newt proxy routes traffic to the local network through the tunnel
3. **Network Access**: The site routes traffic to the local network through the tunnel
4. **Direct Connection**: No additional routing is necessary on the remote network
## Additional Proxy Settings

41
self-host/how-to-update.mdx
View File

@@ -1,9 +1,36 @@
---
title: "How to Update"
description: "Keep your Pangolin deployment up to date with the latest features and security patches"
description: "Keep your self-hosted Pangolin server up to date with the latest features and security patches"
---
Updating Pangolin is straightforward since it's a collection of Docker images. Simply pull the latest images and restart the stack. Migration scripts run automatically to update your database and configuration files when needed.
Updating Pangolin is straightforward since it's a collection of Docker images. Simply pull the latest images and restart the stack.
This page covers updating your self-hosted Pangolin server. To update sites and clients, see the respective guides:
<CardGroup cols={2}>
<Card title="Update Sites" icon="plug" href="/manage/sites/update-site">
Update sites to the latest version.
</Card>
<Card title="Update Clients" icon="desktop" href="/manage/clients/update-client">
Update your installed client to the latest version.
</Card>
</CardGroup>
## Migration Scripts
When Pangolin starts and detects a version update, it runs migration scripts automatically to update your database and configuration files. Pangolin stores the last successfully run version in the database, so it knows which scripts still need to run. Scripts run in order, starting from the oldest unrun script through the latest.
These are commonly SQL schema updates, and sometimes data migrations.
If a release includes a Badger update, Pangolin also tries to update the Traefik config when it still matches the default Pangolin installer Traefik config. If Pangolin cannot apply that change, it fails silently so you can update Badger yourself.
A failed database migration blocks startup and prevents the server from running.
If you are using SQLite, Pangolin automatically creates a copy of the database file before a migration runs so you can roll back if needed. You can disable this by setting the `DISABLE_BACKUP_ON_MIGRATION` environment variable to `true`.
<Warning>
Because migrations can change the database schema, downgrading is sometimes impossible and is not recommended. The database may become incompatible with older versions. Always back up your database before updating.
</Warning>
## Before You Update
@@ -31,7 +58,7 @@ sudo docker compose down
- **Pangolin**: [GitHub Releases](https://github.com/fosrl/pangolin/releases)
- **Gerbil**: [GitHub Releases](https://github.com/fosrl/gerbil/releases)
- **Traefik**: [Docker Hub](https://hub.docker.com/_/traefik)
- **Traefik**: [Docker Hub](https://github.com/traefik/traefik/releases)
- **Badger**: [GitHub Releases](https://github.com/fosrl/badger/releases)
<Info>
@@ -45,15 +72,15 @@ sudo docker compose down
```yaml title="docker-compose.yml"
services:
pangolin:
image: fosrl/pangolin:1.16.0 # Update to latest version
image: fosrl/pangolin:1.22.0 # Check GitHub Releases for latest version tag
# ... rest of config
gerbil:
image: fosrl/gerbil:1.5.0 # Update to latest version
image: fosrl/gerbil:1.5.1 # Check GitHub Releases for latest version tag
# ... rest of config
traefik:
image: traefik:v3.7 # Update if needed
image: traefik:v3.7.12 # Check GitHub Releases for latest version tag
# ... rest of config
```
@@ -64,7 +91,7 @@ services:
plugins:
badger:
moduleName: github.com/fosrl/badger
version: v1.4.1 # Update to latest version
version: v1.7.0 # Check GitHub Releases for latest version tag
```
<Warning>