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

Add docs for managed

Browse Source
This commit is contained in:
Owen
2025-08-21 16:31:33 -07:00
parent c9d6ba92c0
commit a59af90173
14 changed files with 728 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
self-host/advanced/config-file.mdx
View File

@@ -32,6 +32,17 @@ flags:
disable_user_create_org: true
```
In managed mode:
```yaml title="config.yml"
gerbil:
start_port: 51820
base_endpoint: "154.123.45.67" # REPLACE WITH YOUR IP OR DOMAIN
managed:
id: "he4g78wevj25msf"
secret: "n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7d"
```
<Warning>
Generate a strong secret for `server.secret`. Use at least 32 characters with a mix of letters, numbers, and special characters.
@@ -336,6 +347,58 @@ This section contains the complete reference for all configuration options in `c
These middlewares must be defined in your Traefik dynamic configuration.
</Note>
</ResponseField>
<ResponseField name="certificates_path" type="string">
Path where SSL certificates are stored. This is used only with managed Pangolin deployments.
**Example**: `/var/certificates`
**Default**: `/var/certificates`
</ResponseField>
<ResponseField name="monitor_interval" type="integer">
Interval in milliseconds for monitoring configuration changes.
**Example**: `5000`
**Default**: `5000`
</ResponseField>
<ResponseField name="dynamic_cert_config_path" type="string">
Path to the dynamic certificate configuration file. This is used only with managed Pangolin deployments.
**Example**: `/var/dynamic/cert_config.yml`
**Default**: `/var/dynamic/cert_config.yml`
</ResponseField>
<ResponseField name="dynamic_router_config_path" type="string">
Path to the dynamic router configuration file.
**Example**: `/var/dynamic/router_config.yml`
**Default**: `/var/dynamic/router_config.yml`
</ResponseField>
<ResponseField name="site_types" type="array of strings">
Supported site types for Traefik configuration.
**Example**: `["newt", "wireguard", "local"]`
**Default**: `["newt", "wireguard", "local"]`
</ResponseField>
<ResponseField name="file_mode" type="boolean">
Whether to use file-based configuration mode for Traefik.
**Example**: `false`
**Default**: `false`
<Note>
When enabled, uses file-based dynamic configuration instead of API-based updates.
</Note>
</ResponseField>
</Expandable>
</ResponseField>
@@ -543,6 +606,54 @@ This section contains the complete reference for all configuration options in `c
</Expandable>
</ResponseField>
### Managed Configuration
<ResponseField name="managed" type="object">
Managed deployment configuration for connecting self-hosted instances to managed services.
<Expandable title="Managed">
{/* <ResponseField name="name" type="string">
Display name for the managed deployment.
**Example**: `My Self-Hosted Instance`
</ResponseField> */}
<ResponseField name="id" type="string">
Unique identifier for the managed deployment. Generated from the installer or the [Pangolin dashboard](https://pangolin.fossorial.io).
**Example**: `he4g78wevj25msf`
</ResponseField>
<ResponseField name="secret" type="string">
Secret key for authenticating with the managed service. Generated from the installer or the [Pangolin dashboard](https://pangolin.fossorial.io).
**Example**: `n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7d`
<Warning>
Keep this secret secure and do not share it publicly.
</Warning>
</ResponseField>
<ResponseField name="endpoint" type="string">
The managed service endpoint to connect to. This can only change with enterprise deployments.
**Example**: `https://pangolin.fossorial.io`
**Default**: `https://pangolin.fossorial.io`
</ResponseField>
<ResponseField name="redirect_endpoint" type="string">
Custom redirect endpoint for authentication flows. This can only change for enterprise deployments.
**Example**: `https://my-pangolin.example.com`
<Note>
If not specified, the default dashboard URL will be used.
</Note>
</ResponseField>
</Expandable>
</ResponseField>
## Environment Variables
Some configuration values can be set using environment variables for enhanced security:

124
self-host/convert-managed.mdx Normal file
View File

