pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-02-11 15:36:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Renaming to remote-nodes

Browse Source
This commit is contained in:
Owen
2025-10-14 10:46:25 -07:00
parent d2fe75bab7
commit dfd2349c7a
34 changed files with 30 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
self-host/advanced/cloudflare-proxy.mdx
View File

@@ -1,56 +0,0 @@
---
title: "Cloudflare Proxy"
---
Pangolin works with Cloudflare proxy (orange cloud) enabled, but requires specific configuration:
<Warning>
**Terms of Service**: Enabling Cloudflare proxy binds you to Cloudflare's terms of service as traffic routes through their network.
</Warning>
### SSL Configuration
**Recommended setup:**
1. **Use wildcard certificates** with DNS-01 challenge
2. **Set SSL/TLS mode to Full (Strict)**
3. **Disable port 80** (not needed with wildcard certs)
<Info>
Pangolin will **not work** with Cloudflare's Full or Automatic SSL/TLS modes. Only Full (Strict) mode is supported.
</Info>
### WireGuard Configuration
Since Cloudflare proxy obscures the destination IP, you must explicitly set your VPS IP in the [config file](/self-host/advanced/config-file):
```yaml
gerbil:
base_endpoint: "YOUR_VPS_IP_ADDRESS" # Required with Cloudflare proxy
```
<Steps>
<Step title="Get your VPS IP">
Find your VPS public IP address:
```bash
curl ifconfig.io
```
</Step>
<Step title="Update configuration">
Add the IP to your `config.yml`:
```yaml
gerbil:
base_endpoint: "104.21.16.1" # Replace with your actual IP
```
</Step>
<Step title="Restart services">
Restart Pangolin to apply the changes:
```bash
docker-compose restart
```
</Step>
</Steps>

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

