deploy

self-host/dns-and-networking.mdx

@@ -57,7 +57,7 @@ You'll need to create A (or AAAA for IPv6) records pointing to your VPS IP addre
 
 Pangolin requires these ports to be open on your VPS:
 
-<CardGroup cols={3}>
+<CardGroup cols={2}>
 <Card title="TCP Port 80">
   **HTTP/SSL Verification**
   
@@ -75,14 +75,22 @@ Pangolin requires these ports to be open on your VPS:
 </Card>
 
 <Card title="UDP Port 51820">
-  **WireGuard Tunnel**
+  **Site Tunnels**
   
-  - Newt client connections
-  - Gerbil tunnel endpoint
-  - Secure traffic routing
+  This is the default port for sites (Newt) to establish tunnels to the cloud exit node.
+</Card>
+
+<Card title="UDP Port 21820">
+  **Client Tunnels**
+
+  This is the default port for clients relaying through Gerbil to newt. This port is only required for clients.
 </Card>
 </CardGroup>
 
+<Warning>
+Always verify your exposed ports (e.g., with [nmap](https://nmap.org/) or [RustScan](https://github.com/bee-san/RustScan)) and ensure you expose **only** the ports that are absolutely necessary. By tunneling out to the VPS, you are effectively including the VPS in your security boundary, so you must secure it as part of your overall network strategy. For more details, see [Docker’s port publishing documentation](https://docs.docker.com/engine/network/packet-filtering-firewalls/#port-publishing-and-mapping).
+</Warning>
+
 ### Docker Port Exposure
 
 By default, Pangolin exposes these ports on all interfaces:

self-host/how-to-update.mdx

@@ -32,6 +32,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)
+  - **Badger**: [GitHub Releases](https://github.com/fosrl/badger/releases)
   
   <Info>
   Look for the latest stable release (not pre-release or beta versions).
@@ -55,6 +56,16 @@ services:
       image: traefik:v3.4.0       # Update if needed
       # ... rest of config
   ```
+
+  Increase the Badger version number in `config/traefik_config.yml`:
+
+  ```yaml title="traefik_config.yml"
+  experimental:
+    plugins:
+      badger:
+        moduleName: github.com/fosrl/badger
+        version: v1.2.0 # Update to latest version
+  ```
   
   <Warning>
   Update each service you want to upgrade. You can update them individually or all at once.

self-host/manual/unraid.mdx

@@ -313,6 +313,19 @@ Anywhere you see `http://pangolin:3001` must match. The hostname should be the n
 
 **WireGuard Port:**
 
+<Warning>
+You **must** use the default port of `51822` for WireGuard in the Gerbil container. Using any other port may cause connection issues that are difficult to debug.
+
+Make sure this is also reflected in your Pangolin `config.yml`:
+
+```yml
+gerbil:
+  start_port: 51822
+```
+
+See [this GitHub issue comment](https://github.com/fosrl/pangolin/issues/227#issuecomment-2781608815) for more details.
+</Warning>
+
 The port you use for WireGuard must also match what you set the port to in the Pangolin config. By default we use a slightly different port than the standard WireGuard port to avoid conflicts with the built in WireGuard server in Unraid.
 
 **HTTP and HTTPS Ports:**

self-host/system-architecture.mdx

@@ -0,0 +1,66 @@
+---
+"title": "System Architecture"
+"description": "Learn how the components of the system interact to form Pangolin"
+---
+
+### Pangolin (Control Plane)
+
+Pangolin is the main control center that orchestrates the entire system:
+
+- **Web Interface**: Management dashboard for configuring sites, users, and access policies
+- **REST API**: External API for automation and integration
+- **WebSocket Server**: Manages real-time connections to edge network clients
+- **Authentication System**: Handles user authentication and authorization
+- **Database**: Stores configuration, user data, and system state
+
+<Info>
+Pangolin acts as the brain of the system, coordinating all other components and managing user access.
+</Info>
+
+### Gerbil (Tunnel Manager)
+
+Gerbil manages the secure WireGuard tunnels between your edge networks and the central server:
+
+- **Peer Management**: Creates and maintains WireGuard connections
+- **Tunnel Orchestration**: Handles tunnel creation, updates, and cleanup
+- **Security**: Ensures all traffic is encrypted using WireGuard's cryptographic protocols
+
+<Check>
+WireGuard provides fast, secure, and reliable tunneling with minimal overhead.
+</Check>
+
+### Newt (Edge Client)
+
+Newt is a lightweight client that runs on your edge networks (servers, VMs, or containers):
+
+- **Automatic Discovery**: Finds the optimal point of presence for best performance
+- **Dual Connection**: Connects to Pangolin via WebSocket and Gerbil via WireGuard
+- **Resource Proxy**: Creates TCP/UDP proxies to expose your applications securely
+
+<Tip>
+Newt is designed to be resource-efficient and can run on minimal hardware or in containers.
+</Tip>
+
+### Reverse Proxy (Router)
+
+The reverse proxy handles incoming requests and routes them to your applications:
+
+- **Request Routing**: Directs traffic to the correct backend services
+- **SSL Termination**: Manages HTTPS certificates and encryption
+- **Middleware Support**: Integrates with security and monitoring plugins
+
+### Badger (Authentication Middleware)
+
+Badger is Pangolin's middleware that enforces access control:
+
+- **Request Interception**: Catches all incoming requests before they reach your applications
+- **Authentication Check**: Verifies user identity and permissions
+- **Secure Redirects**: Sends unauthenticated users to Pangolin's login system
+
+<Warning>
+Badger ensures that only authenticated and authorized users can access your applications, even if they bypass other security measures.
+</Warning>
+
+<Frame caption="System architecture showing Pangolin components and their interactions">
+<img src="/images/system-diagram.svg" alt="Pangolin system architecture diagram"/>
+</Frame>