@@ -0,0 +1,124 @@
---
title: "Convert to Managed"
description: "Learn how to convert your self-hosted Pangolin instance to a managed deployment"
---
<Info>
Check out the [Managed Deployment Guide](/self-host/managed-deployment) for more information on deploying a managed instance of Pangolin.
</Info>
## Who is this for?
Use this guide if you have a self-hosted Pangolin instance and want to convert it to a managed deployment. It's pretty easy!
## What will happen to my data?
<Warning>
**Always backup your data before updating.** Copy your `config` directory to a safe location so you can roll back if needed.
</Warning>
Your existing Pangolin data will stay in the database, so feel free to try managed deployment without losing anything. If you want to go back, just reverse these steps.
## Migration
<Steps>
<Step title="Sign up">
Create an account on [Pangolin Cloud](https://pangolin.fossorial.io/auth/signup) if you don't have one already.
</Step>
<Step title="Generate credentials">
In the Pangolin Cloud dashboard, navigate to the "Self-hosted" section and generate a new ID and secret for this PoP. Make sure to copy this config, as you'll need it later.
</Step>
<Step title="Prepare your instance">
On your self-hosted Pangolin server:
1. Stop the Pangolin service:
```bash
docker-compose down
```
2. Ensure you have a backup of your `config` directory.
3. Make sure your instance is [up to date](./how-to-update) with the latest versions of Pangolin, Gerbil, and Traefik.
</Step>
<Step title="Paste in the credentials">
Exit your `config/config.yml` and paste the generated ID and secret managed config at the bottom of the file:
```yaml
managed:
id: <your-generated-id>
secret: <your-generated-secret>
```
You can leave the rest of your config the same.
</Step>
<Step title="Update your docker-compose">
We need to update your `docker-compose.yml` file to use the new managed configuration. Its a good idea to backup the old one.
First change the gerbil port `443:443` to `443:8443`. This will send traffic to the Gerbil SNI proxy server before hitting Traefik downstream.
```
gerbil:
ports:
- "443:8443" # <----- It should look like this now
```
Second, add a volume to sync the certs and file based Traefik config between Pangolin and Traefik. At the bottom of the file:
```yaml
volumes:
pangolin-data:
```
Then in Traefik:
```yaml
traefik:
volumes:
- ./config/traefik:/etc/traefik:ro # Volume to store the Traefik configuration
- ./config/letsencrypt:/letsencrypt # Volume to store the Let's Encrypt certificates
- ./config/traefik/logs:/var/log/traefik # Volume to store Traefik logs
# Shared volume for certificates and dynamic config in file mode
- pangolin-data:/var/certificates:ro
- pangolin-data:/var/dynamic:ro
```
And in Pangolin
```yaml
pangolin:
volumes:
- ./config:/app/config
- pangolin-data:/var/certificates
- pangolin-data:/var/dynamic
```
</Step>
<Step title="Add ping to Traefik">
Edit your `config/traefik/traefik_config.yml` file to add a ping endpoint for health checks. Add this to the bottom of the file:
```yaml
ping:
entryPoint: "web"
```
</Step>
<Step title="Bring up the stack">
Start the updated stack with Docker Compose:
```bash
docker-compose up -d
```
</Step>
<Step title="Configure your account">
Pangolin is now controlled through the [Pangolin Cloud](https://pangolin.fossorial.io/auth/signup) dashboard. Make sure to bring your domain and recreate your sites and resources.
<Tip>
If you move your whole domain away from your VPS to Pangolin Cloud, make sure to update your `base_endpoint` under the `gerbil:` section of your `config.yml` to be the IP address of your instance otherwise we cant resolve your instance in DNS.
</Tip>
In the future, we plan to allow importing config!
</Step>
</Steps>

2
self-host/dns-and-networking.mdx
View File

@@ -77,7 +77,7 @@ Pangolin requires these ports to be open on your VPS:
<Card title="UDP Port 51820">
**Site Tunnels**
This is the default port for sites (Newt) to establish tunnels to the cloud exit node.
This is the default port for sites (Newt) to establish tunnels to the proxy (Gerbil).
</Card>
<Card title="UDP Port 21820">

11
self-host/manual/docker-compose.mdx
View File

@@ -144,6 +144,8 @@ services:
restart: unless-stopped
volumes:
- ./config:/app/config
- pangolin-data:/var/certificates
- pangolin-data:/var/dynamic
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3001/api/v1/"]
interval: "3s"
@@ -186,11 +188,17 @@ services:
volumes:
- ./config/traefik:/etc/traefik:ro # Volume to store the Traefik configuration
- ./config/letsencrypt:/letsencrypt # Volume to store the Let's Encrypt certificates
# Shared volume for certificates and dynamic config in file mode
- pangolin-data:/var/certificates:ro
- pangolin-data:/var/dynamic:ro
networks:
default:
driver: bridge
name: pangolin
volumes:
pangolin-data:
```
## Traefik Static Configuration
@@ -242,6 +250,9 @@ entryPoints:
serversTransport:
insecureSkipVerify: true
ping:
entryPoint: "web"
```
## Traefik Dynamic Configuration

234
self-host/manual/managed.mdx Normal file
View File

@@ -0,0 +1,234 @@
---
title: "Docker Compose Managed"
description: "Deploy managed Pangolin manually using Docker Compose without the automated installer"
---
<Tip>
This guide is for managed Pangolin. If you are looking for self-hosted Pangolin please see the [Docker Compose](self-host/docker-compose) guide.
</Tip>
This guide walks you through setting up Pangolin manually using Docker Compose without the automated installer. This approach gives you full control over the configuration and deployment process.
This guide assumes you already have a Linux server with Docker and Docker Compose installed. If you don't, please refer to the [official Docker documentation](https://docs.docker.com/get-docker/) for installation instructions. You must also have root access to the server.
## Prerequisites
Checkout the [quick install guide](self-host/quick-install-managed) for more info regarding what is needed before you install Pangolin.
## File Structure
Create the following directory structure for your Pangolin deployment:
```
.
├── config/
│ ├── config.yml (*)
│ ├── db/
│ │ └── db.sqlite
│ ├── key
│ └── traefik/
│ ├── traefik_config.yml (*)
└── docker-compose.yml (*)
```
<Info>
Files marked with `(*)` must be created manually. Volumes and other files are generated automatically by the services.
</Info>
<AccordionGroup>
<Accordion title="Configuration Files">
**`config/config.yml`**: Main Pangolin configuration file
- Contains all Pangolin settings and options
- See [Configuration Guide](/pangolin/configuration/config) for details
**`config/traefik/traefik_config.yml`**: Traefik static configuration
- Global Traefik settings and entry points
</Accordion>
<Accordion title="Generated Files">
**`config/db/db.sqlite`**: SQLite database file
- Created automatically on first startup
- Contains all Pangolin data and settings
**`config/key`**: Private key file
- Generated by Gerbil service
- Used for WireGuard tunnel encryption
</Accordion>
<Accordion title="Docker Files">
**`docker-compose.yml`**: Service definitions
- Defines Pangolin, Gerbil, and Traefik services
- Network configuration and volume mounts
- Health checks and dependencies
</Accordion>
</AccordionGroup>
<Steps>
<Step title="Create configuration directory">
```bash
mkdir -p config/traefik config/db
```
</Step>
<Step title="Create configuration files">
Create the main configuration files (see below):
- `docker-compose.yml` (in project root)
- `config/traefik/traefik_config.yml`
- `config/config.yml`
</Step>
<Step title="Update domain">
Edit the configuration files to replace:
- `154.123.45.67` with your actual domain OR public IP address of the PoP
<Warning>
Ensure your domain DNS is properly configured to point to your server's IP address if you choose DNS.
</Warning>
</Step>
</Steps>
## Starting the Stack
<Steps>
<Step title="Start the services">
```bash
sudo docker compose up -d
```
</Step>
<Step title="Monitor startup">
```bash
sudo docker compose logs -f
```
</Step>
<Step title="Verify services">
```bash
sudo docker compose ps
```
All services should show "Up" status after a few minutes.
</Step>
</Steps>
## Docker Compose Configuration
Create `docker-compose.yml` in your project root:
```yaml title="docker-compose.yml"
services:
pangolin:
image: fosrl/pangolin:latest # https://github.com/fosrl/pangolin/releases
container_name: pangolin
restart: unless-stopped
volumes:
- ./config:/app/config
- pangolin-data:/var/certificates
- pangolin-data:/var/dynamic
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3001/api/v1/"]
interval: "3s"
timeout: "3s"
retries: 15
gerbil:
image: fosrl/gerbil:latest # https://github.com/fosrl/gerbil/releases
container_name: gerbil
restart: unless-stopped
depends_on:
pangolin:
condition: service_healthy
command:
- --reachableAt=http://gerbil:3003
- --generateAndSaveKeyTo=/var/config/key
- --remoteConfig=http://pangolin:3001/api/v1/
volumes:
- ./config/:/var/config
cap_add:
- NET_ADMIN
- SYS_MODULE
ports:
- 51820:51820/udp
- 21820:21820/udp
- 443:8443
- 80:80
traefik:
image: traefik:v3.4.0
container_name: traefik
restart: unless-stopped
network_mode: service:gerbil # Ports appear on the gerbil service
depends_on:
pangolin:
condition: service_healthy
command:
- --configFile=/etc/traefik/traefik_config.yml
volumes:
- ./config/traefik:/etc/traefik:ro # Volume to store the Traefik configuration
- ./config/letsencrypt:/letsencrypt # Volume to store the Let's Encrypt certificates
# Shared volume for certificates and dynamic config in file mode
- pangolin-data:/var/certificates:ro
- pangolin-data:/var/dynamic:ro
networks:
default:
driver: bridge
name: pangolin
volumes:
pangolin-data:
```
## Traefik Static Configuration
Create `config/traefik/traefik_config.yml`:
```yaml title="config/traefik/traefik_config.yml"
api:
insecure: true
dashboard: true
providers:
file:
directory: "/var/dynamic"
watch: true
experimental:
plugins:
badger:
moduleName: "github.com/fosrl/badger"
version: "v1.2.0"
log:
level: "INFO"
format: "common"
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
transport:
respondingTimeouts:
readTimeout: "30m"
serversTransport:
insecureSkipVerify: true
ping:
entryPoint: "web"
```
## Pangolin Configuration
```yaml title="config/config.yml"
gerbil:
start_port: 51820
base_endpoint: "154.123.45.67" # REPLACE WITH YOUR IP OR DOMAIN
managed:
id: "he4g78wevj25msf"
secret: "n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7d"
```

102
self-host/quick-install-managed.mdx Normal file
View File

@@ -0,0 +1,102 @@
---
title: "Quick Install Managed"
description: "Deploy your own managed Pangolin reverse proxy server in under 10 minutes with our automated installer"
---
<Note>
[Why would I want to deploy a managed Pangolin instance?](../manage/managed.mdx)
</Note>
## Prerequisites
Before you begin, ensure you have:
- **Linux server** with root access and public IP address
- **Open ports on firewall** for 80 (TCP), 443 (TCP), 51820 (UDP), and 21820 (UDP for clients)
<Tip>
**Recommended**: Ubuntu 20.04+ or Debian 11+ for best compatibility and performance.
</Tip>
## Choose Your Server
Need help choosing? See our [complete VPS guide](/self-host/choosing-a-vps) for suggestions.
## DNS & Networking
Before installing Pangolin, ensure you've opened the required port on your firewall. See our guide on [DNS & networking](/self-host/dns-and-networking) for more information.
## Installation Process
<Steps>
<Step title="Download the installer">
Connect to your server via SSH and download the installer:
```bash
curl -fsSL https://digpangolin.com/get-installer.sh | bash
```
The installer supports both AMD64 (x86_64) and ARM64 architectures.
</Step>
<Step title="Run the installer">
Execute the installer with root privileges:
```bash
sudo ./installer
```
The installer places all files in the current directory. Move the installer to your desired installation directory before running it.
</Step>
<Step title="Do you already have credentials from the dashboard?">
If you are on your game and have already generated credentials for this PoP in the dashboard enter them here.
<Tip>
If you don't have them yet you can just select no when asked and we will create it in a later step.
</Tip>
</Step>
<Step title="The public addressable IP address for this PoP">
Enter either the public IP address of your server or a domain name that resolves to it.
If you choose to use a domain keep in mind this just resolves your PoP on the internet while the actual subdomains for resources will be managed in the cloud.
</Step>
<Step title="Generate credentials">
If you did not enter credentials earlier then you should see something like the following:
```
Your managed credentials have been obtained successfully.
ID: he4g78wevj25msf
Secret: n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7d
```
Go to the [Pangolin dashboard](https://pangolin.fossorial.io/) and log in. Navigate to the "Self-hosted" section and add a new PoP. Use this ID and secret to register your PoP.
<Tip>
More than one account can use the same PoP credentials. This is useful for teams.
</Tip>
</Step>
</Steps>
## Post-Installation Setup
Once installation completes successfully, you'll see:
```
Installation complete!
```
Navigate to the [Pangolin dashboard](https://pangolin.fossorial.io/) and create sites, resources, and targets for your managed PoP.
{/* ## Video Walkthrough */}

2
self-host/quick-install.mdx
View File

@@ -118,7 +118,7 @@ https://pangolin.example.com/auth/initial-setup
```
<Check>
The dashboard should load with SSL certificate automatically configured. It might take a few minutes for the first cert to validate, so don't worry if the brwoser throws an insecure warning.
The dashboard should load with SSL certificate automatically configured. It might take a few minutes for the first cert to validate, so don't worry if the browser throws an insecure warning.
</Check>
</Step>