@@ -1,689 +0,0 @@
---
title: "Configuration File"
description: "Configure Pangolin using the config.yml file with detailed settings for all components"
---
The `config.yml` file controls all aspects of your Pangolin deployment, including server settings, domain configuration, email setup, and security options. This file is mounted at `config/config.yml` in your Docker container.
## Setting up your `config.yml`
To get started, create a basic configuration file with the essential settings:
Minimal Pangolin configuration:
```yaml title="config.yml"
app:
dashboard_url: "https://pangolin.example.com"
domains:
domain1:
base_domain: "pangolin.example.com"
cert_resolver: "letsencrypt"
server:
secret: "your-strong-secret"
gerbil:
base_endpoint: "pangolin.example.com"
flags:
require_email_verification: false
disable_signup_without_invite: true
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.
</Warning>
## Reference
This section contains the complete reference for all configuration options in `config.yml`.
### Application Settings
<ResponseField name="app" type="object" required>
Core application configuration including dashboard URL, logging, and general settings.
<Expandable title="App">
<ResponseField name="dashboard_url" type="string" required>
The URL where your Pangolin dashboard is hosted.
**Examples**: `https://example.com`, `https://pangolin.example.com`
This URL is used for generating links, redirects, and authentication flows. You can run Pangolin on a subdomain or root domain.
</ResponseField>
<ResponseField name="log_level" type="string">
The logging level for the application.
**Options**: `debug`, `info`, `warn`, `error`
**Default**: `info`
</ResponseField>
<ResponseField name="save_logs" type="boolean">
Whether to save logs to files in the `config/logs/` directory.
**Default**: `false`
<Note>
When enabled, logs rotate automatically:
- Max file size: 20MB
- Max files: 7 days
</Note>
</ResponseField>
<ResponseField name="log_failed_attempts" type="boolean">
Whether to log failed authentication attempts for security monitoring.
**Default**: `false`
</ResponseField>
<ResponseField name="telemetry" type="object">
Telemetry configuration settings.
<Expandable title="Telemetry">
<ResponseField name="anonymous_usage" type="boolean">
Whether to enable anonymous usage telemetry.
**Default**: `true`
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
### Server Configuration
<ResponseField name="server" type="object" required>
Server ports, networking, and authentication settings.
<Expandable title="Server">
<ResponseField name="external_port" type="integer">
The port for the front-end API that handles external requests.
**Example**: `3000`
</ResponseField>
<ResponseField name="internal_port" type="integer">
The port for the internal private-facing API.
**Example**: `3001`
</ResponseField>
<ResponseField name="next_port" type="integer">
The port for the frontend server (Next.js).
**Example**: `3002`
</ResponseField>
<ResponseField name="integration_port" type="integer">
The port for the integration API (optional).
**Example**: `3004`
</ResponseField>
<ResponseField name="internal_hostname" type="string">
The hostname of the Pangolin container for internal communication.
**Example**: `pangolin`
<Tip>
If using Docker Compose, this should match your container name.
</Tip>
</ResponseField>
<ResponseField name="session_cookie_name" type="string">
The name of the session cookie for storing authentication tokens.
**Example**: `p_session_token`
**Default**: `p_session_token`
</ResponseField>
<ResponseField name="resource_access_token_param" type="string">
Query parameter name for passing access tokens in requests.
**Example**: `p_token`
**Default**: `p_token`
</ResponseField>
<ResponseField name="resource_access_token_headers" type="object">
HTTP headers for passing access tokens in requests.
<Expandable title="Headers">
<ResponseField name="id" type="string">
Header name for access token ID.
**Example**: `P-Access-Token-Id`
</ResponseField>
<ResponseField name="token" type="string">
Header name for access token.
**Example**: `P-Access-Token`
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="resource_session_request_param" type="string">
Query parameter for session request tokens.
**Example**: `p_session_request`
**Default**: `p_session_request`
</ResponseField>
<ResponseField name="cors" type="object">
Cross-Origin Resource Sharing (CORS) configuration.
<Expandable title="CORS">
<ResponseField name="origins" type="array of strings">
Allowed origins for cross-origin requests.
**Example**: `["https://pangolin.example.com"]`
</ResponseField>
<ResponseField name="methods" type="array of strings">
Allowed HTTP methods for CORS requests.
**Example**: `["GET", "POST", "PUT", "DELETE", "PATCH"]`
</ResponseField>
<ResponseField name="allowed_headers" type="array of strings">
Allowed HTTP headers in CORS requests.
**Example**: `["X-CSRF-Token", "Content-Type"]`
</ResponseField>
<ResponseField name="credentials" type="boolean">
Whether to allow credentials in CORS requests.
**Default**: `true`
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="trust_proxy" type="integer">
Number of proxy headers to trust for client IP detection.
**Example**: `1`
**Default**: `1`
<Tip>
Use `1` if running behind a single reverse proxy like Traefik.
</Tip>
</ResponseField>
<ResponseField name="dashboard_session_length_hours" type="integer">
Dashboard session duration in hours.
**Example**: `720` (30 days)
**Default**: `720`
</ResponseField>
<ResponseField name="resource_session_length_hours" type="integer">
Resource session duration in hours.
**Example**: `720` (30 days)
**Default**: `720`
</ResponseField>
<ResponseField name="secret" type="string" required>
Secret key for encrypting sensitive data.
**Environment Variable**: `SERVER_SECRET`
**Minimum Length**: 8 characters
**Example**: `"d28@a2b.2HFTe2bMtZHGneNYgQFKT2X4vm4HuXUXBcq6aVyNZjdGt6Dx-_A@9b3y"`
<Warning>
Generate a strong, random secret. This is used for encrypting sensitive data and should be kept secure.
</Warning>
</ResponseField>
</Expandable>
</ResponseField>
### Domain Configuration
<ResponseField name="domains" type="object" required>
Domain settings for SSL certificates and routing.
At least one domain must be configured.
<Expandable title="Domains">
<ResponseField name="<domain_key>" type="object">
Domain configuration with a unique key of your choice.
<Expandable title="Domain Settings">
<ResponseField name="base_domain" type="string" required>
The base domain for this configuration.
**Example**: `example.com`
</ResponseField>
<ResponseField name="cert_resolver" type="string" required>
The Traefik certificate resolver name.
**Example**: `letsencrypt`
<Note>
This must match the certificate resolver name in your Traefik configuration.
</Note>
</ResponseField>
<ResponseField name="prefer_wildcard_cert" type="boolean">
Whether to prefer wildcard certificates for this domain.
**Example**: `true`
<Tip>
Useful for domains with many subdomains to reduce certificate management overhead.
</Tip>
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
### Traefik Integration
<ResponseField name="traefik" type="object">
Traefik reverse proxy configuration settings.
<Expandable title="Traefik">
<ResponseField name="http_entrypoint" type="string">
The Traefik entrypoint name for HTTP traffic.
**Example**: `web`
<Note>
Must match the entrypoint name in your Traefik configuration.
</Note>
</ResponseField>
<ResponseField name="https_entrypoint" type="string">
The Traefik entrypoint name for HTTPS traffic.
**Example**: `websecure`
<Note>
Must match the entrypoint name in your Traefik configuration.
</Note>
</ResponseField>
<ResponseField name="cert_resolver" type="string">
The default certificate resolver for domains created through the UI.
**Example**: `letsencrypt`
<Note>
This only applies to domains created through the Pangolin dashboard.
</Note>
</ResponseField>
<ResponseField name="prefer_wildcard_cert" type="boolean">
Whether to prefer wildcard certificates for UI-created domains.
**Example**: `true`
<Note>
This only applies to domains created through the Pangolin dashboard.
</Note>
</ResponseField>
<ResponseField name="additional_middlewares" type="array of strings">
Additional Traefik middlewares to apply to resource routers.
**Example**: `["middleware1", "middleware2"]`
<Note>
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>
### Gerbil Tunnel Controller
<ResponseField name="gerbil" type="object" required>
Gerbil tunnel controller settings for WireGuard tunneling.
<Expandable title="Gerbil">
<ResponseField name="base_endpoint" type="string" required>
Domain name included in WireGuard configuration for tunnel connections.
**Example**: `pangolin.example.com`
</ResponseField>
<ResponseField name="start_port" type="integer">
Starting port for WireGuard tunnels.
**Example**: `51820`
</ResponseField>
<ResponseField name="use_subdomain" type="boolean">
Whether to assign unique subdomains to Gerbil exit nodes.
**Default**: `false`
<Warning>
Keep this set to `false` for most deployments.
</Warning>
</ResponseField>
<ResponseField name="subnet_group" type="string">
IP address CIDR range for Gerbil exit node subnets.
**Example**: `10.0.0.0/8`
</ResponseField>
<ResponseField name="block_size" type="integer">
Block size for Gerbil exit node CIDR ranges.
**Example**: `24`
</ResponseField>
<ResponseField name="site_block_size" type="integer">
Block size for site CIDR ranges connected to Gerbil.
**Example**: `26`
</ResponseField>
</Expandable>
</ResponseField>
### Rate Limiting
<ResponseField name="rate_limits" type="object">
Rate limiting configuration for API requests.
<Expandable title="Rate Limits">
<ResponseField name="global" type="object">
Global rate limit settings for all external API requests.
<Expandable title="Global">
<ResponseField name="window_minutes" type="integer">
Time window for rate limiting in minutes.
**Example**: `1`
</ResponseField>
<ResponseField name="max_requests" type="integer">
Maximum number of requests allowed in the time window.
**Example**: `100`
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
### Email Configuration
<ResponseField name="email" type="object">
SMTP settings for sending transactional emails.
<Expandable title="Email">
<ResponseField name="smtp_host" type="string">
SMTP server hostname.
**Example**: `smtp.gmail.com`
</ResponseField>
<ResponseField name="smtp_port" type="integer">
SMTP server port.
**Example**: `587` (TLS) or `465` (SSL)
</ResponseField>
<ResponseField name="smtp_user" type="string">
SMTP username.
**Example**: `no-reply@example.com`
</ResponseField>
<ResponseField name="smtp_pass" type="string">
SMTP password.
**Environment Variable**: `EMAIL_SMTP_PASS`
</ResponseField>
<ResponseField name="smtp_secure" type="boolean">
Whether to use secure connection (SSL/TLS).
**Default**: `false`
<Tip>
Enable this when using port 465 (SSL).
</Tip>
</ResponseField>
<ResponseField name="no_reply" type="string">
From address for sent emails.
**Example**: `no-reply@example.com`
<Note>
Usually the same as `smtp_user`.
</Note>
</ResponseField>
<ResponseField name="smtp_tls_reject_unauthorized" type="boolean">
Whether to fail on invalid server certificates.
**Default**: `true`
</ResponseField>
</Expandable>
</ResponseField>
### Feature Flags
<ResponseField name="flags" type="object">
Feature flags to control application behavior.
<Expandable title="Flags">
<ResponseField name="require_email_verification" type="boolean">
Whether to require email verification for new users.
**Default**: `false`
<Warning>
Only enable this if you have email configuration set up.
</Warning>
</ResponseField>
<ResponseField name="disable_signup_without_invite" type="boolean">
Whether to disable public user registration.
**Default**: `false`
<Note>
Users can still sign up with valid invites when enabled.
</Note>
</ResponseField>
<ResponseField name="disable_user_create_org" type="boolean">
Whether to prevent users from creating organizations.
**Default**: `false`
<Note>
Server admins can always create organizations.
</Note>
</ResponseField>
<ResponseField name="allow_raw_resources" type="boolean">
Whether to allow raw TCP/UDP resource creation.
**Default**: `true`
<Note>
If set to `false`, users will only be able to create http/https resources.
</Note>
</ResponseField>
<ResponseField name="enable_integration_api" type="boolean">
Whether to enable the integration API.
**Default**: `false`
</ResponseField>
</Expandable>
</ResponseField>
### Database Configuration
<ResponseField name="postgres" type="object">
PostgreSQL database configuration (optional).
<Expandable title="PostgreSQL">
<ResponseField name="connection_string" type="string" required>
PostgreSQL connection string.
**Example**: `postgresql://user:password@host:port/database`
<Note>
See [PostgreSQL documentation](/self-host/advanced/database-options#postgresql) for setup instructions.
</Note>
</ResponseField>
</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:
<CardGroup cols={2}>
<Card title="Server Secret" icon="key">
**Variable**: `SERVER_SECRET`
**Config**: `server.secret`
Use this to avoid hardcoding secrets in your config file.
</Card>
<Card title="Email Password" icon="mail">
**Variable**: `EMAIL_SMTP_PASS`
**Config**: `email.smtp_pass`
Keep SMTP passwords secure using environment variables.
</Card>
</CardGroup>

34
self-host/advanced/container-cli-tool.mdx
View File

@@ -1,34 +0,0 @@
---
title: "Internal CLI (pangctl)"
description: "Command-line tool for managing your Pangolin instance"
---
The Pangolin container includes a CLI tool called `pangctl` that provides commands to help you manage your Pangolin instance.
## Accessing the CLI
Run the following command on the host where the Pangolin container is running:
```bash
docker exec -it pangolin pangctl <command>
```
## Available Commands
To see all available commands:
```bash
docker exec -it pangolin pangctl --help
```
## Set Admin Credentials
Set or reset admin credentials for your Pangolin instance:
```bash
docker exec -it pangolin pangctl set-admin-credentials --email "admin@example.com" --password "Password123!"
```
<Warning>
Use a strong password and keep your admin credentials secure.
</Warning>

100
self-host/advanced/database-options.mdx
View File

@@ -1,100 +0,0 @@
---
title: "Database Options"
description: "Configure SQLite or PostgreSQL database for Pangolin"
---
Pangolin supports two database options: SQLite for simplicity and PostgreSQL for production deployments.
<CardGroup cols={2}>
<Card title="SQLite (Default)" icon="database">
- No configuration required
- Easy to use and portable
- Built into the main image
- Perfect for development
</Card>
<Card title="PostgreSQL" icon="database">
- Production-ready database
- Better performance at scale
- Requires separate image
- Advanced configuration options
</Card>
</CardGroup>
## SQLite
By default, Pangolin uses SQLite for its ease of use and portability.
**Docker Image**: `fosrl/pangolin:<version>`
<Note>
No configuration is required to use SQLite with Pangolin.
</Note>
## PostgreSQL
You can optionally use PostgreSQL for production deployments.
**Docker Image**: `fosrl/pangolin:postgresql-<version>`
### Configuration
Add the following section to your Pangolin configuration file:
```yaml title="config.yml"
postgres:
connection_string: postgresql://<user>:<password>@<host>:<port>/<database>
```
<Warning>
Replace the placeholders with your actual PostgreSQL connection details.
</Warning>
### Docker Compose Example
This example sets up PostgreSQL with health checks to ensure the database is ready before Pangolin starts:
```yaml title="docker-compose.yml"
name: pangolin
services:
pangolin:
image: fosrl/pangolin:postgresql-latest # Don't use latest in production
container_name: pangolin
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
volumes:
- ./config:/app/config
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3001/api/v1/"]
interval: "10s"
timeout: "10s"
retries: 15
# ... other services ...
postgres:
image: postgres:17
container_name: postgres
restart: unless-stopped
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
volumes:
- ./config/postgres:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
```
<Warning>
This example is not necessarily production-ready. Adjust the configuration according to your needs and security requirements.
</Warning>
<Note>
Do not use `latest` tags in production. Use specific version tags for stability.
</Note>

73
self-host/advanced/integration-api.mdx
View File

@@ -1,73 +0,0 @@
---
title: "Enable Integration API"
description: "Enable and configure the Integration API for external access"
---
The Integration API provides programmatic access to Pangolin functionality. It includes OpenAPI documentation via Swagger UI.
## Enable Integration API
Update your Pangolin configuration file:
```yaml title="config.yml"
flags:
enable_integration_api: true
```
If you want to specify a port other than the default `3004`, you can do so in the config as well:
```yaml title="config.yml"
server:
integration_port: 3004 # Specify different port
```
## Configure Traefik Routing
Add the following configuration to your `dynamic_config.yml` to expose the Integration API at `https://api.example.com/v1`:
```yaml title="dynamic_config.yml"
http:
middlewares:
redirect-to-https:
redirectScheme:
scheme: https
routers:
int-api-router-redirect:
rule: "Host(`api.example.com`)"
service: int-api-service
entryPoints:
- web
middlewares:
- redirect-to-https
int-api-router:
rule: "Host(`api.example.com`)"
service: int-api-service
entryPoints:
- websecure
tls:
certResolver: letsencrypt
services:
int-api-service:
loadBalancer:
servers:
- url: "http://pangolin:3004"
```
## Access Documentation
Once configured, access the Swagger UI documentation at:
```
https://api.example.com/v1/docs
```
<Frame caption="Swagger UI documentation interface">
<img src="/images/swagger.png" alt="Swagger UI Preview"/>
</Frame>
<Note>
The Integration API will be accessible at `https://api.example.com/v1` for external applications.
</Note>

101
self-host/advanced/postgresql.mdx
View File

@@ -1,101 +0,0 @@
---
title: "Database Options"
description: "Configure SQLite or PostgreSQL database for Pangolin"
---
## Overview
> Choose between SQLite (default) or PostgreSQL for your database
Pangolin supports two database options: SQLite for simplicity and PostgreSQL for production deployments.
<CardGroup cols={2}>
<Card title="SQLite (Default)" icon="database">
- No configuration required
- Easy to use and portable
- Built into the main image
- Perfect for development
</Card>
<Card title="PostgreSQL" icon="postgres">
- Production-ready database
- Better performance at scale
- Requires separate image
- Advanced configuration options
</Card>
</CardGroup>
## SQLite
By default, Pangolin uses SQLite for its ease of use and portability.
**Docker Image**: `fosrl/pangolin:<version>`
<Note>
No configuration is required to use SQLite with Pangolin.
</Note>
## PostgreSQL
You can optionally use PostgreSQL for production deployments.
**Docker Image**: `fosrl/pangolin:postgresql-<version>`
### Configuration
Add the following section to your Pangolin configuration file:
```yaml title="config.yml"
postgres:
connection_string: postgresql://<user>:<password>@<host>:<port>/<database>
```
<Warning>
Replace the placeholders with your actual PostgreSQL connection details.
</Warning>
### Docker Compose Example
This example sets up PostgreSQL with health checks to ensure the database is ready before Pangolin starts:
```yaml title="docker-compose.yml"
name: pangolin
services:
pangolin:
image: fosrl/pangolin:postgresql-latest
container_name: pangolin
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
volumes:
- ./config:/app/config
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3001/api/v1/"]
interval: "10s"
timeout: "10s"
retries: 15
postgres:
image: postgres:17
container_name: postgres
restart: unless-stopped
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
volumes:
- ./config/postgres:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
```
<Warning>
This example is not necessarily production-ready. Adjust the configuration according to your needs and security requirements.
</Warning>
<Note>
Do not use `latest` tags in production. Use specific version tags for stability.
</Note>

42
self-host/advanced/timezone.mdx
View File

@@ -1,42 +0,0 @@
---
title: "Container Timezone"
description: "Configure the timezone for Pangolin, Gerbil, and Traefik containers to match your local time."
---
By default, Docker containers report logs and timestamps in **UTC**. If you want the containers and their log output to use your local timezone, you need to set the timezone in both the container environment and mount the host timezone files.
## Updating your `docker-compose.yml`
Add the following to your `pangolin`, `gerbil`, and `traefik` services in `docker-compose.yml`:
```yaml title="docker-compose.yml"
services:
pangolin:
environment:
- TZ=America/New_York # Set your local timezone
volumes:
- /etc/localtime:/etc/localtime:ro # Sync host timezone
- /etc/timezone:/etc/timezone:ro # Optional: some apps read this file
gerbil:
volumes:
- /etc/localtime:/etc/localtime:ro
- /etc/timezone:/etc/timezone:ro
traefik:
environment:
- TZ=America/New_York
volumes:
- /etc/localtime:/etc/localtime:ro
- /etc/timezone:/etc/timezone:ro
```
### Notes
- **Environment variable `TZ`** ensures most applications inside the container use the correct local timezone.
- **`/etc/localtime` volume** ensures that system utilities (e.g., `date`) inside the container show the correct time.
- **`/etc/timezone` volume** is optional, but some scripts and apps on Debian-based images read it to determine the timezone.
- Logs generated by the containers (including Traefik and Gerbil) will now reflect your local time instead of UTC.
<Warning>
Make sure that the host system has the correct timezone configured, as the containers will reference these host files.
</Warning>

249
self-host/advanced/wild-card-domains.mdx
View File

@@ -1,249 +0,0 @@
---
title: "Wildcard Domains"
description: "Configure wildcard SSL certificates for automatic subdomain security with DNS-01 challenge"
---
Wildcard certificates allow you to secure unlimited subdomains with a single SSL certificate, eliminating the need to generate individual certificates for each subdomain. Pangolin uses Traefik's built-in Let's Encrypt integration to automatically manage these certificates.
<Warning>
Before setting up wildcard certificates, you must have a domain that you own and control. You must also have access to the DNS records for this domain.
</Warning>
<Info>
Since Pangolin uses Traefik as a reverse proxy, it has built-in support for Let's Encrypt certificates. This allows you to easily secure your Pangolin instance and all proxied resources with HTTPS. Let's Encrypt provides free SSL certificates, which are automatically renewed.
</Info>
If you used the default settings during installation, your Traefik instance should be set up to use `HTTP-01` challenge for certificate generation. This challenge is the easiest to configure and requires that the Traefik instance be accessible from the internet on port 80.
<Note>
It is highly recommended that you read the [official Traefik documentation](https://doc.traefik.io/traefik/https/acme/) on ACME and Let's Encrypt before proceeding.
</Note>
## Benefits of Wildcard Certificates
<CardGroup cols={3}>
<Card title="Single Certificate" icon="certificate">
Secure unlimited subdomains with one certificate, reducing management overhead.
</Card>
<Card title="Instant Subdomains" icon="bolt">
Add new subdomains without waiting for certificate generation (up to a few minutes).
</Card>
<Card title="Rate Limit Friendly" icon="shield">
Reduce Let's Encrypt rate limit impact by using fewer certificate requests.
</Card>
</CardGroup>
### Examples
- A wildcard cert `*.example.com` could protect:
- `api.example.com`
- `blog.example.com`
- `dashboard.example.com`
- Another wildcard `*.subdomain.example.com` could protect:
- `api.subdomain.example.com`
- `blog.subdomain.example.com`
<Info>
The [rate limits](https://letsencrypt.org/docs/rate-limits/) for Let's Encrypt are per domain. Using a wildcard certificate reduces the number of domains you have, which can help you avoid hitting these limits.
</Info>
## Setting Up Wildcard Certificates
<Steps>
<Step title="Stop the stack">
Make sure the stack is not running before making configuration changes.
</Step>
<Step title="Update Traefik configuration">
Update the Traefik configuration to use the DNS-01 challenge instead of the HTTP-01 challenge. This tells Traefik to use your DNS provider to create the DNS records needed for the challenge.
</Step>
<Step title="Configure Pangolin">
Set the `prefer_wildcard_cert` flag to `true` in the Pangolin configuration file for your domain.
</Step>
</Steps>
<Note>
This setting will try to encourage Traefik to request one wildcard certificate for each level of the domain used by your existing resources.
**Example**: If you have two resources `blog.example.com` and `blog.subdomain.example.com`, Traefik should try to request a wildcard certificate for `*.example.com` and `*.subdomain.example.com` automatically for you.
</Note>
## Traefik Configuration
### Default Config for HTTP-01 Challenge
This is the default config generated by the installer. This is shown here for reference to compare with the wildcard config below.
<AccordionGroup>
<Accordion title="1. HTTP Challenge Configuration">
Tell Traefik to use the `web` entrypoint for the HTTP challenge.
```yaml title="traefik_config.yml" highlight={4,5}
certificatesResolvers:
letsencrypt:
acme:
httpChallenge:
entryPoint: web
email: admin@example.com
storage: "/letsencrypt/acme.json"
caServer: "https://acme-v02.api.letsencrypt.org/directory"
```
</Accordion>
<Accordion title="2. Dynamic Configuration">
Set the cert resolver to `letsencrypt` and the entrypoint to `websecure` in the dynamic config.
```yaml title="dynamic_config.yml"
next-router:
rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)"
service: next-service
entryPoints:
- websecure
tls:
certResolver: letsencrypt
```
</Accordion>
</AccordionGroup>
### Wildcard Config for DNS-01 Challenge
<Steps>
<Step title="1. Configure DNS Challenge">
Tell Traefik to use your DNS provider for the DNS challenge. In this example, we are using Cloudflare.
```yaml title="traefik_config.yml" highlight={4,5}
certificatesResolvers:
letsencrypt:
acme:
dnsChallenge:
provider: "cloudflare" # your DNS provider
# see https://doc.traefik.io/traefik/https/acme/#providers
email: "admin@example.com"
storage: "/letsencrypt/acme.json"
caServer: "https://acme-v02.api.letsencrypt.org/directory"
```
</Step>
<Step title="2. Add Wildcard Domains">
Add the domain and wildcard domain to the domains section of the next (front end) router in the dynamic config. This tells Traefik to generate a wildcard certificate for the base domain and all subdomains.
```yaml title="dynamic_config.yml" highlight={9-12}
next-router:
rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)"
service: next-service
entryPoints:
- websecure
tls:
certResolver: letsencrypt
domains:
- main: "example.com"
sans:
- "*.example.com"
```
</Step>
<Step title="3. Add Environment Variables">
Add the environment variables for your DNS provider to the Traefik service in the docker compose file. This allows Traefik to authenticate with your DNS provider to create the DNS records needed for the challenge.
```yaml title="docker-compose.yml" highlight={11-13}
traefik:
image: traefik:v3.4.0
container_name: traefik
restart: unless-stopped
network_mode: service:gerbil
depends_on:
pangolin:
condition: service_healthy
command:
- --configFile=/etc/traefik/traefik_config.yml
# Add the environment variables for your DNS provider.
environment:
CLOUDFLARE_DNS_API_TOKEN: "your-cloudflare-api-token"
volumes:
- ./config/traefik:/etc/traefik:ro
- ./config/letsencrypt:/letsencrypt
```
</Step>
</Steps>
<Warning>
If you're using Cloudflare, make sure your API token has the permissions Zone/Zone/Read and Zone/DNS/Edit and make sure it applies to all zones.
</Warning>
<Info>
Traefik supports most DNS providers. You can find a full list of supported providers and how to configure them in the [Traefik documentation on providers](https://doc.traefik.io/traefik/https/acme/#providers).
</Info>
## Verify it Works
<Tips>
<Tip title="Clear Old Certificates">
You can ensure Traefik doesn't try to use the old certs by deleting the previously used `acme.json` file. This will force Traefik to generate a new certificate on the next start.
</Tip>
</Tips>
<Steps>
<Step title="Start the stack">
Start the stack and watch the logs. You should notice that Traefik is making calls to your DNS provider to create the necessary records to complete the challenge.
</Step>
<Step title="Check logs">
For debugging purposes, you may find it useful to set the log level of Traefik to `debug` in the `traefik_config.yml` file.
</Step>
<Step title="Test new resource">
After Traefik is done waiting for the cert to verify, try to create a new resource with an unused subdomain. Traefik should not try to generate a new certificate, but instead use the wildcard certificate. The domain should also be secured immediately instead of waiting for a new certificate to be generated.
</Step>
<Step title="Verify certificate">
You can also check the volume (in the example above at `config/letsencrypt/`) for the correct certificates. In the `acme.json` file you should see something similar to the following. Note the `*.` in the domain.
</Step>
</Steps>
```json highlight={5}
{
"Certificates": [
{
"domain": {
"main": "*.example.com"
},
"certificate": "...",
"key": "...",
"Store": "default"
}
]
}
```
## Troubleshooting
<AccordionGroup>
<Accordion title="Certificate not generating">
**Problem**: Wildcard certificate not being created.
**Solutions**:
- Verify DNS provider credentials are correct
- Check that API token has proper permissions
- Ensure domain ownership and DNS access
- Review Traefik logs for specific error messages
</Accordion>
<Accordion title="DNS challenge failing">
**Problem**: DNS-01 challenge not completing.
**Solutions**:
- Verify DNS provider is supported by Traefik
- Check API token permissions and scope
- Ensure DNS propagation has completed
- Review provider-specific configuration
</Accordion>
<Accordion title="Old certificates still being used">
**Problem**: Traefik using old HTTP-01 certificates.
**Solution**: Delete the `acme.json` file to force new certificate generation.
</Accordion>
</AccordionGroup>

30
self-host/advanced/without-tunneling.mdx
View File

@@ -1,30 +0,0 @@
---
title: "Without Tunneling"
description: "Use Pangolin as a local reverse proxy without Gerbil tunneling"
---
Use Pangolin as a local reverse proxy and authentication manager
You can use Pangolin without Gerbil and tunneling. In this configuration, Pangolin acts as a normal reverse proxy and authentication manager that can be deployed on your local network to provide access to resources.
<Note>
You can also use "local" sites to expose resources on the same VPS as Pangolin in addition to remote sites.
</Note>
## Setup
### Using the Installer
When asked if you want to install Gerbil for tunneling, select **No**. Gerbil will be removed from the Docker Compose configuration.
### Manual Installation
Follow the [manual install steps](/self-host/manual/docker-compose), but **Gerbil is not required**. Your Docker Compose should not include the Gerbil container.
## How It Works
When Gerbil starts up, it registers itself with Pangolin. By not installing Gerbil, you will only have the option to choose the "Local" connection method. This means Traefik will use the local network to reach your resources.
<Warning>
All setup remains the same, except Pangolin and Traefik must now be on the same network as the resources you want to proxy to.
</Warning>

113
self-host/choosing-a-vps.mdx
View File

@@ -1,113 +0,0 @@
---
title: "Choosing a VPS"
description: "Compare hosting options and find the best VPS for your Pangolin deployment"
---
Pangolin generally requires minimal resources to run effectively. A basic VPS with **1 vCPU, 1GB RAM, and 8GB SSD** is sufficient for most deployments.
<CardGroup cols={2}>
<Card title="Minimum Requirements">
- **CPU**: 1 vCPU
- **RAM**: 1GB
- **Storage**: 8GB SSD
- **Bandwidth**: 1TB/month
</Card>
<Card title="Recommended Specs">
- **CPU**: 2 vCPU
- **RAM**: 2GB
- **Storage**: 20GB SSD
- **Bandwidth**: 2TB/month
</Card>
</CardGroup>
## Recommended Options
<Tip>
We're part of RackNerd's affiliate program. Using our links helps support Pangolin development at no extra cost to you.
</Tip>
<CardGroup cols={2}>
<Card title="RackNerd Starter Plan" href="https://my.racknerd.com/aff.php?aff=13788&pid=912">
**$0.91/month** - Perfect for personal use and small deployments
- 1 vCPU, 1GB RAM, 20GB SSD
- Excellent performance for the price
- Reliable uptime and support
</Card>
<Card title="RackNerd Basic Plan" href="https://my.racknerd.com/aff.php?aff=13788&pid=913">
**$1.47/month** - Ideal for small teams and growing deployments
- 2 vCPU, 2GB RAM, 30GB SSD
- Great value for performance
</Card>
<Card title="RackNerd Standard Plan" href="https://my.racknerd.com/aff.php?aff=13788&pid=914">
**$2.49/month** - Best for larger teams and production use
- 3 vCPU, 3.5GB RAM, 60GB SSD
- Room for growth and scaling
</Card>
</CardGroup>
## VPS Provider Comparison
| Provider | Plan | CPU | RAM | Storage | Price/Month | Price/Year | Best For |
|----------|------|-----|-----|---------|-------------|------------|----------|
| **[RackNerd](https://my.racknerd.com/aff.php?aff=13788)** | Starter | 1 vCPU | 1GB | 20GB SSD | $0.91 | $10.96 | Budget users |
| **[RackNerd](https://my.racknerd.com/aff.php?aff=13788)** | Basic | 2 vCPU | 2GB | 30GB SSD | $1.47 | $17.66 | Small teams |
| **[RackNerd](https://my.racknerd.com/aff.php?aff=13788)** | Standard | 3 vCPU | 3.5GB | 60GB SSD | $2.49 | $29.89 | Growing teams |
| **[Hetzner Cloud](https://www.hetzner.com/cloud)** | CX11 | 2 vCPU | 4GB | 40GB SSD | $4.59 | $55.08 | Performance |
| **[UpCloud](https://upcloud.com/pricing/)** | 1xCPU | 1 vCPU | 1GB | 10GB SSD | $3.30 | $39.60 | European users |
| **[Vultr](https://www.vultr.com/pricing)** | Cloud Compute | 1 vCPU | 1GB | 25GB SSD | $5.00 | $60.00 | Global presence |
| **[Linode](https://www.linode.com/pricing/)** | Nanode | 1 vCPU | 1GB | 25GB SSD | $5.00 | $60.00 | Developer friendly |
| **[DigitalOcean](https://www.digitalocean.com/pricing/droplets)** | Basic | 1 vCPU | 1GB | 25GB SSD | $6.00 | $72.00 | Easy setup |
| **[OVHcloud](https://www.ovhcloud.com/en/vps/)** | Starter | 2 vCPU | 2GB | 40GB SSD | $5.50 | $66.00 | European users |
| **[AWS EC2](https://instances.vantage.sh/)** | t3.micro | 2 vCPU | 1GB | 8GB SSD | $8.50 | $102.00 | Enterprise |
<Info>
Prices shown are approximate and may vary based on location, promotions, and currency exchange rates. Check provider websites for current pricing.
</Info>
## Selection Criteria
When choosing your VPS provider, consider these factors:
<AccordionGroup>
<Accordion title="Performance Requirements">
**Resource usage depends on several key factors:**
**Primary factors:**
- **Number of connected sites**: More sites = higher CPU and memory usage
- **Data throughput**: Amount of traffic transiting through the server
**Secondary factors:**
- **Dashboard UI usage**: Active admin sessions and configuration changes
- **Database activity**: User management, logging, and analytics queries
</Accordion>
<Accordion title="Geographic Location">
**Choose a data center close to your users:**
- **North America**: RackNerd, DigitalOcean, Vultr
- **Europe**: Hetzner, OVHcloud, UpCloud
- **Asia Pacific**: Vultr, Linode, DigitalOcean
- **Global**: AWS, Google Cloud, Azure
</Accordion>
<Accordion title="Support and Reliability">
**Consider these factors:**
- **Uptime guarantees**: Most providers offer 99.9%+
- **Support quality**: 24/7 support vs. community forums
- **Backup options**: Automated backups vs. manual
- **Monitoring**: Built-in monitoring tools
</Accordion>
<Accordion title="Cost Considerations">
**Hidden costs to watch for:**
- **Bandwidth overages**: Most plans include 1-2TB/month
- **Backup storage**: Additional charges for automated backups
- **IPv4 addresses**: Some providers charge extra
- **Support tiers**: Premium support may cost extra
</Accordion>
</AccordionGroup>

205
self-host/community-guides/crowdsec.mdx
View File

@@ -1,205 +0,0 @@
---
title: "CrowdSec"
---
<Note>
This is a community guide and is not officially supported. If you have any issues, please reach out to the [author](https://github.com/Lokowitz).
</Note>
CrowdSec is a modern, open-source, collaborative behavior detection engine, integrated with a global IP reputation network. It functions as a massively multiplayer firewall, analyzing visitor behavior and responding appropriately to various types of attacks.
## Installation
Crowdsec can be installed using the Pangolin Installer.
## Configuration
By default, Crowdsec is installed with a basic configuration, which includes the [Crowdsec Bouncer Traefik plugin](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin).
### Choose the right logs
#### Syslog
For systems utilizing Syslog, the following volumes should be added to the `docker-compose.yml` file:
```yaml
service:
crowdsec:
volumes:
- /var/log/auth.log:/var/log/auth.log:ro
- /var/log/syslog:/var/log/syslog:ro
```
Create a `syslog.yaml` file under `/config/crowdsec/acquis.d` with the following content:
```yaml
filenames:
- /var/log/auth.log
- /var/log/syslog
labels:
type: syslog
```
#### Journalctl
To log iptables to journalctl, execute the following command on your host system:
```bash
iptables -A INPUT -j LOG --log-prefix "iptables: "
```
Update the `docker-compose.yml` file as follows:
```yaml
service:
crowdsec:
image: crowdsecurity/crowdsec:latest-debian
environment:
COLLECTIONS: crowdsecurity/traefik crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules crowdsecurity/linux crowdsecurity/iptables
volumes:
- ./config/crowdsec:/etc/crowdsec
- ./config/crowdsec/db:/var/lib/crowdsec/data
- ./config/traefik/logs:/var/log/traefik:ro
- /var/log/journal:/var/log/host:ro
```
Create a `journalctl.yaml` file under `/config/crowdsec/acquis.d` with the following content:
```yaml
source: journalctl
journalctl_filter:
- "--directory=/var/log/host/"
labels:
type: syslog
```
### Securing the Host System (SSH)
By default, only Traefik requests are secured through the Crowdsec bouncer. To extend protection to your host system (e.g., SSH), follow these steps to add a firewall bouncer:
1. Install the Crowdsec repositories. Refer to the [installation documentation](https://docs.crowdsec.net/docs/next/getting_started/install_crowdsec/#install-our-repositories):
```bash
curl -s https://install.crowdsec.net | sudo sh
```
2. Install the firewall bouncer. For Debian/Ubuntu systems using IPTables, refer to the [documentation](https://docs.crowdsec.net/u/bouncers/firewall/):
```bash
sudo apt install crowdsec-firewall-bouncer-iptables
```
3. Create an API key for the firewall bouncer to communicate with your CrowdSec Docker container. ("vps-firewall" is a placeholder name for the key):
```bash
docker exec -it crowdsec cscli bouncers add vps-firewall
```
4. Copy the dispalyed API key and insert it into the bouncer's configuration file:
```bash
nano /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml
```
5. Restart the firewall bouncer:
```bash
systemctl restart crowdsec-firewall-bouncer
```
6. Update the `docker-compose.yml` file to expose communication port `8080` for the CrowdSec container and restart the container:
```yaml
service:
crowdsec:
ports:
- 6060:6060 # Metrics port
- 8080:8080 # Local API port
```
<Warning>
Docker’s NAT-based port publishing feature automatically exposes all `ports:` defined in the `docker-compose` file on all network interfaces. This behavior can bypass your host firewall settings, potentially exposing services that you did not intend to make public.
Please see [complete warning about exposing ports](/self-host/dns-and-networking).
</Warning>
7. Verify communication between the firewall bouncer and the CrowdSec container by running:
```bash
docker exec crowdsec cscli metrics
```
The output should look like this:
```bash
+------------------------------------------------------------------+
| Local API Bouncers Metrics |
+---------------------------+----------------------+--------+------+
| Bouncer | Route | Method | Hits |
+---------------------------+----------------------+--------+------+
| traefik-bouncer | /v1/decisions/stream | HEAD | 2 |
| traefik-bouncer@10.0.4.20 | /v1/decisions | GET | 3 |
| vps-firewall | /v1/decisions/stream | GET | 84 | <---------
+---------------------------+----------------------+--------+------+
```
## Custom Ban Page
To display a custom ban page to attackers, follow these steps:
1. Place a `ban.html` page in the `/config/traefik` directory. If you prefer not to create your own, you can download the official example:
```bash
wget https://raw.githubusercontent.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/refs/heads/main/ban.html
```
2. Update the `/config/traefik/dynamic_config.yml` file to include the following:
```yaml
http:
middlewares:
crowdsec:
plugin:
crowdsec:
banHTMLFilePath: /etc/traefik/ban.html
```
## Custom Captcha Page
To use a custom captcha page, follow these steps:
1. Place a `captcha.html` page in the `/config/traefik` directory. If you don't want to create your own, you can download the official example:
```bash
wget https://raw.githubusercontent.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/refs/heads/main/captcha.html
```
2. Update the `/config/traefik/dynamic_config.yml` file with the following configuration, replacing `<SERVICE>` with your captcha provider (MUST BE either `hcaptcha`, `recaptcha`, or `turnstile`), and `<KEY>` with the appropriate site and secret keys:
```yaml
http:
middlewares:
crowdsec:
plugin:
crowdsec:
captchaHTMLFilePath: /etc/traefik/captcha.html
captchaGracePeriodSeconds: 300
captchaProvider: <SERVICE>
captchaSiteKey: <KEY>
captchaSecretKey: <KEY>
```
## Testing
You can test your configuration by adding a temporary ban or captcha for your IP. The ban will last for one minute.
To add a ban:
```bash
docker exec crowdsec cscli decisions add --ip <YOUR IP> -d 1m --type ban
```
To trigger a captcha challenge:
```bash
docker exec crowdsec cscli decisions add --ip <YOUR IP> -d 1m --type captcha
```

69
self-host/community-guides/geoblock.mdx
View File

@@ -1,69 +0,0 @@
---
title: "GeoBlock"
---
<Note>
This is a community guide and is not officially supported. If you have any issues, please reach out to the [author](https://github.com/Lokowitz).
</Note>
GeoBlock is a Traefik middleware that uses IP-based geolocation to allow or block traffic from specific countries. It helps enhance security and access control by restricting unwanted or potentially harmful connections based on geographic regions.
## Installation
To integrate GeoBlock into your Traefik setup, follow the steps below:
1. Add the following configuration to your `/config/traefik/traefik_config.yml` file:
```yaml
entryPoints:
websecure:
http:
middlewares:
- geoblock@file
experimental:
plugins:
geoblock:
moduleName: github.com/PascalMinder/geoblock
version: v0.3.2
```
2. Add the following configuration to your `/config/traefik/dynamic_config.yml` file. Setting `blackListMode: false` enables GeoBlock in whitelist mode, allowing only the specified countries. Remember to add the appropriate countries when traveling. A list of country codes can be found in the [documentation](https://github.com/PascalMinder/geoblock#full-plugin-sample-configuration).
```yaml
http:
middlewares:
geoblock:
plugin:
geoblock:
silentStartUp: false
allowLocalRequests: true
logLocalRequests: false # change to true to see logs and verify if it is working
logAllowedRequests: false # change to true to see logs and verify if it is working
logApiRequests: false # change to true to see logs and verify if it is working
api: "https://get.geojs.io/v1/ip/country/{ip}"
apiTimeoutMs: 500
cacheSize: 25
forceMonthlyUpdate: true
allowUnknownCountries: false
unknownCountryApiResponse: "nil"
blackListMode: false
countries:
- DE # add/replace with your country code
```
3. Restart Traefik to apply the changes:
```bash
docker restart traefik
```
## Testing
To monitor GeoBlock activities in the Traefik logs, enable logging by setting the following options to `true`:
```yaml
logLocalRequests: true
logAllowedRequests: true
logApiRequests: true
```

142
self-host/community-guides/homeassistant.mdx
View File

@@ -1,142 +0,0 @@
---
title: "Home Assistant Add-on"
---
<Note>
This is a community add-on and is not officially supported. If you have any issues, please reach out to the [author](https://github.com/Ferdinand99/home-assistant-newt-addon).
</Note>
This Home Assistant add-on allows you to easily run **Newt** directly in Home Assistant. The add-on lets you configure **PANGOLIN_ENDPOINT**, **NEWT_ID**, and **NEWT_SECRET** via the Home Assistant interface.
## Features
- Easy installation via Home Assistant Add-on Store
- Automated setup and execution of the Newt container
- Supports `amd64`, `armv7`, `armhf`, and `aarch64` architectures
- Automatic restart on crash
## Installation
### **1. Add the GitHub Repository as an Add-on Source**
- Go to **Settings → Add-ons → Add-on Store**.
- Click the menu (three dots in the top right) and select **Repositories**.
- Add the following URL:
```
https://github.com/Ferdinand99/home-assistant-newt-addon
```
or
```
https://git.opland.net/Ferdinand99/home-assistant-newt-addon/
```
1. Click **Add** and wait for the repository to load.
### **2. Install and Start the Add-on**
1. Find **Newt Add-on** in the list and click **Install**.
2. Go to the **Configuration** tab and enter your values for:
- **PANGOLIN_ENDPOINT** (e.g., `https://example.com`)
- **NEWT_ID**
- **NEWT_SECRET**
3. Click **Save** and then **Start**.
4. Check the **Logs** tab to verify that everything is running correctly.
## **Configuration**
After installation, you can configure the add-on via the Home Assistant UI:
```yaml
PANGOLIN_ENDPOINT: "https://example.com"
NEWT_ID: "your_newt_id"
NEWT_SECRET: "your_newt_secret"
```
### **Docker Environment Variables**
The following environment variables are passed to the `Newt` container:
- `PANGOLIN_ENDPOINT`
- `NEWT_ID`
- `NEWT_SECRET`
## Exposing Home Assistant through addon
1. Connect addon to your Pangolin by completing environment variables and starting the addon
2. In Pangolin create new HTTP resource for your new Tunnel with subdomain
3. Within the created Resource add new Target Configuration
| Method | IP / Hostname | Port |
| --- | ----------- | --- |
| HTTP | 127.0.0.1 | 8123 |
4. In Home Assistant's `configuration.yaml` add these two sections:
```yaml
http:
use_x_forwarded_for: true
trusted_proxies:
- 127.0.0.1
homeassistant:
allowlist_external_urls:
- "https://<subdomain>.example.com" # <-- Replace with URL of created resource in Pangolin
```
4.5: If you wan't to use SSO Authentication in Pangolin you need to set up the `configuration.yaml` like this:
```
http:
cors_allowed_origins:
- https://google.com
- https://www.home-assistant.io
ip_ban_enabled: true
login_attempts_threshold: 2
use_x_forwarded_for: true
trusted_proxies:
- 127.0.0.1
- Local IP of your NEWT instance
- VPS IP
```
You also need to set up `Resource rules` in the pangolin dashboard. [See rule overview here](/manage/access-control/bypass-rules).
Many thanks to steuerlexi for finding this out!
https://github.com/fosrl/pangolin/issues/757#issuecomment-2903774897
<Note>
Please see [http](https://www.home-assistant.io/integrations/http/) documentation and [allowlist_external_urls](https://www.home-assistant.io/integrations/homeassistant/#external_url) on Home Assistant site.
</Note>
5. Restart Home Assistant and your new Pangolin Proxy should be alive
## Troubleshooting
#### **Add-on does not start?**
- Check the logs in Home Assistant (`Settings → Add-ons → Newt → Logs`).
- Ensure that `PANGOLIN_ENDPOINT`, `NEWT_ID`, and `NEWT_SECRET` are set correctly.
#### **Changes in configuration do not take effect?**
- Restart the add-on after making changes.
- Try removing the container manually:
```shell
docker stop newt
docker rm newt
```
- Then start the add-on again.
#### **Docker not available?**
- Home Assistant OS manages Docker automatically, but check if the system has access to Docker by running:
```shell
docker info
```
If this fails, there may be a restriction in Home Assistant OS.
## Useful Links
- [HA addon repo](https://github.com/Ferdinand99/home-assistant-newt-addon)
- [Home Assistant](https://www.home-assistant.io/)
- [Docker Docs](https://docs.docker.com/)

200
self-host/community-guides/metrics.mdx
View File

@@ -1,200 +0,0 @@
---
title: "Metrics"
---
<Note>
This is a community guide and is not officially supported. If you have any issues, please reach out to the [author](https://github.com/Lokowitz).
</Note>
This is a basic example of collecting metrics from Traefik and CrowdSec using Prometheus and visualizing them with Grafana dashboards.
<Warning>
Important for users with low-powered server (1GB RAM):
This setup will increase the use of your server RAM.
</Warning>
## Configuration
### Traefik
For claiming metrics from Traefik we have to adjust some configuration files.
1. Udpate the `docker-compose.yml` file of the Pangolin stack to expose metrics port `8082` for the Prometheus connection:
```yaml
service:
gerbil:
ports:
- 8082:8082
```
<Warning>
Docker’s NAT-based port publishing feature automatically exposes all `ports:` defined in `docker-compose` file. This behavior can bypass your host firewall settings, potentially exposing services that you did not intend to make public.
Please see [complete warning about exposing ports](/self-host/dns-and-networking).
</Warning>
2. Update the `/config/traefik/traefik_config.yml` file to include the following:
```yaml
entryPoints:
metrics:
address: ":8082"
metrics:
prometheus:
buckets:
- 0.1
- 0.3
- 1.2
- 5.0
entryPoint: metrics
addEntryPointsLabels: true
addRoutersLabels: true
addServicesLabels: true
```
3. Restart the Gerbil and Traefik container to apply the changes:
```bash
sudo docker restart traefik gerbil
```
### Crowdsec
For claiming metrics from Crowdsec we have to adjust the docker compose files.
1. Udpate the `docker-compose.yml` file of the Pangolin stack to expose metrics port `6060` for the Prometheus connection:
```yaml
service:
crowdsec:
ports:
- 6060:6060
```
<Warning>
Docker’s NAT-based port publishing feature automatically exposes all `ports:` defined in the `docker-compose` file on all network interfaces. This behavior can bypass your host firewall settings, potentially exposing services that you did not intend to make public.
Please see [complete warning about exposing ports](/self-host/dns-and-networking).
</Warning>
2. Restart the Crowdsec container to apply the changes:
```bash
sudo docker restart crowdsec
```
## Prometheus
1. Create a new Prometheus container or add it to `docker-compose.yml` of Pangolin stack:
```yaml
services:
prometheus:
container_name: prometheus
image: prom/prometheus:latest
restart: unless-stopped
ports:
- 9090:9090
volumes:
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
- ./config/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
- ./config/prometheus/data:/prometheus
```
<Warning>
Docker’s NAT-based port publishing feature automatically exposes all `ports:` defined in the `docker-compose` file on all network interfaces. This behavior can bypass your host firewall settings, potentially exposing services that you did not intend to make public.
Please see [complete warning about exposing ports](/self-host/dns-and-networking).
</Warning>
2. Create a `prometheus.yml` file in the `/config/prometheus` directory with the following content:
```yaml
global:
scrape_interval: 15s
evaluation_interval: 15s
scrape_configs:
- job_name: "prometheus"
static_configs:
- targets: ["localhost:9090"]
- job_name: traefik
static_configs:
- targets: ["172.17.0.1:8082"]
- job_name: crowdsec
static_configs:
- targets: ["172.17.0.1:6060"]
```
3. Create a folder `data` in `/config/prometheus` and change the ower and owning group:
```bash
chown nobody:nogroup data
```
4. Start the Prometheus container:
```bash
sudo docker conpose up -d
```
## Grafana
1. Create a new Grafana container or add it to `docker-compose.yml` of Pangolin stack:
```yaml
services:
grafana:
image: grafana/grafana:latest
container_name: grafana
restart: unless-stopped
ports:
- 3000:3000
volumes:
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
- ./config/grafana/data:/var/lib/grafana
```
<Warning>
Docker’s NAT-based port publishing feature automatically exposes all `ports:` defined in the `docker-compose` file on all network interfaces. This behavior can bypass your host firewall settings, potentially exposing services that you did not intend to make public.
Please see [complete warning about exposing ports](/self-host/dns-and-networking).
</Warning>
2. Start the Grafana container:
```bash
sudo docker compose up -d
```
<Note>
Default login credentials for Grafana admin user is admin:admin.
</Note>
### Add Prometheus Connection
Add the Prometheus connection under Connections -> Add new connection.
Set `http://172.17.0.1:9090` as `Prometheus Server URL` and click `Save & test`.
### Add Dashboard
Add a Dashboard under Dashboard -> New -> Import and import a pre configured Dashboard or create your own.
#### Traefik
<Frame caption="Traefik Dashboard">
<img src="/images/traefik_dashboard.png" alt="Traefik Dashboard"/>
</Frame>
Template Import ID = 17346
https://grafana.com/grafana/dashboards/17346-traefik-official-standalone-dashboard/
#### Crowdsec
https://github.com/crowdsecurity/grafana-dashboards/tree/master

171
self-host/community-guides/middlewaremanager.mdx
View File

@@ -1,171 +0,0 @@
---
title: "Middleware Manager"
---
<Note>
This is a community guide and not officially supported. For issues, contributions, or bug reports, please use the [official GitHub repository](https://github.com/hhftechnology/middleware-manager).
</Note>
## What is Middleware Manager?
The **Middleware Manager** is a microservice that extends your existing traefik deployments.
It provides a **web UI** to attach Traefik middlewares to resources without editing Pangolin itself.
:warning: **Security Warning**
Middlewares can strengthen security but also create vulnerabilities if misconfigured.
* Test in staging before production.
* Misusing forward authentication can leak credentials.
* Bad rate limiter configs may be bypassed.
* Header misconfigurations can expose apps to XSS/CSRF.
* Stacking too many middlewares impacts performance.
* Always check provider references (`@http` vs `@file`).
---
### Key Use Cases
* External authentication (Authelia, Authentik, JWT)
* Security headers and CSP policies
* Geographic IP blocking
* Rate limiting / DDoS protection
* Redirects & path rewrites
* CrowdSec and other security tool integrations
---
## Prerequisites
* A running **Pangolin v1.0.0+**
* Docker + Docker Compose
* Basic Traefik knowledge
* Admin access to your Pangolin host
---
## Step 1: Add Middleware Manager Service
Update your `docker-compose.yml`:
```yaml
middleware-manager:
image: hhftechnology/middleware-manager:latest
container_name: middleware-manager
restart: unless-stopped
volumes:
- ./data:/data
- ./config/traefik/rules:/conf
- ./config/middleware-manager/templates.yaml:/app/config/templates.yaml # Optional custom templates
environment:
- PANGOLIN_API_URL=http://pangolin:3001/api/v1
- TRAEFIK_CONF_DIR=/conf
- DB_PATH=/data/middleware.db
- PORT=3456
ports:
- "3456:3456"
````
---
## Step 2: Create Required Directories
```bash
mkdir -p ./config/traefik/rules
mkdir -p ./config/middleware-manager
```
Move any dynamic configs into `./config/traefik/rules`.
---
## Step 3: Update Traefik Volumes & Providers
In your `traefik` service:
```yaml
volumes:
- ./config/traefik:/etc/traefik:ro
- ./config/letsencrypt:/letsencrypt
- ./config/traefik/logs:/var/log/traefik
- ./config/traefik/rules:/rules # required
```
In `traefik_config.yml`:
```yaml
providers:
file:
directory: "/rules"
watch: true
```
---
## Step 4: Start Services
```bash
docker compose up -d
```
---
## Step 5: Access the UI
Middleware Manager runs at:
👉 [http://localhost:3456](http://localhost:3456)
---
## Common Middleware Examples
### Rate Limiting
```yaml
middlewares:
- id: "rate-limit"
type: "rateLimit"
config:
average: 100
burst: 50
```
### Security Headers
```yaml
middlewares:
- id: "security-headers"
type: "headers"
config:
customResponseHeaders:
Server: ""
X-Powered-By: ""
browserXSSFilter: true
contentTypeNosniff: true
forceSTSHeader: true
stsSeconds: 63072000
```
---
## Troubleshooting
* **Service does not exist** → Check `@http` or `@file` suffix in references
* **Middleware does not exist** → Verify config and required plugins
* **No changes applied** → Check Traefik logs, middleware priority, restart services
* **UI not showing resources** → Confirm `PANGOLIN_API_URL` and network connectivity
* **Database errors** → Check `./data` permissions, or reset `middleware.db`
* **CrowdSec errors → Ensure the crowdsec container is running; middlewares fail if the service is down.
* **Protecting Pangolin itself** → Apply middlewares (e.g. geoblock, headers) directly on the websecure entryPoint to cover all traffic.
* **Applying to many services** → Attach middleware to entryPoints instead of individual resources to cover all subdomains at once.
* **TCP / SMTP with STARTTLS** → Not supported. Traefik cannot handle STARTTLS negotiation (only implicit TLS like SMTPS on 465).
---
## Final Notes
The Middleware Manager gives you a UI to work with Traefik’s powerful middleware ecosystem.
* Start with simple configs → test thoroughly → expand gradually.
* Use templates where possible.
* Always validate in staging before production.

72
self-host/community-guides/overview.mdx
View File

@@ -1,72 +0,0 @@
---
title: "Overview"
---
<Note>
These are community written guides and are not officially supported. If you have any issues, please reach out to the authors or the community on [Discord](https://digpangolin.com/discord) or [Github discussions](https://github.com/orgs/fosrl/discussions).
</Note>
The modular design of this system enables the extension of its functionality through the integration of existing Traefik plugins, such as Crowdsec and Geoblock.
Additionally, Prometheus can collect metrics from both CrowdSec and Traefik, which can then be visualized in Grafana to monitor security events, request statistics, and traffic patterns in real time.
## Traefik plugins
For a complete list of available plugins, please refer to the [Plugin Catalog](https://plugins.traefik.io/plugins).
### Crowdsec Bouncer
When installing Crowdsec via the Pangolin installer, the Crowdsec Traefik Bouncer will be automatically installed and configured by default. The configuration can be customized to meet your specific requirements.
The CrowdSec Bouncer plugin for Traefik integrates CrowdSec’s security engine to block malicious traffic in real time. It runs as middleware within a Traefik container and enforces decisions based on CrowdSec’s threat intelligence. This helps protect services from bots, attackers, and abusive IPs dynamically.
For additional information, consult the following resources:
- [Traefik Plugin Catalog](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin)
- [Github Repository](https://github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin)
### Geoblock
The GeoBlock plugin for Traefik is a middleware that restricts access based on the client’s geographic location. It runs within a Traefik container and uses IP-based geolocation to allow or block traffic from specific countries. This is useful for security, compliance, or access control in Traefik-managed services.
For more details, please refer to the following resources:
- [Github Repository](https://github.com/PascalMinder/geoblock)
### Middleware Manager
The Middlware manager is a microservice that allows you to add custom middleware to Pangolin / Traefik resources.
For more details, please refer to the following resources:
- [Github Repository](https://github.com/hhftechnology/middleware-manager)
## Metrics
Currently you can claim metric data from Traefik and Crowdsec with Prometheus and visiulize it within a Grafana Dashboard.
### Prometheus
Prometheus is an open-source monitoring and alerting toolkit designed for collecting and querying time-series metrics. It runs as a Docker container and uses a pull-based model to scrape data from configured endpoints. Prometheus integrates well with Grafana for visualization and Alertmanager for alert handling.
For more details, please refer to the following resources:
- [Homepage](https://prometheus.io/)
- [Github Repository](https://github.com/prometheus/prometheus)
### Grafana
Grafana is an open-source analytics and visualization platform used to monitor and display time-series data. It runs as a Docker container and supports multiple data sources, including Prometheus, InfluxDB, and MySQL. Grafana provides interactive dashboards, alerting, and extensive customization options for data visualization.
For more details, please refer to the following resources:
- [Homepage](https://grafana.com/)
- [Github Repository](https://github.com/grafana/grafana)
### Traefik Logs Dashboard
The Traefik Logs Dashboard is a real-time dashboard for analyzing Traefik logs with IP geolocation, status code analysis, and service metrics.
For more details, please refer to the following resources:
- [Github Repository](https://github.com/hhftechnology/traefik-log-dashboard)

162
self-host/community-guides/proxyprotocol.mdx
View File

@@ -1,162 +0,0 @@
---
title: "Proxy Protocol"
description: "Using Proxy Protocol to Preserve Client IPs for TCP/UDP backends"
---
Did you ever want to get the real ip instead of newt's IP or traefik's IP for TCP/UDP applications? Then follow below, Just be warned this is not a begineer guide.
This guide shows how to enable Proxy Protocol manually until a GUI option becomes available.
⚠️ It’s an advanced setup, so you’ll be editing configuration files and running cli commands. ⚠️
In Pangolin, make a TCP resource or UDP resource.
> **Note:** Not all applications support Proxy Protocol. If you send Proxy Protocol headers to an application that isn't configured for it or doesn't support it, the connection will fail entirely.
---
## Creating the Resource
In Pangolin, go into **Resources** and create a TCP or UDP route like you normally would — pointing it to your resource which accepts Proxy Protocol.
Say I'm using `tcp-8888` with Pangolin.
I configure it to hit my Proxy Protocol–enabled service such as Minecraft Paper or Velocity.
It'll give you a **port** to put into the compose file and an **entryPoint** to add into the `traefik_config.yml`.
Only do the second, not the first.
---
## Add the EntryPoint
Add an entrypoint in `traefik_config.yml` for the port you intend to use.
```yaml
entryPoints:
tcp-22000:
address: ":22000/tcp"
```
I'm going to use `tcp-22000` for this, and in Traefik under **Gerbil**, I'm going to add the same mapping:
```yaml
gerbil:
image: fosrl/gerbil
container_name: gerbil
restart: unless-stopped
ports:
- 51820:51820/udp
- 21820:21820/udp
- 443:443/tcp
- 80:80/tcp
- 22000:22000/tcp
```
---
## Find the Service Address
Run the following command:
```bash
docker exec pangolin curl http://localhost:3001/api/v1/traefik-config | jq
```
Look for the entry that resembles:
```json
"tcp": {
"routers": {
"43-router": {
"entryPoints": [
"tcp-8888"
],
"service": "43-service",
"rule": "HostSNI(`*`)"
```
Follow this down further until you reach the service line — `43-service` in this example:
```json
"services": {
"43-service": {
"loadBalancer": {
"servers": [
{
"address": "100.89.128.4:58655"
}
]
}
},
```
Make a note of the address there.
---
## Update Dynamic Configuration
Go into `config/traefik_dynamic.yml` and add:
### TCP Example
```yaml
tcp:
routers:
minecraft-rtr:
rule: "HostSNI(`*`)"
entryPoints:
- "tcp-22000"
service: minecraft-svc
services:
minecraft-svc:
loadBalancer:
serversTransport: proxy-protocol-v1 # Can be named anything really as long as it matches the defined transport.
servers:
- address: "100.89.128.4:58655"
serversTransports:
proxy-protocol-v1:
proxyProtocol:
version: 1 # Velocity can handle v2 also but in in doubt use version over version 2.
```
### UDP Example
```yaml
udp:
routers:
servicename-rtr:
entryPoints:
- "udp-22000"
service: servicename-svc
services:
servicename-svc:
loadBalancer:
serversTransport: proxyprotocol-udp
servers:
- address: "100.89.128.4:58655"
serversTransports:
proxyprotocol-udp:
proxyProtocol:
version: 1
```
---
Also do note.. If you change the dummy (8888) info at all for the destination or the port or the site.. you will need to repopulate the info all over again. Starting from the JQ line above.
---
## Downstream Applications
For downstream applications, you'll need to configure them to trust Proxy Protocol connections originating from the system where **Newt** connects to the service.
For example:
If the Newt is running on **Host B** at `192.168.1.5`,
your service on **Host A** at `192.168.1.4` needs to trust `192.168.1.5` as a trusted Proxy Protocol source.
Once Proxy Protocol is in play, the connection between Traefik and the backend **must** speak Proxy Protocol — otherwise it will refuse to connect.

216
self-host/community-guides/traefiklogsdashboard.mdx
View File

@@ -1,216 +0,0 @@
---
title: "Traefik Log Dashboard"
---
<Note>
This is a community guide and is not officially supported. For issues or advanced configuration, please visit the [official repository](https://github.com/hhftechnology/traefik-log-dashboard).
</Note>
If you’re already using the **Pangolin stack with Traefik as your reverse proxy**, you have powerful routing in place. But raw log files and scattered metrics make it difficult to truly understand traffic patterns.
The **Enhanced Traefik Log Dashboard** adds **real-time monitoring, OpenTelemetry support, and geolocation analytics**, giving you a full picture of your traffic.
## Features
* **OpenTelemetry OTLP Support**: Real-time traces from Traefik v3+
* **Hybrid Monitoring**: Combine OTLP traces with traditional log parsing
* **Geolocation**: MaxMind GeoIP integration with automatic updates
* **Analytics**: Live request rates, response times, error tracking
* **Production Ready**: Resource limits, health checks, optimized GC/memory
## Prerequisites
* Docker + Docker Compose
* Traefik v3.0+ (for OTLP) or v2.x (logs only)
* A working Pangolin stack
## Step 1: Configure Traefik
### For OTLP + Logs (Recommended)
Update `./config/traefik/traefik_config.yml`:
```yaml
log:
level: INFO
filePath: "/var/log/traefik/traefik.log"
format: json
accessLog:
filePath: "/var/log/traefik/access.log"
format: json
tracing:
otlp:
http:
endpoint: "http://log-dashboard-backend:4318/v1/traces"
sampleRate: 0.1 # Adjust as needed - 0.1 for 10% sampling
globalAttributes:
environment: "production"
service.version: "v3.0"
deployment.environment: "pangolin"
```
### For Logs Only
```yaml
log:
level: INFO
filePath: "/var/log/traefik/traefik.log"
accessLog:
filePath: "/var/log/traefik/access.log"
format: json
```
## Step 2: Add Dashboard Services
Extend your existing `docker-compose.yml` with:
```yaml
log-dashboard-backend:
image: ghcr.io/hhftechnology/traefik-log-dashboard-backend:latest
container_name: log-dashboard-backend
restart: unless-stopped
ports:
- "4317:4317" # OTLP gRPC
- "4318:4318" # OTLP HTTP
volumes:
- ./config/traefik/logs:/logs:ro
- ./config/maxmind:/maxmind:ro
environment:
- PORT=3001
- TRAEFIK_LOG_FILE=/logs/access.log
- OTLP_ENABLED=true
- OTLP_GRPC_PORT=4317
- OTLP_HTTP_PORT=4318
- USE_MAXMIND=true
- MAXMIND_DB_PATH=/maxmind/GeoLite2-City.mmdb
- MAXMIND_FALLBACK_ONLINE=true
- GOGC=50
- GOMEMLIMIT=500MiB
log-dashboard-frontend:
image: ghcr.io/hhftechnology/traefik-log-dashboard-frontend:latest
container_name: log-dashboard-frontend
restart: unless-stopped
ports:
- "3000:80"
environment:
- BACKEND_SERVICE=log-dashboard-backend
- BACKEND_PORT=3001
depends_on:
- log-dashboard-backend
```
## Step 3: Setup MaxMind GeoIP (Optional but Recommended)
1. Create a free MaxMind account → [GeoLite2 signup](https://www.maxmind.com/en/geolite2/signup)
2. Generate a license key
3. Create directory:
```bash
mkdir -p ./config/maxmind
export MAXMIND_LICENSE_KEY=your_key_here
```
4. (Optional) Add updater service:
```yaml
maxmind-updater:
image: alpine:latest
container_name: maxmind-db-updater
volumes:
- ./config/maxmind:/data
environment:
- MAXMIND_LICENSE_KEY=${MAXMIND_LICENSE_KEY}
command: >
sh -c "
apk add --no-cache wget tar &&
cd /data &&
wget -O GeoLite2-City.tar.gz 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=$MAXMIND_LICENSE_KEY&suffix=tar.gz' &&
tar -xzf GeoLite2-City.tar.gz --strip-components=1 '*/GeoLite2-City.mmdb' &&
rm -f GeoLite2-City.tar.gz
"
```
## Step 4: Launch Stack
```bash
docker compose up -d
docker compose ps
```
## Step 5: Access the Dashboard
* **Frontend UI** → [http://localhost:3000](http://localhost:3000)
## Key Features
* **Real-time statistics** (requests, response times, error rates)
* **Interactive world map** (request origins via MaxMind)
* **Service insights** (performance by router/service)
* **Hybrid monitoring** (OTLP + logs together)
## Performance Tuning
For production or high-traffic environments, you may want to adjust settings to optimize resource usage and throughput.
### Reduce OTLP Sampling
Lower sampling to avoid overwhelming storage and dashboards:
```yaml
tracing:
sampleRate: 0.1 # 10% sampling in production
````
### Prefer gRPC over HTTP
For lower latency and higher throughput, enable gRPC instead of HTTP:
```yaml
tracing:
otlp:
grpc:
endpoint: "log-dashboard-backend:4317"
insecure: true
```
### Tune Backend Memory
Set environment variables in `log-dashboard-backend`:
```yaml
environment:
- GOGC=20 # More aggressive garbage collection
- GOMEMLIMIT=1GiB # Hard memory limit
```
### Resource Limits
Add CPU and memory constraints to containers:
```yaml
deploy:
resources:
limits:
cpus: "1.0"
memory: 512M
reservations:
cpus: "0.2"
memory: 128M
```
These adjustments help keep the dashboard responsive while minimizing resource overhead.
## Troubleshooting
* **OTLP not showing** → Check Traefik `tracing` config + ports `4317/4318`
* **Logs not loading** → Ensure Traefik logs in JSON, volume mounted correctly
* **GeoIP errors** → Verify `MAXMIND_LICENSE_KEY` and DB path
* **Maxmind download errors** → Check license key validity by trying url with key directly in your browser
* **Docker logs for Traefik not showing** → Use `docker exec -it traefik tail -f /var/log/traefik/traefik.log` instead of `docker logs traefik -f` to see real-time logs on the command line.
---

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

@@ -1,124 +0,0 @@
---
title: "Convert to Managed"
description: "Learn how to convert your Community Edition Pangolin instance to a managed self-hosted node for free"
---
<Info>
Check out the [Managed Deployment Guide](/self-host/quick-install-managed) 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 node. 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>

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

@@ -1,212 +0,0 @@
---
title: "DNS & Networking"
description: "Configure your domain, DNS records, and network settings for Pangolin deployment"
---
Pangolin requires proper DNS configuration and network setup to function correctly. This guide covers domain setup, DNS records, port configuration, and networking considerations.
## DNS Configuration
### Basic DNS Records
You'll need to create A (or AAAA for IPv6) records pointing to your VPS IP address.
<Steps>
<Step title="Create wildcard record">
Create a wildcard subdomain record for your domain:
```
Type: A
Name: *
Value: YOUR_VPS_IP_ADDRESS
TTL: 300 (or default)
```
<Check>
This allows any subdomain (e.g., `app.example.com`, `api.example.com`) to resolve to your VPS.
</Check>
</Step>
<Step title="Create root domain record (optional)">
If you plan to use your root domain as a resource:
```
Type: A
Name: @ (or leave blank)
Value: YOUR_VPS_IP_ADDRESS
TTL: 300 (or default)
```
<Info>
This is only needed if you want to use `example.com` (not just subdomains) as a resource.
</Info>
</Step>
<Step title="Wait for propagation">
DNS changes can take 5 minutes to 48 hours to propagate globally.
<Tip>
Use Google DNS (8.8.8.8) or your provider's DNS to test changes faster.
</Tip>
</Step>
</Steps>
## Port Configuration
### Required Ports
Pangolin requires these ports to be open on your VPS:
<CardGroup cols={2}>
<Card title="TCP Port 80">
**HTTP/SSL Verification**
- Let's Encrypt domain validation
- Non-SSL resources
- Can be disabled with wildcard certs
</Card>
<Card title="TCP Port 443">
**HTTPS Traffic**
- Pangolin web dashboard
- SSL-secured resources
- Essential for operation
</Card>
<Card title="UDP Port 51820">
**Site Tunnels**
This is the default port for sites (Newt) to establish tunnels to the proxy (Gerbil).
</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:
```yaml
gerbil:
ports:
- "80:80" # HTTP/SSL verification and non-SSL resources
- "443:443" # HTTPS for web UI and SSL resources
- "51820:51820" # WireGuard for Newt connections
- "21820:21820" # WireGuard for client connections
```
### Firewall Configuration
Ensure your VPS firewall allows these ports:
<Tabs>
<Tab title="Cloud Provider">
Configure security groups/firewall rules in your cloud provider's dashboard to allow:
- TCP ports 80 and 443
- UDP ports 51820 and 21820
</Tab>
<Tab title="UFW (Ubuntu)">
```bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 51820/udp
sudo ufw allow 21820/udp
sudo ufw enable
```
</Tab>
<Tab title="firewalld (CentOS/RHEL)">
```bash
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=51820/udp
sudo firewall-cmd --permanent --add-port=21820/udp
sudo firewall-cmd --reload
```
</Tab>
</Tabs>
## Internal Network Configuration
### Default Subnet Settings
Pangolin uses these default network settings:
```yaml
gerbil:
block_size: 24
site_block_size: 30
subnet_group: 100.89.137.0/20
```
**What this means:**
- **Gerbil network**: Uses first /24 subnet in `100.89.137.0/20` range
- **Site allocation**: Each site gets a /30 subnet (4 IPs)
- **CGNAT range**: Avoids conflicts with most private networks
<Info>
The `100.89.137.0/20` range is in the CGNAT (Carrier-Grade NAT) space, which should avoid conflicts with typical private networks (192.168.x.x, 10.x.x.x, 172.16-31.x.x).
</Info>
<Warning>
**Important**: If this subnet conflicts with your network, change it in your config **before** registering your first Gerbil.
</Warning>
### Customizing Network Settings
If you need to change the default network:
```yaml
gerbil:
block_size: 24 # Size of Gerbil's network block
site_block_size: 30 # Size of each site's network block
subnet_group: 10.0.0.0/8 # Custom subnet range
start_port: 51820 # WireGuard server port
```
<Tip>
For heavy WireGuard usage, consider increasing `site_block_size` to 29 (8 IPs) or 28 (16 IPs) per site.
</Tip>
## Docker Networking
### Local Services
When deploying services in Docker alongside Pangolin:
<AccordionGroup>
<Accordion title="Container Communication">
**For services in the same Docker Compose:**
- Use service names as hostnames
- Example: `http://pangolin:8080`
- Docker Compose creates internal network automatically
</Accordion>
<Accordion title="Host Machine Access">
**To access services on the host machine:**
- Use `172.17.0.1` (Docker bridge gateway)
- Or use `host.docker.internal` (Docker Desktop)
- Example: `http://172.17.0.1:3000`
</Accordion>
<Accordion title="External Services">
**For services outside Docker:**
- Use the host's public IP address
- Ensure firewall allows the required ports
- Consider using VPN or secure tunnels
</Accordion>
</AccordionGroup>

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

@@ -1,111 +0,0 @@
---
title: "How to Update"
description: "Keep your Pangolin deployment 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.
## Before You Update
<Warning>
**Always backup your data before updating.** Copy your `config` directory to a safe location so you can roll back if needed.
</Warning>
<Tip>
**Recommended**: Update incrementally between major versions. For example, update from 1.0.0 → 1.1.0 → 1.2.0 instead of jumping directly from 1.0.0 → 1.2.0.
</Tip>
## Update Process
<Steps>
<Step title="Stop the stack">
Stop all running containers:
```bash
sudo docker compose down
```
</Step>
<Step title="Check latest versions">
Find the latest version numbers:
- **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).
</Info>
</Step>
<Step title="Update version numbers">
Edit your `docker-compose.yml` file and update the image versions:
```yaml title="docker-compose.yml"
services:
pangolin:
image: fosrl/pangolin:1.7.3 # Update to latest version
# ... rest of config
gerbil:
image: fosrl/gerbil:1.2.1 # Update to latest version
# ... rest of config
traefik:
image: traefik:v3.4.0 # Update if needed
# ... rest of config
```
Increase the Badger version number in `config/traefik/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.
</Warning>
</Step>
<Step title="Pull new images">
Download the updated Docker images:
```bash
sudo docker compose pull
```
</Step>
<Step title="Start the stack">
Start the updated containers:
```bash
sudo docker compose up -d
```
</Step>
<Step title="Monitor the update">
Watch the logs to ensure everything starts correctly:
```bash
sudo docker compose logs -f
```
</Step>
<Step title="Verify functionality">
Test that everything is working:
1. Access your Pangolin dashboard
2. Check that all sites are accessible
3. Verify tunnel connections (if using Gerbil)
4. Test any custom configurations
<Check>
If everything works, your update is complete!
</Check>
</Step>
</Steps>

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

@@ -1,319 +0,0 @@
---
title: "Docker Compose"
description: "Deploy Pangolin manually using Docker Compose without the automated installer"
---
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) 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
│ ├── letsencrypt/
│ │ └── acme.json
│ ├── logs/
│ └── traefik/
│ ├── traefik_config.yml (*)
│ └── dynamic_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](/self-host/advanced/config-file) for details
**`config/traefik/traefik_config.yml`**: Traefik static configuration
- Global Traefik settings and entry points
- SSL certificate resolver configuration
**`config/traefik/dynamic_config.yml`**: Traefik dynamic configuration
- HTTP routers and services for Pangolin
- Load balancer and middleware configuration
</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
**`config/letsencrypt/acme.json`**: SSL certificate storage
- Managed by Traefik
- Contains Let's Encrypt certificates
</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 config/letsencrypt config/logs
```
</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/traefik/dynamic_config.yml`
- `config/config.yml`
</Step>
<Step title="Update domain and email">
Edit the configuration files to replace:
- `pangolin.example.com` with your actual domain
- `admin@example.com` with your email address
<Warning>
Ensure your domain DNS is properly configured to point to your server's IP address.
</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>
<Step title="Access the dashboard">
Navigate to `https://your-domain.com/auth/initial-setup` to complete the initial setup.
<Check>
The dashboard should load with SSL certificate automatically configured.
</Check>
</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:443 # Port for traefik because of the network_mode
- 80:80 # Port for traefik because of the network_mode
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:
http:
endpoint: "http://pangolin:3001/api/v1/traefik-config"
pollInterval: "5s"
file:
filename: "/etc/traefik/dynamic_config.yml"
experimental:
plugins:
badger:
moduleName: "github.com/fosrl/badger"
version: "v1.2.0"
log:
level: "INFO"
format: "common"
certificatesResolvers:
letsencrypt:
acme:
httpChallenge:
entryPoint: web
email: admin@example.com # REPLACE WITH YOUR EMAIL
storage: "/letsencrypt/acme.json"
caServer: "https://acme-v02.api.letsencrypt.org/directory"
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
transport:
respondingTimeouts:
readTimeout: "30m"
http:
tls:
certResolver: "letsencrypt"
serversTransport:
insecureSkipVerify: true
ping:
entryPoint: "web"
```
## Traefik Dynamic Configuration
Create `config/traefik/dynamic_config.yml`:
```yaml title="config/traefik/dynamic_config.yml"
http:
middlewares:
redirect-to-https:
redirectScheme:
scheme: https
routers:
# HTTP to HTTPS redirect router
main-app-router-redirect:
rule: "Host(`pangolin.example.com`)" # REPLACE WITH YOUR DOMAIN
service: next-service
entryPoints:
- web
middlewares:
- redirect-to-https
# Next.js router (handles everything except API and WebSocket paths)
next-router:
rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)" # REPLACE WITH YOUR DOMAIN
service: next-service
entryPoints:
- websecure
tls:
certResolver: letsencrypt
# API router (handles /api/v1 paths)
api-router:
rule: "Host(`pangolin.example.com`) && PathPrefix(`/api/v1`)" # REPLACE WITH YOUR DOMAIN
service: api-service
entryPoints:
- websecure
tls:
certResolver: letsencrypt
# WebSocket router
ws-router:
rule: "Host(`pangolin.example.com`)" # REPLACE WITH YOUR DOMAIN
service: api-service
entryPoints:
- websecure
tls:
certResolver: letsencrypt
services:
next-service:
loadBalancer:
servers:
- url: "http://pangolin:3002" # Next.js server
api-service:
loadBalancer:
servers:
- url: "http://pangolin:3000" # API/WebSocket server
```
## Pangolin Configuration
Create `config/config.yml` with your Pangolin settings. See the [configuration guide](/self-host/advanced/config-file) for detailed options and examples.

238
self-host/manual/managed.mdx
View File

@@ -1,238 +0,0 @@
---
title: "Docker Compose"
description: "Deploy managed Pangolin manually using Docker Compose without the automated installer"
---
<Tip>
This guide is for managed self-hosted Pangolin. If you are looking for self-hosted Community Edition Pangolin please see this [Docker Compose](/self-host/manual/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](/self-host/advanced/config-file) 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 node
<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"
proxyProtocol:
trustedIPs:
- 0.0.0.0/0
- ::1/128
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"
```

381
self-host/manual/unraid.mdx
View File

@@ -1,381 +0,0 @@
---
title: "Unraid Deployment"
description: "Deploy Pangolin on Unraid for local reverse proxy and tunneling"
---
## Overview
This guide explains how to use Pangolin and Traefik as a local reverse proxy without Gerbil and its tunneling features. The second (optional) part will expand on this and show how to enable tunneling by setting up Gerbil.
All containers are available in the Unraid Community Apps (CA) store. If you're not familiar with Unraid, you can find more information on their [website](https://unraid.net/).
This installation has a lot of moving parts and is a bit non-standard for Unraid because Pangolin and its components were designed to run as micro-services on a VPS in tunneling mode. However, some may want to use "Local" reverse proxying on their Unraid server or use their Unraid server as a tunnel controller with Gerbil. For either of these use cases, follow the steps outlined in this guide.
## Prerequisites
- A working Unraid server.
- A domain name with access to configure DNS and the ability to port forward on your network.
- The networking is the same as for the VPS, just on your local network, so please refer to [networking page](/self-host/dns-and-networking) for more info.
## Create a Docker Network
Before starting, create a new docker network on Unraid. This will simplify things, and allow the containers to communicate with each other via their container names. If you already have a network, there is no need to create another one.
1. Open the web terminal in Unraid.
2. Run the following command:
<Info>
You can use any name you want for the network. We will use `mynetwork` in this guide.
</Info>
```bash
docker network create mynetwork
```
For more info on this, see this [tutorial by IBRACORP](https://www.youtube.com/watch?v=7fzBDCI8O2w).
## 1. Setup Pangolin and Traefik
This first part will enable Pangolin to work in "Local" reverse proxy mode. Newt and WireGuard will **not** be able to be used after finishing this first part. However, if you want to use those features, you still need to follow this first part of the tutorial because we show how to set up Pangolin and Traefik first.
### Install and Setup Pangolin
#### 1. Create the Config Files
Pangolin uses a yaml file for configuration. If this is not present on start up, the container will throw an error and exit.
Create a `config.yml` file in the `config` folder.
See the [Configuration](/self-host/advanced/config-file) section for what to put in this file.
```
pangolin/
├─ config/
│ ├─ config.yml
```
#### 2. Install Pangolin via the CA Store
#### 3. Configure Pangolin
Set the network to the one you created earlier.
<Frame caption="Pangolin configuration settings in Unraid">
<img
src="/images/pangolin_config.png"
alt="Pangolin configuration settings in Unraid"
/>
</Frame>
**Ports:**
Due to the way Pangolin was designed to work with docker compose and a config file, the way it handles ports is a little different as compared to other popular Unraid containers. For all host ports:
The host ports, container ports, and ports in the config should match for simplicity. This is because the Pangolin config also has ports in it. If you decide to use a non-default port, you would need to edit the port in the template and the config file.
For example, to change the port for the WebUI:
- Click edit on the port
- Set the "Container Port" to the new port you want to use
- Set the "Host Port" to the new port you want to use
- Edit Pangolin's config file and set `server.next_port` to the new port you want to use
#### 4. Start the Pangolin Container
<Warning>
Pangolin will not start without a config file. If you have not created the config file or the config file is invalid, the container will throw an error and exit.
</Warning>
#### 5. Log in to the dashboard
After successful installation:
1. Complete the initial admin user setup via the dashboard at `https://<your-domain>/auth/initial-setup`
2. You can log in using the admin email and password you provided
3. Create your first "Local" site for local reverse proxying
### Install and Setup Traefik
Before starting with Traefik, shut down the Pangolin container.
#### 1. Create the Config Files
Update the appdata path with new files for Traefik. At this point there may be some extra files generated by Pangolin.
```
pangolin/
├─ config/
│ ├─ config.yml
│ ├─ letsencrypt/
│ ├─ traefik/
│ │ ├─ dynamic_config.yml
│ │ ├─ traefik_config.yml
```
**`pangolin/config/traefik/traefik_config.yml`:**
```yaml title="pangolin/config/traefik/traefik_config.yml
api:
insecure: true
dashboard: true
providers:
http:
endpoint: "http://pangolin:3001/api/v1/traefik-config"
pollInterval: "5s"
file:
filename: "/etc/traefik/dynamic_config.yml"
experimental:
plugins:
badger:
moduleName: "github.com/fosrl/badger"
version: "v1.2.0"
log:
level: "INFO"
format: "common"
certificatesResolvers:
letsencrypt:
acme:
httpChallenge:
entryPoint: web
email: admin@example.com # REPLACE THIS WITH YOUR EMAIL
storage: "/letsencrypt/acme.json"
caServer: "https://acme-v02.api.letsencrypt.org/directory"
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
transport:
respondingTimeouts:
readTimeout: "30m"
http:
tls:
certResolver: "letsencrypt"
serversTransport:
insecureSkipVerify: true
```
**`pangolin/config/traefik/dynamic_config.yml`:**
The dynamic configuration file is where you define the HTTP routers and services for the Pangolin frontend and backend. Below is an example configuration for a Next.js frontend and an API backend.
The domain you enter here is what will be used to access the main Pangolin dashboard. Make sure you have the DNS set up correctly for this domain. Point it to the IP address of the server running Pangolin.
```yaml title="pangolin/config/traefik/dynamic_config.yml"
http:
middlewares:
redirect-to-https:
redirectScheme:
scheme: https
routers:
# HTTP to HTTPS redirect router
main-app-router-redirect:
rule: "Host(`pangolin.example.com`)" # REPLACE THIS WITH YOUR DOMAIN
service: next-service
entryPoints:
- web
middlewares:
- redirect-to-https
# Next.js router (handles everything except API and WebSocket paths)
next-router:
rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)" # REPLACE THIS WITH YOUR DOMAIN
service: next-service
entryPoints:
- websecure
tls:
certResolver: letsencrypt
# API router (handles /api/v1 paths)
api-router:
rule: "Host(`pangolin.example.com`) && PathPrefix(`/api/v1`)" # REPLACE THIS WITH YOUR DOMAIN
service: api-service
entryPoints:
- websecure
tls:
certResolver: letsencrypt
# WebSocket router
ws-router:
rule: "Host(`pangolin.example.com`)" # REPLACE THIS WITH YOUR DOMAIN
service: api-service
entryPoints:
- websecure
tls:
certResolver: letsencrypt
services:
next-service:
loadBalancer:
servers:
- url: "http://pangolin:3002" # Next.js server
api-service:
loadBalancer:
servers:
- url: "http://pangolin:3000" # API/WebSocket server
```
#### 2. Install Traefik via the CA Store
This section will use the Traefik template from the "IBRACORP" repository. If you already have a Traefik installation running, you should manually configure your Traefik config to work with Pangolin.
<Frame caption="Traefik repository selection in Community Apps">
<img
src="/images/traefik_repo.png"
width="400"
alt="Traefik repository selection in Community Apps"
/>
</Frame>
#### 3. Configure Traefik
<Frame caption="Traefik configuration settings in Unraid">
<img
src="/images/traefik_config.png"
alt="Traefik configuration settings in Unraid"
/>
</Frame>
<Info>
Please refer to the official Traefik docs for more information on the Traefik configuration beyond this guide.
</Info>
**Match your config to the one above. You will have to remove some of the default variables in the template that are not needed. You can always add them back if you need them later.**
**Network Type:**
Set the network type to the one you created earlier.
**Post Arguments:**
Tell Traefik where the config file is located by adding the following to the "Post Arguments" field. This is not the host path, but the path inside the container.
```bash
--configFile=/etc/traefik/traefik_config.yml
```
**Config Folder:**
If you're using the Traefik config generated by Pangolin, point this to the same appdata path as Pangolin, but append `/traefik`, like this: `<appdata>/config/traefik`.
**Lets Encrypt (Host Path 2 in screenshot):**
Traefik will store the certification information here. You can make this path anywhere you want. For simplicity, we're placing it in the same config path at `<appdata>/config/letsencrypt`.
**Ports:**
You will need to port forward the https and http ports listed in the config on your network's router.
#### 4. Port Forwarding
You will need to port forward the ports you set in the Traefik config on your network's router. This is so that Traefik can receive traffic from the internet. You should forward 443 to the https port and 80 to the http port you set in the Traefik config.
## 2. Add Gerbil for Tunneling (Optional)
<Info>
If you do not want to use the tunneling feature of Pangolin and only want to use it as a local reverse proxy, you can stop here.
</Info>
Before setting up Gerbil, shut down Traefik and Pangolin.
If you plan to use tunneling features of Pangolin with Newt or WireGuard, you will need to add Gerbil to the stack. Gerbil is the tunnel controller for Pangolin and is used to manage the tunnels between the Pangolin server and the client.
Luckily, adding Gerbil is fairly easy.
The important concept to understand going forward, is we need to network Traefik through Gerbil. All Traefik traffic goes through the Gerbil container and exits.
#### 1. Install Gerbil via the CA Store
#### 2. Configure Gerbil
Set the network to the one you created earlier.
<Frame caption="Gerbil configuration settings in Unraid">
<img
src="/images/gerbil_config.png"
alt="Gerbil configuration settings in Unraid"
/>
</Frame>
**Important things to consider:**
**Internal Communication:**
Anywhere you see `http://pangolin:3001` must match. The hostname should be the name of the Pangolin container on the docker network you're using. This is because it is routed using the internal docker DNS address. The port must also match the port you have set for the internal port in Pangolin. These defaults will work unless you changed these values earlier when setting up Pangolin.
**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:**
You must open these ports because Traefik will be routed through Gerbil. These ports should match the ports you set in the Traefik config earlier. In the next step, we will set the network mode for Traefik which will close the ports on the Traefik side, and prevent conflicts. Before doing this, if you start the Traefik container at the same time as the Gerbil container with the same ports mapped to the host, you will get an error.
#### 3. Network Traefik Through Gerbil
As discussed earlier we need to network Traefik through Gerbil. This is pretty easy. We will do all of this in the Traefik container settings.
Toggle advanced settings, and add the following to the "Extra Parameters" section.
```bash
--net=container:Gerbil
```
Then, set "Network Type" to "None".
<Frame caption="Traefik networking configuration through Gerbil">
<img
src="/images/traefik_networking.png"
alt="Traefik networking configuration through Gerbil"
/>
</Frame>
#### 4. Start the stack
We recommend to start the whole stack in the following order:
1. Pangolin
2. Gerbil
3. Traefik
#### 5. Port Forwarding
You will need to port forward the WireGuard port you set in the Gerbil config on your network's router. This is so that the client can connect to the server.
#### 6. Verify Tunnels are Functional
Your logs for Gerbil should look something like this:
<Info>
You probably won't have the peer connection messages but in general, you should see the WireGuard interface being started.
</Info>
<Frame caption="Gerbil logs showing WireGuard interface startup">
<img
src="/images/gerbil_logs.png"
alt="Gerbil logs showing WireGuard interface startup"
/>
</Frame>
Log back into the Pangolin dashboard and create a new site with Newt or basic WireGuard. Copy the credentials to your client and connect. You should see the tunnel status change to "Online" after a few moments if the connection is successful. Remember to also monitor the logs on the client and server.

121
self-host/quick-install-managed.mdx
View File

@@ -1,121 +0,0 @@
---
title: "Quick Install Guide"
description: "Deploy your own managed Pangolin instance in under 10 minutes with our automated installer"
---
<Note>
Self-host your own Pangolin node using the cloud control plane for out of the box high availability and a number of other benefits.
**It's free and all traffic stays on your infrastructure.**
[Why would I want to deploy a managed Pangolin instance?](/manage/managed)
</Note>
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/iPdK8M0cb9s"
title="YouTube video player"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
## Prerequisites
Before you begin, ensure you have:
- **Pangolin Cloud** account. You can [create a free account here](https://pangolin.fossorial.io/auth/signup). No subscription required.
- **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.
## Networking
Before installing Pangolin, ensure you've opened the required port on your firewall. See our guide on [networking](/self-host/dns-and-networking#port-configuration) 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 node 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 node">
Enter either the public IP address of your server or a domain name that resolves to it.
<Note>
The installer will attempt resolve and prefill your public IP address. Verify this is correct before preceding.
</Note>
<Warning>
If you choose to use a domain keep in mind this just resolves your node on the internet while the actual subdomains for resources will be managed in the cloud.
</Warning>
</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 node. Select the adopt method. Use this ID and secret to register your node.
<Tip>
More than one account can use the same node 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 node.
{/* ## Video Walkthrough */}

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

@@ -1,164 +0,0 @@
---
title: "Installation Guide"
description: "Deploy your own fully self-hosted instance of Pangolin Community Edition"
---
<Note>
This guide is for the Community Edition self-hosted Pangolin. For self-hosting a highly available managed node, check out [this quick install guide](/self-host/quick-install-managed).
What does this mean? Learn about Managed Self-hosted Nodes [here](/manage/managed).
</Note>
<Info>
Community Edition Pangolin provides only one node and is not highly available.
</Info>
## Prerequisites
Before you begin, ensure you have:
- **Linux server** with root access and public IP address
- **Domain name** pointing to your server's IP address for the dashboard
- **Email address** for Let's Encrypt SSL certificates and admin log in
- **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 set up DNS for your domain(s) and 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="Configure basic settings">
The installer will prompt you for essential configuration:
- **Base Domain**: Enter your root domain without subdomains (e.g., `example.com`)
- **Dashboard Domain**: Press Enter to accept the default `pangolin.example.com` or enter a custom domain
- **Let's Encrypt Email**: Provide an email for SSL certificates and admin login
- **Tunneling**: Choose whether to install Gerbil for tunneled connections (default: yes). You can run Pangolin without tunneling. It will function as a standard reverse proxy.
</Step>
<Step title="Configure email (optional)">
<Tip>
Email functionality is optional and can be added later.
</Tip>
Choose whether to enable SMTP email functionality:
- **Default**: No (recommended for initial setup)
- **If enabled**: You'll need SMTP server details (host, port, username, password)
</Step>
<Step title="Start installation">
Confirm that you want to install and start the containers:
- The installer will pull Docker images (pangolin, gerbil, traefik)
- Containers will be started automatically
- This process takes 2-3 minutes depending on your internet connection
You'll see progress indicators as each container is pulled and started.
</Step>
<Step title="Install CrowdSec (optional)">
The installer will ask if you want to install CrowdSec for additional security:
- **Default**: No (recommended for initial setup)
- **If enabled**: You'll need to confirm you're willing to manage CrowdSec configuration
<Warning>
CrowdSec adds complexity and requires manual configuration for optimal security. Only enable if you're comfortable managing it.
</Warning>
<Info>
CrowdSec can be installed later if needed. The basic installation provides sufficient security for most use cases.
</Info>
</Step>
</Steps>
## Post-Installation Setup
Once installation completes successfully, you'll see:
```
Installation complete!
To complete the initial setup, please visit:
https://pangolin.example.com/auth/initial-setup
```
<Steps>
<Step title="Access the dashboard">
Navigate to the URL shown in the installer output:
```
https://<your-dashboard-domain>/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 browser throws an insecure warning.
</Check>
</Step>
<Step title="Create admin account">
Complete the initial admin user setup:
- Enter your admin email address
- Set a strong password
- Verify your email (if email is configured)
<Warning>
Use a strong, unique password for your admin account. This account has full system access.
</Warning>
</Step>
<Step title="Create your first organization">
After logging in:
1. Click "Create Organization"
2. Enter organization name and description
<Check>
You're now ready to start adding applications and configuring your reverse proxy!
</Check>
</Step>
</Steps>
## Video Walkthrough
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/W0uVLjTyAn8"
title="Pangolin Quick Install Guide"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>

132
self-host/supporter-program.mdx
View File

@@ -1,132 +0,0 @@
---
title: "Supporter Program"
description: "Support Pangolin development and remove UI elements with a supporter key"
---
Pangolin self-hosted will always be free and open source, but maintaining the project takes time and resources. The supporter program helps fund ongoing development — including bug fixes, new features, and community support.
## Supporter Tiers
<Tabs>
<Tab title="Limited Supporter ($25)">
**Perfect for small teams**
- **User limit**: 5 or fewer users
- **Support button**: Removed from UI
- **Usage**: Unlimited servers and installations
- **Upgrade**: Available to Full Supporter
<Warning>
Once you add your 6th user, the support button will return. Remove a user or upgrade to Full Supporter to hide it again.
</Warning>
</Tab>
<Tab title="Full Supporter ($95)">
**Perfect for larger teams**
- **User limit**: Unlimited users
- **Support button**: Permanently removed
- **Usage**: Unlimited servers and installations
- **Best value**: For growing teams
<Check>
The support button and other marks will never return, regardless of user count.
</Check>
</Tab>
</Tabs>
<Frame caption="Supporter tier comparison showing Limited vs Full Supporter benefits">
<img
src="/images/supporter-tiers.png"
alt="Supporter tier comparison showing Limited vs Full Supporter benefits"
/>
</Frame>
## How to Get Your Supporter Key
<Steps>
<Step title="Purchase a tier">
Go to our [GitHub Sponsors page](https://github.com/sponsors/fosrl) and purchase either:
- **Limited Supporter**: $25 one-time
- **Full Supporter**: $95 one-time
</Step>
<Step title="Get your key">
After purchase, visit [supporters.fossorial.io](https://supporters.fossorial.io) and:
1. Log in with your GitHub account
2. Copy your supporter key
</Step>
<Step title="Redeem in Pangolin">
In your Pangolin dashboard:
1. Click the supporter button
2. Enter your supporter key
3. Click "Redeem"
</Step>
</Steps>
<Frame caption="Pangolin supporter key redemption interface">
<img
src="/images/redeem-key.png"
alt="Pangolin supporter key redemption interface"
/>
</Frame>
## Frequently Asked Questions
<AccordionGroup>
<Accordion title="How many servers can I use my key on?">
**Unlimited usage**
You can use your supporter key on as many servers and installations as you want. There are no restrictions on the number of deployments.
</Accordion>
<Accordion title="Can I upgrade my tier?">
**Yes, but requires new purchase**
To upgrade from Limited to Full Supporter:
1. Purchase the Full Supporter ($95) tier on GitHub
2. Your account will be automatically upgraded
3. Restart your Pangolin server to update the status
<Warning>
Due to GitHub's tier system, you must purchase the higher tier even if you already have the lower one. This results in an extra donation, which we appreciate!
</Warning>
</Accordion>
<Accordion title="Can I hide the button without paying?">
**Temporary hiding available**
You can click "Hide for 7 days" at the bottom of the supporter dialog to temporarily hide the button without purchasing a supporter key.
</Accordion>
<Accordion title="What if I buy the same tier again?">
**Thanks for the extra donation!**
You can only obtain one supporter key per tier. Additional purchases of the same tier won't change your key, but we appreciate the extra support!
</Accordion>
<Accordion title="Can I get a refund?">
**No refunds available**
GitHub Sponsors does not allow us to refund donations. Please make sure you're comfortable supporting the project before purchasing a tier.
</Accordion>
<Accordion title="What happens if I exceed my user limit?">
**Limited Supporter restrictions**
If you have a Limited Supporter key and add your 6th user:
- The support button will return to the UI
- You can either remove a user or upgrade to Full Supporter
- Your key remains valid for other installations
<Info>
Full Supporter keys have no user limits.
</Info>
</Accordion>
</AccordionGroup>

66
self-host/system-architecture.mdx
View File

@@ -1,66 +0,0 @@
---
"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 node 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>

42
self-host/telemetry.mdx
View File

@@ -1,42 +0,0 @@
---
title: "Telemetry"
description: "Understanding Pangolin's anonymous usage data collection"
---
Pangolin collects anonymous usage telemetry to help us understand how the software is used and guide future improvements and feature development.
## What We Collect
The telemetry system collects **anonymous, aggregated data** about your Pangolin deployment. For example:
- **System metrics**: Number of sites, users, resources, and clients
- **Usage patterns**: Resource types, protocols, and SSO configurations
- **Performance data**: Site traffic volumes and online status
- **Deployment info**: App version and installation timestamp
## Privacy & Anonymity
**No personal information is ever collected or transmitted.** All data is:
- **Anonymized**: Identifying info is hashed using SHA-256
- **Non-identifying**: Cannot be used to identify specific users or organizations
## Configuration
You can control telemetry collection in your `config.yml`:
```yaml
app:
telemetry:
anonymous_usage: true # Set to false to disable
```
## What This Helps
Anonymous usage data helps us:
- Identify popular features and usage patterns
- Prioritize development efforts
- Improve performance and reliability
- Make Pangolin better for everyone
If you have concerns about telemetry collection, you can disable it entirely by setting `anonymous_usage: false` in your configuration.