diff --git a/docs/01_Architecture/Pangolin/About/How_Pangolin_Works.md b/docs/01_Architecture/Pangolin/About/How_Pangolin_Works.md
new file mode 100644
index 00000000..8d15f1f8
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/About/How_Pangolin_Works.md
@@ -0,0 +1,109 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# How Pangolin Works
+
+> Learn about the fundamentals of Pangolin and how they work together to provide simple and secure remote access.
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+## Basic Steps
+
+
+
+ Join remote networks together using site connectors. Pangolin's lightweight connectors use intelligent routing and NAT traversal to make any network anywhere available.
+
+
+
+ Create resources that represent services or entire network ranges available for remote access. Resources can be public or fully private.
+
+
+
+ Authenticated users can access resources anywhere using a web browser or when connected with a Pangolin client on their device.
+
+
+
+## Key Concepts
+
+Pangolin relies on several components that work together to provide secure remote access. Each component has a specific
+role in ensuring that only authenticated users can access the resources they are authorized to use.
+
+### Pangolin Server
+
+The Pangolin server is the central coordination component for your network. It stores configuration changes, manages
+access policies, and coordinates connections between clients and sites. The server handles user authentication and
+generates access control lists that determine what resources each user can reach.
+
+You can use Pangolin Cloud, which is fully managed, or you can self-host your own Pangolin server for complete control
+over your infrastructure and data.
+
+
+ Learn how to deploy your own self-hosted Pangolin server or use Pangolin Cloud.
+
+
+### Sites
+
+Sites connect remote networks to your Pangolin server. They use Newt connectors to create secure tunnels from remote
+networks back to Pangolin. Sites let you expose resources on those networks to authorized users.
+
+Sites run behind firewalls on remote networks. They maintain outbound connections to the Pangolin server. By default,
+sites block all traffic until you define resources and grant access. This ensures that just deploying a site does not
+expose any network resources.
+
+The Newt connector handles tunnel creation, NAT traversal, and routing. It makes remote networks available without
+requiring complex firewall rules or public IP addresses.
+
+
+ Learn about sites, how they work, and how to install and configure them.
+
+
+### Resources
+
+Resources are the applications, hosts, or network ranges you make available to users. They exist on sites and represent
+what users can access. Users connect to resources, not to sites directly.
+
+There are two types of resources. Public resources work through web browsers and act as reverse proxies to backend
+services. Private resources require a client connection and function like a zero-trust VPN.
+
+You must define resources and assign access before users can reach them. By default, no resources are available on
+sites. This ensures that only explicitly defined resources can be accessed.
+
+
+ Learn about public and private resources and how to create them.
+
+
+### Clients
+
+Clients are software components installed on user devices or machines. They let users and automated systems connect to
+your Pangolin network and access private resources through a secure tunnel.
+
+Users authenticate through the client using their accounts. Machines connect with credentials. Once connected, users can
+reach all resources their account has access to. The client handles routing decisions and establishes encrypted tunnels
+to the appropriate sites.
+
+Clients are available for Mac, Windows, and Linux. They work transparently with applications, so no application
+configuration is required.
+
+
+ Learn about clients and where to download them for Mac, Windows, and Linux.
+
+
+### Remote Nodes
+
+Remote nodes are self-hosted Pangolin servers that you control while using Pangolin Cloud
+or [Enterprise Edition](/self-host/enterprise-edition) for management and coordination. You maintain complete control
+over your infrastructure and data flow, while the cloud handles the control plane, DNS, certificate management, and
+backups.
+
+You can deploy multiple remote nodes for high availability and automatic failover. If your nodes become unavailable,
+traffic can optionally fail over to cloud infrastructure until you restore service.
+
+
+ Learn about remote nodes and how they provide high availability and simplified operations.
+
+
diff --git a/docs/01_Architecture/Pangolin/About/Pangolin_vs._Reverse-Proxy_vs._VPN.md b/docs/01_Architecture/Pangolin/About/Pangolin_vs._Reverse-Proxy_vs._VPN.md
new file mode 100644
index 00000000..e011e900
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/About/Pangolin_vs._Reverse-Proxy_vs._VPN.md
@@ -0,0 +1,89 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Pangolin vs. Reverse Proxy vs. VPN
+
+> What are the similarities and differences between Pangolin and traditional reverse proxies and VPNs?
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Pangolin combines the capabilities of both a reverse proxy and a VPN into a single platform. It provides reverse proxy
+functionality through public resources and VPN functionality through private resources, all with zero-trust access
+control and distributed architecture.
+
+## What Each Solution Provides
+
+**Reverse Proxies** expose web applications to the internet. They handle SSL termination, load balancing, and basic
+authentication. Users access applications through web browsers using domain names.
+
+**VPNs** create encrypted tunnels that give users access to entire private networks. Users install client software and
+connect to a VPN server. Once connected, they can access any resource on the network they have network-level access to.
+
+**Pangolin** provides both capabilities. Public resources work like a reverse proxy, allowing browser-based access to
+specific applications. Private resources work like a zero-trust VPN, giving users access to specific hosts or network
+ranges when connected with a client.
+
+## Reverse Proxy Capabilities
+
+Pangolin's public resources function as reverse proxies. They expose web applications through domain names with
+automatic SSL certificates. Users access these resources through web browsers without installing any software.
+
+Public resources support identity-aware access control. You can require authentication, enforce multi-factor
+authentication, and create rules based on user identity, roles, geographic location, IP addresses, and URL paths. This
+goes beyond what traditional reverse proxies offer.
+
+Unlike traditional reverse proxies, Pangolin does not require public IP addresses or open ports on your network. Sites
+create outbound tunnels to Pangolin, so your applications remain behind firewalls.
+
+## VPN Capabilities
+
+Pangolin's private resources function like a zero-trust VPN. Users install a Pangolin client on their device and connect
+to your organization. Once connected, they can access the specific hosts or network ranges you have granted them access
+to.
+
+Private resources provide granular access control. Users only get access to the specific resources you define, not
+entire networks. This reduces the risk of over-permission that comes with traditional VPNs.
+
+Clients work transparently with applications. No application configuration is required. Users connect once and can
+access all their authorized resources. The client handles routing and establishes encrypted tunnels automatically.
+
+## Why Pangolin Combines Both
+
+Many organizations need both reverse proxy and VPN capabilities. You might want to expose web applications to users
+through browsers while also providing secure access to databases, SSH servers, or internal services that require a
+VPN-like connection.
+
+With Pangolin, you use one platform for both use cases. Public resources handle web application access. Private
+resources handle VPN-like access. Both use the same authentication system, access control policies, and infrastructure.
+
+This unified approach simplifies management. You configure users, roles, and access policies once. Those policies apply
+to both public and private resources. You do not need to maintain separate systems for reverse proxy and VPN access.
+
+## Infrastructure and Availability
+
+Traditional reverse proxies and VPNs typically run on a single server. If that server fails, all access is lost. They
+also require public IP addresses and open ports, which adds complexity and security concerns.
+
+Pangolin uses a distributed architecture with multiple nodes. If one node fails, traffic automatically routes to another
+node. Sites create outbound tunnels, so your networks do not need public IP addresses or open ports.
+
+You can deploy multiple remote nodes for high availability. If your nodes become unavailable, traffic can optionally
+fail over to cloud infrastructure until you restore service. This provides redundancy that single-server solutions
+cannot match.
+
+## When to Use Each Solution
+
+Use a traditional reverse proxy if you only need to expose web applications, you have a public IP address, and you do
+not need advanced access control or high availability.
+
+Use a traditional VPN if you need full network access, you can accept the security risks of broad access, and you do not
+need application-specific access control.
+
+Use Pangolin if you need both reverse proxy and VPN capabilities, you want granular access control, you need high
+availability, or you want to avoid public IP addresses and open ports.
+
diff --git a/docs/01_Architecture/Pangolin/Documentation Index Fetch.md b/docs/01_Architecture/Pangolin/Documentation Index Fetch.md
new file mode 100644
index 00000000..00e369dd
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Documentation Index Fetch.md
@@ -0,0 +1,131 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# How to Update
+
+> Keep your Pangolin deployment up to date with the latest features and security patches
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+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
+
+
+ **Always backup your data before updating.** Copy your `config` directory to a safe location so you can roll back if needed.
+
+
+
+ **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.
+
+
+## Update Process
+
+
+
+ Stop all running containers:
+
+ ```bash theme={"dark"}
+ sudo docker compose down
+ ```
+
+
+
+
+ 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)
+
+
+ Look for the latest stable release (not pre-release or beta versions).
+
+
+
+
+
+ Edit your `docker-compose.yml` file and update the image versions:
+
+ ```yaml title="docker-compose.yml" theme={"dark"}
+ services:
+ pangolin:
+ image: fosrl/pangolin:1.16.2 # 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" theme={"dark"}
+ experimental:
+ plugins:
+ badger:
+ moduleName: github.com/fosrl/badger
+ version: v1.3.0 # Update to latest version
+ ```
+
+
+ Update each service you want to upgrade. You can update them individually or all at once.
+
+
+
+
+
+ Download the updated Docker images:
+
+ ```bash theme={"dark"}
+ sudo docker compose pull
+ ```
+
+
+
+
+ Start the updated containers:
+
+ ```bash theme={"dark"}
+ sudo docker compose up -d
+ ```
+
+
+
+
+ Watch the logs to ensure everything starts correctly:
+
+ ```bash theme={"dark"}
+ sudo docker compose logs -f
+ ```
+
+
+
+
+ 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
+
+
+ If everything works, your update is complete!
+
+
+
+
+
+
+Built with [Mintlify](https://mintlify.com).
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/ASN_Blocking.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/ASN_Blocking.md
new file mode 100644
index 00000000..ba885c47
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/ASN_Blocking.md
@@ -0,0 +1,130 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# ASN Blocking
+
+> Configure ASN blocking to restrict access based on Autonomous System Numbers
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ ASN blocking is available in Pangolin community! Protect your resources by blocking or allowing specific networks and service providers.
+
+
+## Benefits of ASN Blocking
+
+ASN blocking provides several important security and operational advantages:
+
+### Security Benefits
+
+* **Block Malicious Networks**: Prevent access from autonomous systems known for hosting malicious activity, botnets, or
+ spam operations
+* **Control Cloud Provider Access**: Restrict or allow access from specific cloud providers (AWS, Azure, GCP, etc.)
+* **Block VPN/Proxy Services**: Deny access from commercial VPN and proxy service providers to prevent anonymous access
+* **Datacenter Filtering**: Block traffic from datacenter networks while allowing residential ISPs
+* **Compliance Requirements**: Meet regulatory requirements that restrict access from certain network types or providers
+
+## Implementing ASN Blocking with Bypass Rules
+
+ASN blocking in Pangolin is implemented using [bypass rules](/manage/access-control/rules) with ASN-based matching. You
+can create rules that either allow or deny access based on the visitor's Autonomous System Number.
+
+
+
+
+
+### Setting Up ASN Blocking Rules
+
+1. Navigate to your target resource and select the **Rules** tab
+2. Create a new rule and select **ASN** as the match type
+3. Choose an ASN from the dropdown of common providers, or manually enter a specific ASN number
+4. Choose your rule action:
+ * **Allow**: Bypass authentication for users from specific ASNs
+ * **Deny**: Block all access from specific ASNs
+ * **Pass to Auth**: Let users from specific ASNs proceed to authentication
+
+### Common ASNs
+
+The dropdown includes many commonly-used ASNs such as:
+
+* **Cloud Providers**: Amazon (AS16509), Google Cloud (AS15169), Microsoft Azure (AS8075), DigitalOcean (AS14061)
+* **Major ISPs**: Comcast (AS7922), AT\&T (AS7018), Verizon (AS701), Deutsche Telekom (AS3320)
+* **VPN/Proxy Services**: NordVPN (various), ExpressVPN (various), Mullvad (AS42831)
+* **CDN Providers**: Cloudflare (AS13335), Fastly (AS54113), Akamai (various)
+
+If the ASN you need isn't in the dropdown, you can manually enter the ASN number (e.g., AS12345 or just 12345).
+
+### Common ASN Blocking Patterns
+
+#### Block VPN and Proxy Services
+
+Create deny rules for known VPN and proxy ASNs to prevent anonymous access:
+
+1. Create **Deny** rules for each VPN/proxy provider ASN
+2. Select ASNs from the dropdown or enter them manually
+3. Set appropriate priorities
+
+#### Block Datacenter Traffic
+
+Block access from datacenter and hosting provider ASNs while allowing residential users:
+
+1. Create **Deny** rules for major cloud and hosting provider ASNs
+2. Include providers like AWS, GCP, Azure, DigitalOcean, etc.
+3. This helps ensure only real users from residential ISPs can access your resources
+
+#### Allow Only Specific Networks
+
+Create a default deny rule and explicitly allow only approved ASNs:
+
+1. Create a **Deny** rule matching all traffic with priority 100
+2. Create **Allow** rules for specific approved ASNs with higher priority (e.g., 10, 20, 30)
+
+#### Regional ISP Control
+
+Allow access only from specific country ISPs while blocking others:
+
+1. **Combine with Country Rules**: Use ASN rules to specify which ISPs are allowed
+2. Create **Allow** rules for major residential ISPs in your target countries
+3. Block datacenter and VPN ASNs that might circumvent country restrictions
+
+### Best Practices
+
+
+ ASN blocking affects all users from that network. Be careful when blocking large ISPs or cloud providers, as legitimate users or your own infrastructure may be affected.
+
+
+### Finding ASN Numbers
+
+If you need to find the ASN for a specific network or provider:
+
+1. Use online tools like [bgp.he.net](https://bgp.he.net/) or [ipinfo.io](https://ipinfo.io/)
+2. Search by company name, IP address, or ASN number
+3. Enter the ASN in the rule configuration (with or without the "AS" prefix)
+
+### Rule Priority Example
+
+```
+Priority 1: Allow - ASN: AS7922 (Comcast)
+Priority 2: Allow - ASN: AS7018 (AT&T)
+Priority 3: Deny - ASN: AS13335 (Cloudflare - VPN)
+Priority 4: Deny - ASN: AS16509 (Amazon - Datacenter)
+```
+
+This configuration allows access from residential users on Comcast and AT\&T while blocking Cloudflare's VPN service and
+Amazon datacenters.
+
+### Advanced Patterns
+
+#### Block Bot Networks
+
+Identify and block ASNs associated with automated bot traffic:
+
+1. Monitor your access logs for suspicious ASNs
+2. Create **Deny** rules for ASNs showing bot-like behavior
+3. Regularly review and update your blocklist
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Change_Password.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Change_Password.md
new file mode 100644
index 00000000..c3c5815f
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Change_Password.md
@@ -0,0 +1,36 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Change Password
+
+> Change or reset your Pangolin account password
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+### Change Password
+
+If you're already logged in, you can change your password by clicking your profile menu (top right) and selecting Change
+Password. You will be required to confirm your old password and enter a new password.
+
+
+ If you want to require password changes at regular intervals for better security, check out the [password rotation documentation](/manage/access-control/password-rotation).
+
+
+### Reset Password
+
+If you forgot your password, you can use the reset password function. On the login page, select Forgot your password?.
+This will ask for your username or email. A reset code will be sent to that email to complete the reset.
+
+If you're self‑hosting Pangolin, you will need an SMTP server configured to send emails. If you don't have one
+configured, the server will log the reset code to the server logs for you to retrieve and use to reset the password.
+
+### Force Reset Server Admin Password
+
+For self‑hosted Pangolin, if you need to force reset your server admin account password server‑side, you can use the
+internal CLI. [See more here](/self-host/advanced/container-cli-tool).
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Create_User.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Create_User.md
new file mode 100644
index 00000000..b2e28539
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Create_User.md
@@ -0,0 +1,42 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Create User
+
+> Add internal or external users to your organization
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Users can be added to organizations. When a user is added to Pangolin, there is a global user object and an
+organization‑specific user object that links that user to the organization. This allows a user to exist in one or more
+organizations.
+
+
+ Because the root user exists and a per‑organization user exists, a user invited to an organization may be able to create a new organization. You can disable this functionality via a flag in the config file in self‑hosted Pangolin. [Check out the config file documentation](/self-host/advanced/config-file#feature-flags).
+
+
+When removing a user from an organization, their account still exists. To completely delete their account, visit the
+server admin panel as the server admin and delete the global user in the users table.
+
+### Internal Users
+
+An internal user is an identity managed by Pangolin only. When adding the user, you will receive an invite link. The
+user needs to use this link to either accept the invite, or create an account for the first time and accept the invite.
+
+### External Users
+
+An external user is an identity managed by an external identity provider. When creating an external user, you will need
+to select an existing identity provider added to
+Pangolin. [Check out the documentation on adding an IDP](/manage/identity-providers/add-an-idp).
+
+An identity provider may have auto‑provisioning enabled. This means new users who log in with the IDP are automatically
+created and you do not need to manually create the
+user. [Check out the auto‑provisioning documentation](/manage/identity-providers/auto-provisioning).
+
+Even if auto‑provisioning is enabled, you can still manually create users.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Custom_Login_Page.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Custom_Login_Page.md
new file mode 100644
index 00000000..e5d49a6c
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Custom_Login_Page.md
@@ -0,0 +1,56 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Custom Login Page
+
+> Configure a custom authentication page URL for your organization
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ Custom auth pages are only available in Pangolin Cloud.
+
+
+Custom organization authentication pages let you serve the login page at your own domain instead of the default
+`app.pangolin.net`. This provides better user experience and brand consistency.
+
+
+
+## Benefits
+
+**For Resource Authentication:**
+
+* Users are redirected to your custom domain for login
+* Familiar domain builds trust and security awareness
+* Consistent branding throughout the authentication flow
+
+**For Identity Provider Integration:**
+
+* Centralized login page for your organization
+* Choose between multiple login methods (Google, Azure, etc.)
+* Platform SSO: login once, access all Pangolin resources
+* Direct access to the Pangolin management dashboard
+
+
+
+
+
+## Configuration
+
+1. Go to **Settings** in your organization sidebar
+2. Use the domain picker to select your custom domain
+3. Save your changes
+
+
+ You need to add a custom domain to your organization first. Free domains (`*.tunneled.to`, `*.hostlocal.app`, etc.) cannot be used for auth pages. [Learn how to add domains](/manage/domains#adding-domains)
+
+
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Device_Approvals.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Device_Approvals.md
new file mode 100644
index 00000000..d1110882
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Device_Approvals.md
@@ -0,0 +1,53 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Device Approvals
+
+> Only allow trusted devices to connect to an organization
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ Only available in Pangolin Cloud and [Enterprise Edition](/self-host/enterprise-edition).
+
+
+By default, any client configured with valid credentials can connect to an organization. To enhance security, you can
+enable device approvals, which require each new device to be manually approved by an administrator before it can
+connect.
+
+When device approvals are enabled, the first time a user connects a new device to the organization, the device will be
+marked as "Pending Approval." An administrator must then review and approve the device in the management console before
+it can access organization resources.
+
+
+
+
+
+All approvals can also be managed from a central page as they stream in to allow admins to approve or deny devices
+quickly.
+
+
+
+
+
+## Enabling Device Approvals
+
+Device approvals are enabled on a per-role basis. To enable device approvals for a role, follow these steps:
+
+1. Click on the **Roles** tab.
+2. Select the role you want to enable device approvals for.
+3. Toggle the **Require Device Approval** option to enable it.
+4. Save your changes.
+
+Once enabled, any new user connecting with that role will require approval from an administrator before it can access
+organization resources.
+
+
+ You cannot enable device approvals for the "Admin" role.
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Forwarded_Headers.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Forwarded_Headers.md
new file mode 100644
index 00000000..3f07b7f9
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Forwarded_Headers.md
@@ -0,0 +1,63 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Forwarded Headers
+
+> Learn how Pangolin forwards user identity information to your backend applications through HTTP headers
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Pangolin can forward user identity information to your backend applications through custom HTTP headers. This allows
+your applications to receive user details directly from the request headers, enabling integration with Pangolin's
+authentication system.
+
+
+ Forwarded headers are only available when using authentication methods that provide user identity information.
+
+
+## Supported Headers
+
+Pangolin forwards the following headers to your backend when user identity is available:
+
+| Header | Description | Example |
+|----------------|---------------------------------|------------------------|
+| `Remote-User` | Unique username or user ID | `user_123` |
+| `Remote-Email` | User's email address | `john.doe@example.com` |
+| `Remote-Name` | User's full name | `John Doe` |
+| `Remote-Role` | User's role or group membership | `admin` |
+
+## Authentication Methods
+
+### Headers Available
+
+These authentication methods provide user identity information and will include the forwarded headers:
+
+
+
+ Full user identity information including username, email, and name.
+
+
+
+### Headers Not Available
+
+These authentication methods do not provide user identity information:
+
+
+
+ No user identity - only access control.
+
+
+
+ No user identity - only access control.
+
+
+
+ No user identity - only access control.
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Geo-blocking.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Geo-blocking.md
new file mode 100644
index 00000000..f46815ba
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Geo-blocking.md
@@ -0,0 +1,99 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Geo-blocking
+
+> Configure geo blocking to restrict access based on geographic location
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ Geoblocking is available in Pangolin community! Make sure to follow this guide for how to enable: [Enabling Geo Blocking](/self-host/advanced/enable-geoblocking)
+
+
+
+
+## Benefits of Geo Blocking
+
+Geo blocking provides several important security and compliance advantages:
+
+### Security Benefits
+
+* **Reduce Attack Surface**: Block access from regions with high levels of malicious activity or where you don't expect
+ legitimate users
+* **Prevent Unauthorized Access**: Limit exposure to threat actors operating from specific geographic locations
+* **Compliance Requirements**: Meet regulatory requirements that restrict data access based on geographic location
+* **Resource Protection**: Prevent unnecessary load on your services from regions where you don't operate
+
+## Implementing Geo Blocking with Bypass Rules
+
+Geo blocking in Pangolin is implemented using [bypass rules](/manage/access-control/rules) with country-based matching.
+You can create rules that either allow or deny access based on the visitor's country.
+
+
+
+
+
+### Setting Up Geo Blocking Rules
+
+1. Navigate to your target resource and select the **Rules** tab
+2. Create a new rule and select **Country** as the match type
+3. Choose your rule action:
+ * **Allow**: Bypass authentication for users from specific countries
+ * **Deny**: Block all access from specific countries
+ * **Pass to Auth**: Let users from specific countries proceed to authentication
+
+### Common Geo Blocking Patterns
+
+#### Allow Only Specific Countries
+
+Create a "Deny" rule that blocks all countries except those you want to allow:
+
+1. Create a **Deny** rule
+2. Select **Country** match type
+3. Choose "ALL" to match all countries
+4. Add priority: 100 (lower priority)
+
+Then create specific allow rules for your approved countries:
+
+1. Create **Allow** rules for each approved country
+2. Set higher priority (e.g., 10, 20, 30) so they process first
+
+#### Block Specific High-Risk Countries
+
+Create targeted deny rules for specific countries while allowing all others:
+
+1. Create **Deny** rules for each country you want to block
+2. Select the specific countries from the dropdown
+3. Set appropriate priorities
+
+#### Regional Access Control
+
+Combine geo blocking with other rule types for sophisticated access control:
+
+1. **Path + Country**: Block admin paths (`/admin/*`) from all countries except your headquarters
+2. **IP + Country**: Allow specific IPs from restricted countries (for VPN users or partners)
+3. **CIDR + Country**: Combine network-based and geography-based restrictions
+
+### Best Practices
+
+
+ IP geolocation is not always 100% accurate. Users with VPNs, proxies, or mobile networks may appear to be from different countries than expected.
+
+
+### Rule Priority Example
+
+```
+Priority 1: Allow - Country: United States
+Priority 2: Allow - Country: Canada
+Priority 3: Allow - Country: United Kingdom
+Priority 4: Deny - Country: ALL
+```
+
+This configuration allows access only from the US, Canada, and UK while blocking all other countries.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Multi-Factor_Authentication.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Multi-Factor_Authentication.md
new file mode 100644
index 00000000..5343359c
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Multi-Factor_Authentication.md
@@ -0,0 +1,41 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Multi-Factor Authentication
+
+> Enable and manage two-factor authentication and enforcement for your organization
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Pangolin supports two‑factor authentication (2FA) for Pangolin user accounts.
+
+### Enable or Disable 2FA
+
+* Click your profile menu (top right) to enable two‑factor authentication.
+* You will need to confirm your password and code before enabling/disabling 2FA.
+
+### Supported Methods
+
+* **Time‑based one‑time code (TOTP)**: Use an authenticator app (e.g., 1Password, Google Authenticator).
+* **Push via email**: Contact sales to enable.
+* **Push via Duo**: Contact sales to enable.
+
+### Enforcement
+
+
+ Two‑factor enforcement (requiring 2FA at login) is available in [Enterprise Edition](/self-host/enterprise-edition) only.
+
+
+To enable enforcement, go to Organization Settings and toggle 2FA enforcement in the Security section.
+
+* Enforcement is configured per organization.
+* MFA enforcement only applies to internal Pangolin user accounts. This policy does not apply to accounts linked to an
+ external identity provider.
+* When enforced, users must enable 2FA before accessing the organization or its resources.
+* Users without 2FA will see a prompt directing them to enable it before proceeding.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Password_Rotation.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Password_Rotation.md
new file mode 100644
index 00000000..1443667b
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Password_Rotation.md
@@ -0,0 +1,32 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Password Rotation
+
+> Configure password expiration and rotation requirements for your organization
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+By default, Pangolin does not require passwords to be rotated on a regular basis. However, password rotation can be
+required on a per‑organization basis.
+
+### Configuration
+
+
+ Password expiry and rotation is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
+
+
+To enable password rotation, go to Organization Settings and select a maximum password age in the Security section.
+After the configured period expires, users will be prompted to change their password when accessing the organization or
+its resources.
+
+* Password rotation is enforced on a per‑organization basis.
+* Password rotation only applies to internal Pangolin user accounts. This policy does not apply to accounts linked to an
+ external identity provider.
+* Users who need to change their password will see a prompt directing them to update it before proceeding.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Rules.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Rules.md
new file mode 100644
index 00000000..a126bd71
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Rules.md
@@ -0,0 +1,170 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Rules
+
+> Configure rules to allow or deny access to resources without authentication
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Rules allow you to either "allow" and bypass the Pangolin auth system (no pin, login, password), or "deny" and fully
+reject the request. After you create a resource you can select the "Rules" tab on the sidebar and enable rules.
+
+
+
+ Bypass authentication completely for matching requests. Users can access resources without any login or PIN.
+
+
+
+ Completely reject requests that match the rule. Useful for blocking admin paths or sensitive endpoints.
+
+
+
+ Pass requests that match the rule to the next stage for user to authenticate with SSO, password, or pin. Useful for enforcing auth on specific paths while allowing others.
+
+
+
+## Types of Rules
+
+Rules are processed from top to bottom in order of their priority. This means you can have multiple rules to bypass auth
+and to just flat deny users at the end.
+
+Right now you can match on the following items:
+
+### Path
+
+Path match rules allow URL patterns defined with plain text and wildcards (`*`) that match any characters. Patterns and
+URLs are split into segments (using `/`), and **each segment is matched individually**.
+
+#### Examples:
+
+* `blog/posts`
+ Matches the exact path `/blog/posts`.
+
+* `blog/*`
+ Matches any path under `/blog` (e.g., `/blog/travel`).
+
+* `*/2023/*`
+ Matches paths with `/2023/` as a middle segment (e.g., `/news/2023/summary`).
+
+* `article*`
+ Matches **segments** starting with "article" (e.g., `/article-123`).
+
+* `*admin*`
+ Matches **segments** containing "admin" (e.g., `/my-admin-panel`).
+
+* `personal-*/*`
+ Matches paths where the first segment starts with `personal-` and is followed by any segment (e.g.,
+ `/personal-blog/post`).
+
+#### Segment-by-Segment Matching
+
+* **Normalization:**
+ Both patterns and URLs are split into segments. For example, `/blog/journal/entry` becomes
+ `["blog", "journal", "entry"]`, while `/blog*` becomes `["blog*"]`.
+
+* **Validation:**
+ Each pattern segment must correspond to a URL segment, and wildcards match zero or more characters within that
+ segment. A pattern like `/blog*` only matches the first segment, so URLs with extra segments require additional
+ placeholders (e.g., `/blog*/*`).
+
+### Country
+
+Country match rules allow you to specify allowed or denied countries for requests based on their IP address. This is
+useful for geo-restrictions or compliance with regional regulations.
+
+We use a IP database to geolocate the IP address but this is not always accurate. We try to keep it updated, but there
+may be cases where the location is incorrect.
+
+Select the "ALL" option to match all countries for allowing or denying access.
+
+### CIDR
+
+CIDR (Classless Inter-Domain Routing) notation specifies IP address ranges using an IP address and a network prefix
+length. The format is \[IP address]/\[prefix length].
+
+**Examples:**
+
+* `192.168.1.0/0` - Matches all 256 IPs from 192.168.1.0 to 192.168.1.255
+* `10.0.0.0/8` - Matches any IP starting with 10 (16.7 million addresses)
+* `2001:db8::/32` - Matches a range of IPv6 addresses
+* `0.0.0.0/0` - Matches all IPv4 addresses
+
+
+ The prefix length (1-32 for IPv4, 1-128 for IPv6) determines how many bits from the left are fixed. Smaller prefix numbers match larger ranges.
+
+
+### IP
+
+Pretty simple: you can match on simply an IP address like your home IP to bypass auth. This is the same as entering a
+/32 CIDR.
+
+**Examples:**
+
+* `23.234.134.32`
+* `34.45.245.64`
+* `192.168.1.1`
+
+## Rules for Specific Apps
+
+This table compiles paths that need to be allowed for various apps to work with Pangolin authentication.
+
+| App | Required Bypass Rules |
+|----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Media Management** | |
+| Radarr | `/api/*` |
+| Sonarr | `/api/*` |
+| Lidarr | `/api/*` |
+| **Media Servers** | |
+| Jellyfin (iOS) | `/system/info/public` |
+| Jellyfin (Roku) | `/System/Info/Public` `/Users/AuthenticateByName` `/Users/Public` `/QuickConnect/Initiate` `/QuickConnect/Connect` `/Users/AuthenticateWithQuickConnect` |
+| Audiobookshelf | Audiobookshelf also supports `/audiobookshelf` by default. Each rule should also be applied to this path. `/api/*` `/login` `/auth/*` `/feed/*` `/socket.io/` `/status` `/logout` `/ping` `/public/*` The following is needed for public shares and is optional for clients: `/share/*` `/_nuxt/*.js` `/_nuxt/fonts/*` |
+| **Management & Monitoring** | |
+| Tautulli | `/api/*` |
+| Harbour | `/api/*` |
+| Hoarder App | `/api/*` |
+| Uptime Kuma Manager | `/api/*` `/socket.io/*` |
+| Beszel | `/api/beszel/agent-connect` |
+| MeshCentral | `/api/*` `/meshrelay.ashx` `/agent.ashx` |
+| **Security & Privacy** | |
+| AdGuard Home | `/api/*` |
+| Ente Auth | `*api*` |
+| Vaultwarden/Bitwarden | `/api/*` `/identity/*` `/wl/*` Always Deny - Path - `/admin/*` |
+| **Cloud & Sync** | |
+| Nextcloud | `/` (Main interface) `/index.php` (Core handler) `/remote.php` (Remote access) `/status.php` (Status checks) `/ocs` (Collaboration Services API) `/apps` (Applications) `/remote.php/webdav` (WebDAV endpoint) `/remote.php/dav` (CalDAV/CardDAV) `/remote.php/caldav` (Calendar sync) `/remote.php/carddav` (Contacts sync) `/ocs/v1.php` (API endpoints) `/ocs/v2.php` (API v2 endpoints) `/login` (Authentication) `/.well-known/*` (Service discovery) `/.well-known/webfinger` (WebFinger protocol) `/s/*` (Shared files/folders) |
+| Onlyoffice | `/cache/*` `*/CommandService.ashx` `*/converter/*` `*/doc/*` `*/downloadas/*` `/downloadfile/*` `*/fonts/*` `/healthcheck` `/methodology/*` `*/plugins.json` `*/sdkjs/*` `*/sdkjs-plugins/*` `*/themes.json` `*/web-apps/*` |
+| **Photo Management** | |
+| Ente Photos | `*api*` |
+| Immich | `/api/*` `/.well-known/immich` |
+| **File Management** | |
+| Filebrowser | `/static/*` `/share/*` `/api/public/dl/*` `/api/public/share/*` |
+| **Notes & Knowledge Management** | |
+| Joplin Notes Server | `/api/*` `/shares/*` `/css/*` `/images/*` Always Deny - Path - `/login/*` (optional) |
+| Erugo | `/api/*` `/shares/*` `/build/*` `/get-logo` |
+| Memos | `/api/*` `/assets/*` `/explore*` `/memos.api.v1.*` `/auth/callback*` `/auth` `/site.webmanifest` `/logo.webp` `/full-logo.webp` `/android-chrome-192x192.png` |
+| Linkding | `/api/*` `/bookmarks/*` Always Deny - Path - `/admin/*` |
+| **Communication** | |
+| Matrix/Synapse (Clients) | `/_matrix/*` `/_synapse/client/*` |
+| Matrix/Synapse (Federation) | `/_matrix/*` |
+| **Notifications** | |
+| Gotify | `/version` `/message` `/application` `/client` `/stream` `/plugin` `/health` |
+| **Home Automation** | |
+| Home Assistant | `/api/*` `/auth/*` `/frontend_latest/*` `/lovelace/*` `/static/*` `/hacsfiles/*` `/local/*` `/manifest.json` `/sw-modern.js` |
+| n8n | `/webhook-test/*/webhook` `/webhook/*/webhook` |
+| **Project Management** | |
+| Jetbrains Youtrack | `/api/*` `/hub/api/*` |
+| **Genealogy** | |
+| Gramps Web | `/api/*` |
+| **Analytics** | |
+| Liwan | `/script.js` `/api/send` |
+| Umami | `/script.js` `/api/send` |
+
+
+ These rules are examples and may need to be adjusted based on your specific app configuration and version.
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Security_Keys.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Security_Keys.md
new file mode 100644
index 00000000..a61617af
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Security_Keys.md
@@ -0,0 +1,25 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Security Keys
+
+> Use security keys for passwordless login to your Pangolin account
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+You can log in with security keys, also known as passwordless login. On the login page, there is an option below the
+login button to Log in with security key.
+
+### Add a Security Key
+
+To add a security key, you must first be logged in. Then click your profile menu (top right) and select Add Security
+Keys. Follow the steps to add your key.
+
+Once a security key is added to your account, you can select the Continue with security key option the next time you log
+in.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Session_Length.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Session_Length.md
new file mode 100644
index 00000000..3b940587
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Session_Length.md
@@ -0,0 +1,33 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Session Length
+
+> Configure maximum session length and expiration policies for your organization
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+By default, Pangolin keeps extending a session indefinitely if a user is actively using it. If a user is not actively
+using the session, it will expire after 30 days.
+
+However, you can require users to log in at regular intervals by enforcing maximum session lengths on a per‑organization
+basis.
+
+### Configuration
+
+
+ Session length enforcement is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
+
+
+To enable session length enforcement, go to Organization Settings and set a maximum session length in the Security
+section. After this amount of time, users will be prompted to log back in to acquire a fresh session.
+
+* Session length enforcement is configured per organization.
+* Session length enforcement applies to both internal Pangolin users and users linked to external identity providers.
+* Users whose session has expired will see a prompt directing them to log in again before proceeding.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Blueprints.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Blueprints.md
new file mode 100644
index 00000000..6131d1e1
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Blueprints.md
@@ -0,0 +1,582 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Blueprints
+
+> Pangolin Blueprints are declarative configurations that allow you to define your resources and their settings in a
+> structured format
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Blueprints provide a way to define your Pangolin resources and their configurations in a structured, declarative format.
+This allows for easier management, version control, and automation of your resource setups.
+
+
+
+## Overview
+
+Pangolin supports two blueprint formats:
+
+1. **YAML Configuration Files**: Standalone configuration files
+2. **Docker Labels**: Configuration embedded in Docker Compose files
+
+
+ Some features in this documentation are marked with **(EE)**, indicating they are available only in [Enterprise Edition](/self-host/enterprise-edition) of Pangolin.
+
+
+## YAML Configuration Format
+
+YAML config can be applied using Docker labels, API, from a Newt site, or in the UI. *Application through a CLI tool is
+planned.*
+
+
+ You can apply blueprints directly through the Pangolin CLI.
+
+ ```bash theme={null}
+ pangolin apply blueprint --file /path/to/blueprint.yaml
+ ```
+
+
+
+
+ You can also apply blueprints directly in the Pangolin UI. Navigate to **Settings > Blueprints** and paste your YAML configuration into the provided text area.
+
+
+
+
+
+
+
+ Newt automatically discovers and applies blueprints defined in YAML format when passing the `--blueprint-file` argument. For example
+
+ ```bash theme={null}
+ newt --blueprint-file /path/to/blueprint.yaml
+ ```
+
+
+
+
+ You can also apply blueprints directly through the Pangolin API with an API key. [Take a look at the API documentation for more details.](https://api.pangolin.net/v1/docs/#/Organization/put_org__orgId__blueprint)
+
+PUT to `/org/{orgId}/blueprint` with a base64 encoded JSON body like the following:
+
+ ```json theme={null}
+ {
+ "blueprint": "base64-encoded-json-content"
+ }
+ ```
+
+[See this python example](https://github.com/fosrl/pangolin/blob/dev/blueprint.py)
+
+
+### Public Resources
+
+Public resources are used to expose HTTP, TCP, or UDP services through Pangolin. Below is an example configuration for
+public resources:
+
+```yaml theme={null}
+public-resources:
+ resource-nice-id-uno:
+ name: this is a http resource
+ protocol: http
+ full-domain: uno.example.com
+ host-header: example.com
+ tls-server-name: example.com
+ headers:
+ - name: X-Example-Header
+ value: example-value
+ - name: X-Another-Header
+ value: another-value
+ rules:
+ - action: allow
+ match: ip
+ value: 1.1.1.1
+ priority: 1
+ - action: deny
+ match: cidr
+ value: 2.2.2.2/32
+ priority: 2
+ - action: allow
+ match: asn
+ value: AS13335
+ priority: 3
+ - action: pass
+ match: path
+ value: /admin
+ targets:
+ - site: lively-yosemite-toad
+ hostname: localhost
+ method: http
+ port: 8000
+ - site: slim-alpine-chipmunk
+ hostname: localhost
+ path: /admin
+ path-match: exact
+ method: https
+ port: 8001
+ resource-nice-id-dos:
+ name: this is a raw resource
+ protocol: tcp
+ proxy-port: 3000
+ targets:
+ - site: lively-yosemite-toad
+ hostname: localhost
+ port: 3000
+```
+
+### Authentication Configuration
+
+
+ Authentication is off by default. You can enable it by adding the relevant fields in the `auth` section as shown in the example below.
+
+
+```yaml theme={null}
+public-resources:
+ secure-resource:
+ name: Secured Resource
+ protocol: http
+ full-domain: secure.example.com
+ auth:
+ pincode: 123456
+ password: your-secure-password
+ basic-auth:
+ user: asdfa
+ password: sadf
+ sso-enabled: true
+ sso-roles:
+ - Member
+ - Admin
+ sso-users:
+ - user@example.com
+ whitelist-users:
+ - admin@example.com
+```
+
+### Targets-Only Resources
+
+You can define simplified resources that contain only target configurations. This is useful for adding targets to
+existing resources or for simple configurations:
+
+```yaml theme={null}
+public-resources:
+ additional-targets:
+ targets:
+ - site: another-site
+ hostname: backend-server
+ method: https
+ port: 8443
+ - site: another-site
+ hostname: backup-server
+ method: http
+ port: 8080
+```
+
+
+ When using targets-only resources, the `name` and `protocol` fields are not required. All other resource-level validations are skipped for these simplified configurations.
+
+
+### Maintenance Page Configuration **(EE)**
+
+
+ This is an [Enterprise Edition](/self-host/enterprise-edition) (EE)-only feature. It allows you to display a maintenance page for a public resource when it's under maintenance or when targets are unhealthy.
+
+
+```yaml theme={null}
+public-resources:
+ production-app:
+ name: Production Application
+ protocol: http
+ full-domain: app.example.com
+ maintenance:
+ enabled: true
+ type: forced
+ title: Scheduled Maintenance
+ message: We are performing system upgrades to improve performance. The service will be back online shortly.
+ estimated-time: 2 hours
+ targets:
+ - site: my-site
+ hostname: app-server
+ method: https
+ port: 443
+```
+
+**Maintenance Types:**
+
+* **`forced`**: Always displays the maintenance page regardless of target health status
+* **`automatic`**: Displays the maintenance page only when all targets are unhealthy or the sites are offline
+
+### Private Resources
+
+Private resources define proxied resources accessible when connected via an client:
+
+```yaml theme={null}
+private-resources:
+ private-resource-nice-id-uno:
+ name: SSH Server
+ mode: host
+ destination: 192.168.1.100
+ site: lively-yosemite-toad
+ tcp-ports: "22,3389"
+ udp-ports: "*"
+ disable-icmp: false
+ roles:
+ - Developer
+ - DevOps
+ users:
+ - user@example.com
+ machines:
+ - machine-id-1
+ - machine-id-2
+ private-resource-nice-id-duo:
+ name: Internal Network
+ mode: cidr
+ destination: 10.0.0.0/24
+ site: lively-yosemite-toad
+ tcp-ports: "80,443,8000-9000"
+ udp-ports: "53,123"
+ disable-icmp: true
+ users:
+ - admin@example.com
+```
+
+## Docker Labels Format
+
+For containerized applications, you can define blueprints using Docker labels.
+
+
+ Blueprints will **continuously apply** from changes in the docker stack, newt restarting, or when viewing the resource in the dashboard.
+
+
+### Enabling Docker Socket Access
+
+To use Docker labels, enable the Docker socket when running Newt:
+
+```bash theme={null}
+newt --docker-socket /var/run/docker.sock
+```
+
+or using the environment variable:
+
+```bash theme={null}
+DOCKER_SOCKET=/var/run/docker.sock
+```
+
+### Docker Compose Example
+
+
+ The compose file will be the source of truth, any edits through the resources dashboard will be **overwritten** by the blueprint labels defined in the compose stack.
+
+
+```yaml theme={null}
+services:
+ newt:
+ image: fosrl/newt
+ container_name: newt
+ restart: unless-stopped
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
+ environment:
+ - PANGOLIN_ENDPOINT=https://app.pangolin.net
+ - NEWT_ID=h1rbsgku89wf9z3
+ - NEWT_SECRET=z7g54mbcwkglpx1aau9gb8mzcccoof2fdbs97keoakg2pp5z
+ - DOCKER_SOCKET=/var/run/docker.sock
+
+ nginx1:
+ image: nginxdemos/hello
+ container_name: nginx1
+ labels:
+ # Public Resource Configuration
+ - pangolin.public-resources.nginx.name=nginx
+ - pangolin.public-resources.nginx.full-domain=nginx.fosrl.io
+ - pangolin.public-resources.nginx.protocol=http
+ - pangolin.public-resources.nginx.headers[0].name=X-Example-Header
+ - pangolin.public-resources.nginx.headers[0].value=example-value
+ # Target Configuration - the port and hostname will be auto-detected
+ - pangolin.public-resources.nginx.targets[0].method=http
+ - pangolin.public-resources.nginx.targets[0].path=/path
+ - pangolin.public-resources.nginx.targets[0].path-match=prefix
+
+ nginx2:
+ image: nginxdemos/hello
+ container_name: nginx2
+ labels:
+ # Additional target for the same resource where the port and hostname are explicit
+ - pangolin.public-resources.nginx.targets[1].method=http
+ - pangolin.public-resources.nginx.targets[1].hostname=nginx2
+ - pangolin.public-resources.nginx.targets[1].port=80
+
+networks:
+ default:
+ name: pangolin_default
+```
+
+This will create a resource that looks like the following:
+
+
+
+
+
+### Docker Labels Considerations
+
+
+ When hostname and internal port are not explicitly defined in labels, Pangolin will automatically detect them from the container configuration.
+
+
+
+ If no site is specified in the labels, the resource will be assigned to the Newt site that discovered the container.
+
+
+
+ Configuration across different containers is automatically merged to form complete resource definitions. This allows you to distribute targets across multiple containers while maintaining a single logical resource.
+
+
+## Configuration Properties
+
+### Public Resources
+
+| Property | Type | Required | Description | Constraints |
+|-------------------|---------|--------------|-----------------------------------------|-------------------------------------------------------------------------------------------------------|
+| `name` | string | Conditional | Human-readable name for the resource | Required unless targets-only resource |
+| `protocol` | string | Conditional | Protocol type (`http`, `tcp`, or `udp`) | Required unless targets-only resource |
+| `full-domain` | string | HTTP only | Full domain name for HTTP resources | Required for HTTP protocol, must be unique |
+| `proxy-port` | number | TCP/UDP only | Port for raw TCP/UDP resources | Required for TCP/UDP, 1-65535, must be unique within public-resources |
+| `ssl` | boolean | No | Enable SSL/TLS for the resource | - |
+| `enabled` | boolean | No | Whether the resource is enabled | Defaults to `true` |
+| `host-header` | string | No | Custom Host header for requests | - |
+| `tls-server-name` | string | No | SNI name for TLS connections | - |
+| `headers` | array | No | Custom headers to add to requests | Each header requires `name` and `value` (min 1 char each) |
+| `rules` | array | No | Access control rules | See Rules section below |
+| `auth` | object | HTTP only | Authentication configuration | See Authentication section below |
+| `maintenance` | object | No | Maintenance page configuration **(EE)** | [Enterprise Edition](/self-host/enterprise-edition) only. See Maintenance Configuration section below |
+| `targets` | array | Yes | Target endpoints for the resource | See Targets section below |
+
+### Target Configuration
+
+| Property | Type | Required | Description | Constraints |
+|-----------------|---------|-----------|----------------------------------------------------------------------|--------------------------------------|
+| `site` | string | No | Site identifier where the target is located | - |
+| `hostname` | string | Yes | Target hostname or IP address | - |
+| `port` | number | Yes | Port on the target system | 1-65535 |
+| `method` | string | HTTP only | Protocol method (`http`, `https`, or `h2c`) | Required for HTTP protocol targets |
+| `enabled` | boolean | No | Whether the target is enabled | Defaults to `true` |
+| `internal-port` | number | No | Internal port mapping | 1-65535 |
+| `path` | string | HTTP only | Path prefix, exact path, or regex pattern | - |
+| `path-match` | string | HTTP only | Path matching type (`prefix`, `exact`, or `regex`) | - |
+| `rewrite-path` | string | No | Path to rewrite the request to | - |
+| `rewrite-match` | string | No | Rewrite matching type (`exact`, `prefix`, `regex`, or `stripPrefix`) | - |
+| `priority` | number | No | Target priority for load balancing | 1-1000, defaults to 100 |
+| `healthcheck` | object | No | Health check configuration for the target | See Health Check Configuration below |
+
+### Health Check Configuration
+
+Health checks can be configured for individual targets to monitor their availability. Add a `healthcheck` object to any
+target:
+
+```yaml theme={null}
+public-resources:
+ monitored-service:
+ name: Monitored Service
+ protocol: http
+ full-domain: service.example.com
+ targets:
+ - site: my-site
+ hostname: backend-server
+ method: https
+ port: 8443
+ healthcheck:
+ hostname: backend-server
+ port: 8443
+ enabled: true
+ path: /health
+ interval: 30
+ timeout: 5
+ method: GET
+ status: 200
+ headers:
+ - name: X-Health-Check
+ value: true
+```
+
+| Property | Type | Required | Description | Constraints |
+|----------------------|---------|----------|---------------------------------------|------------------------------------------|
+| `hostname` | string | Yes | Hostname for health check | - |
+| `port` | number | Yes | Port for health check | 1-65535 |
+| `enabled` | boolean | No | Whether health check is enabled | Defaults to `true` |
+| `path` | string | No | Path to check | - |
+| `scheme` | string | No | Protocol scheme for the health check | - |
+| `mode` | string | No | Health check mode | Defaults to `http` |
+| `interval` | number | No | Seconds between health checks | Defaults to 30 |
+| `unhealthy-interval` | number | No | Seconds between checks when unhealthy | Defaults to 30 |
+| `timeout` | number | No | Timeout in seconds | Defaults to 5 |
+| `headers` | array | No | Headers to send with health check | Array of objects with `name` and `value` |
+| `follow-redirects` | boolean | No | Whether to follow redirects | Defaults to `true` |
+| `method` | string | No | HTTP method for health check | Defaults to `GET` |
+| `status` | number | No | Expected HTTP status code | - |
+
+### Authentication Configuration
+
+Not allowed on TCP/UDP resources.
+
+| Property | Type | Required | Description | Constraints |
+|-------------------|---------|----------|--------------------------------------|---------------------------------------|
+| `pincode` | number | No | 6-digit PIN for access | Must be exactly 6 digits |
+| `password` | string | No | Password for access | - |
+| `basic-auth` | object | No | Basic authentication configuration | Requires `user` and `password` fields |
+| `sso-enabled` | boolean | No | Enable SSO authentication | Defaults to `false` |
+| `sso-roles` | array | No | Allowed SSO roles | Cannot include "Admin" role |
+| `sso-users` | array | No | Allowed SSO usernames | Must be valid usernames |
+| `whitelist-users` | array | No | Whitelisted user emails | Must be valid email addresses |
+| `auto-login-idp` | number | No | Automatic login identity provider ID | Must be a positive integer |
+
+### Maintenance Configuration **(EE)**
+
+
+ This is an [Enterprise Edition](/self-host/enterprise-edition) (EE)-only feature. It allows you to display a maintenance page for a public resource.
+
+
+The `maintenance` object can be added to any public resource to display a maintenance page to users:
+
+```yaml theme={null}
+public-resources:
+ my-service:
+ name: My Service
+ protocol: http
+ full-domain: service.example.com
+ maintenance:
+ enabled: true
+ type: automatic
+ title: Scheduled Maintenance
+ message: We are performing scheduled maintenance. Service will resume shortly.
+ estimated-time: 2 hours
+ targets:
+ - site: my-site
+ hostname: backend-server
+ method: https
+ port: 8443
+```
+
+| Property | Type | Required | Description | Constraints |
+|------------------|---------|----------|--------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| `enabled` | boolean | No | Whether the maintenance page is enabled | Defaults to `false` |
+| `type` | string | No | Maintenance type (`forced` or `automatic`) | `forced` always shows maintenance page; `automatic` shows only when all targets are unhealthy or sites offline |
+| `title` | string | No | Title text for the maintenance page | Maximum 255 characters, can be null |
+| `message` | string | No | Message text explaining the maintenance | Maximum 2000 characters, can be null |
+| `estimated-time` | string | No | Estimated time for maintenance completion | Maximum 100 characters, can be null |
+
+**Maintenance Types:**
+
+* **`forced`**: Always displays the maintenance page regardless of target health status
+* **`automatic`**: Displays the maintenance page only when all targets are unhealthy
+
+### Rules Configuration
+
+| Property | Type | Required | Description | Constraints |
+|------------|--------|----------|-------------------------------------------------|-------------------------------------------------------------------------------------|
+| `action` | string | Yes | Rule action (`allow`, `deny`, or `pass`) | - |
+| `match` | string | Yes | Match type (`cidr`, `path`, `ip`, or `country`) | - |
+| `value` | string | Yes | Value to match against | Format depends on match type. For `country` match, use `ALL` to match all countries |
+| `priority` | number | No | Processing priority of the rule. | If not set, the priority is auto-assigned sequentially based on the rule order. |
+
+
+ If no priority is defined, it is auto-assigned sequentially starting at 1 based on the rule order.
+ Each rule consumes one priority slot, including rules with manually assigned priorities.
+ Manual and auto-assigned priorities must be unique.
+
+
+### Private Resources
+
+These are resources used with Pangolin clients (e.g., SSH, RDP).
+
+| Property | Type | Required | Description | Constraints |
+|----------------|---------|----------|-----------------------------------------------|------------------------------------------------------------------------------------------------|
+| `name` | string | Yes | Human-readable name for the resource | 1-255 characters |
+| `mode` | string | Yes | Resource mode (`host` or `cidr`) | - |
+| `destination` | string | Yes | Target IP address, hostname, or CIDR block | For `host` mode: IP address or domain. For `cidr` mode: valid CIDR notation |
+| `site` | string | Yes | Site identifier where the resource is located | - |
+| `tcp-ports` | string | No | TCP port ranges to allow | Port range string (e.g., `"80,443,8000-9000"`), defaults to `"*"` (all ports) |
+| `udp-ports` | string | No | UDP port ranges to allow | Port range string (e.g., `"53,123,5000-6000"`), defaults to `"*"` (all ports) |
+| `disable-icmp` | boolean | No | Disable ICMP (ping) for this resource | Defaults to `false` |
+| `alias` | string | No | Fully qualified domain name alias | Must be a valid FQDN (e.g., example.com). Required when destination is a domain in `host` mode |
+| `roles` | array | No | Allowed SSO roles | Cannot include "Admin" role |
+| `users` | array | No | Allowed user emails | Must be valid email addresses |
+| `machines` | array | No | Allowed machine identifiers | Array of strings |
+
+## Validation Rules and Constraints
+
+### Resource-Level Validations
+
+1. **Targets-Only Resources**: A resource can contain only the `targets` field, in which case `name` and `protocol` are
+ not required.
+
+2. **Protocol-Specific Requirements**:
+ * **HTTP Protocol**: Must have `full-domain` and all targets must have `method` field
+ * **TCP/UDP Protocol**: Must have `proxy-port` and targets must NOT have `method` field
+ * **TCP/UDP Protocol**: Cannot have `auth` configuration
+
+3. **Alias Uniqueness**: `alias` values must be unique across all private resources within the same blueprint and in the
+ org
+
+4. **Domain Uniqueness**: `full-domain` values must be unique across all public resources
+
+5. **Proxy Port Uniqueness**: `proxy-port` values must be unique per protocol within public resources (e.g., TCP port
+ 3000 and UDP port 3000 can coexist)
+
+6. **Target Method Requirements**: When protocol is `http`, all non-null targets must specify a `method`
+
+## Common Validation Errors
+
+When working with blueprints, you may encounter these validation errors:
+
+### "Admin role cannot be included in sso-roles"
+
+The `Admin` role is reserved and cannot be included in the `sso-roles` array for authentication configuration.
+
+### "Duplicate 'full-domain' values found"
+
+Each `full-domain` must be unique across all public resources. If you need multiple resources for the same domain, use
+different subdomains or paths.
+
+### "Duplicate 'proxy-port' values found in public-resources"
+
+Port numbers in `proxy-port` must be unique per protocol within public-resources (e.g., you can't have two TCP resources
+using port 3000, but TCP port 3000 and UDP port 3000 can coexist).
+
+### "When protocol is 'http', all targets must have a 'method' field"
+
+All targets in HTTP proxy resources must specify whether they use `http`, `https`, or `h2c`.
+
+### "When protocol is 'tcp' or 'udp', targets must not have a 'method' field"
+
+TCP and UDP targets should not include the `method` field as it's only applicable to HTTP resources.
+
+### "When protocol is 'tcp' or 'udp', 'auth' must not be provided"
+
+Authentication is only supported for HTTP resources, not TCP or UDP.
+
+### "Resource must either be targets-only or have both 'name' and 'protocol' fields"
+
+Resources must either contain only the `targets` field (targets-only) or include both `name` and `protocol` for complete
+resource definitions.
+
+### "Duplicate 'alias' values found in private-resources"
+
+Alias values in private resources must be unique within the blueprint.
+
+### "Destination must be a valid IP address or valid domain AND alias is required"
+
+For private resources in `host` mode, the destination must be a valid IP address or domain. When using a domain, an
+`alias` field is required.
+
+### "Destination must be a valid CIDR notation for cidr mode"
+
+For private resources in `cidr` mode, the destination must be a valid CIDR notation (e.g., 10.0.0.0/24).
+
+### "Admin role cannot be included in roles"
+
+The `Admin` role is reserved and cannot be included in the `roles` array for private resource configuration.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Branding.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Branding.md
new file mode 100644
index 00000000..9633832b
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Branding.md
@@ -0,0 +1,328 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Branding
+
+> Learn how to customize the look your Pangolin dashboard and login pages with custom branding
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ Branding is only available in [Enterprise Edition](/self-host/enterprise-edition).
+
+
+Pangolin allows you to customize the appearance of your dashboard with your own branding, including colors, logos, and
+custom text for authentication pages. Branding is configured through the `privateConfig.yml` file.
+
+## Organization Branding
+
+In the settings of each organization, there is an Authentication Page branding settings section. These settings enable
+you to brand the resource authentication page and organization authentication page for that specific organization. These
+settings will override anything set in the configuration file.
+
+## Setting up Branding
+
+To get started, create a `privateConfig.yml` file next to your existing `config.yml` file:
+
+```yaml title="privateConfig.yml" theme={null}
+branding:
+ app_name: "MyApp"
+
+ logo:
+ light_path: "/branding/logo-light.svg"
+ dark_path: "/branding/logo-dark.svg"
+
+ colors:
+ light:
+ primary: "hsl(212, 65%, 35%)"
+ ring: "hsl(212, 65%, 35%)"
+ primary-foreground: "hsl(0 0% 98%)"
+ dark:
+ primary: "hsl(212, 65%, 45%)"
+ ring: "hsl(212, 65%, 35%)"
+ primary-foreground: "hsl(0 0% 98%)"
+```
+
+## Mounting Branding Assets
+
+For image assets like logos and backgrounds, you need to mount a volume to the Pangolin container to make them
+accessible to the application:
+
+```yaml title="docker-compose.yml" theme={null}
+volumes:
+ - ./config:/app/config
+ - ./branding:/app/public/branding
+```
+
+Your folder structure should look like this:
+
+```
+.
+├── config/
+│ ├── config.yml
+│ └── privateConfig.yml
+└── branding/
+ ├── logo-light.svg
+ ├── logo-dark.svg
+ └── favicon.ico
+```
+
+## Reference
+
+All branding configuration options are optional. Only specify the sections you want to customize.
+
+### Application Name
+
+
+ The name of your application that appears in various places throughout the UI.
+
+**Example**: `"MyApp"`
+
+
+### Favicon
+
+To customize the favicon, mount your favicon to `/app/public/favicon.ico` in the container.
+
+```yaml title="docker-compose.yml" theme={null}
+volumes:
+ - ./config:/app/config
+ - ./branding/favicon.ico:/app/public/favicon.ico
+```
+
+### Background Image
+
+
+ Path to a custom background image used on authentication pages.
+
+**Example**: `"/branding/backgrounds/bg.png"`
+
+
+ Requires mounting a volume to `/app/public`.
+
+
+
+### Colors
+
+
+ Custom color scheme that overrides the default Tailwind classes for shadcn components.
+
+Colors can be provided in OKLCH or HSL format for example and apply to both light and dark modes.
+
+**Color Reference**: Available color properties include `background`, `foreground`, `card`, `card-foreground`,
+`popover`, `popover-foreground`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `muted`,
+`muted-foreground`, `accent`, `accent-foreground`, `destructive`, `destructive-foreground`, `border`, `input`, `ring`,
+`radius`, and `chart-1` through `chart-5`.
+
+**Example**:
+
+ ```yaml theme={null}
+ colors:
+ light:
+ primary: "hsl(212, 65%, 35%)"
+ background: "hsl(212, 65%, 35%)"
+ foreground: "hsl(0 0% 98%)"
+ dark:
+ primary: "hsl(212, 65%, 45%)"
+ background: "hsl(212, 65%, 35%)"
+ foreground: "hsl(0 0% 98%)"
+ ```
+
+
+ For a complete list of Tailwind color classes used by shadcn components, refer to the [shadcn/ui documentation](https://ui.shadcn.com/docs/theming).
+
+
+
+### Logo
+
+
+ Logo configuration for different parts of the application.
+
+
+
+ Path to the logo image used in light mode.
+
+ **Example**: `"/branding/logo-light.svg"`
+
+
+
+ Path to the logo image used in dark mode.
+
+ **Example**: `"/branding/logo-dark.svg"`
+
+
+
+ Logo dimensions for authentication pages.
+
+
+
+ Logo width in pixels.
+
+ **Example**: `200`
+
+
+
+ Logo height in pixels.
+
+ **Example**: `80`
+
+
+
+
+
+ Logo dimensions for the navigation bar.
+
+
+
+ Logo width in pixels.
+
+ **Example**: `150`
+
+
+
+ Logo height in pixels.
+
+ **Example**: `60`
+
+
+
+
+
+
+
+### Footer
+
+
+ Custom footer links displayed at the bottom of the page.
+
+**Example**:
+
+ ```yaml theme={null}
+ footer:
+ - text: "Privacy Policy"
+ href: "https://example.com/privacy"
+ - text: "Terms of Service"
+ href: "https://example.com/terms"
+ ```
+
+
+ The display text for the footer link.
+
+
+
+ The URL or path for the footer link.
+
+
+
+### Hide Auth Page Footer
+
+
+ Hide the horizontal footer text that appears in the bottom layout of all authentication pages.
+
+**Default**: `false`
+
+
+### Login Page
+
+
+ Custom text for the login page.
+
+
+
+ The subtitle text displayed below the title.
+
+ **Example**: `"Sign in to continue to your account"`
+
+
+
+
+
+### Signup Page
+
+
+ Custom text for the signup page.
+
+
+
+ The subtitle text displayed below the title.
+
+ **Example**: `"Join us and get started today"`
+
+
+
+
+
+### Resource Auth Page
+
+
+ Configuration for the resource authentication page shown to users when accessing protected resources.
+
+
+
+ Whether to display the logo on the resource auth page.
+
+ **Default**: `true`
+
+
+
+ Whether to hide the "Powered by Pangolin" text on the resource auth page.
+
+ **Default**: `false`
+
+
+
+ The main title text displayed on the resource auth page.
+
+ **Example**: `"Access Restricted"`
+
+
+
+ The subtitle text displayed below the title.
+
+ **Example**: `"Please sign in to view this resource"`
+
+
+
+
+
+### Emails
+
+
+ Email customization settings.
+
+
+
+ Custom signature appended to sent emails.
+
+ **Example**: `"Best regards,\nThe MyApp Team"`
+
+
+ Use `\n` for line breaks in the signature.
+
+
+
+
+ Email color scheme.
+
+
+
+ Primary color for email elements.
+
+ **Example**: `"oklch(0.6717 0.1946 41.93)"`
+
+
+
+
+
+
+
+## Applying Changes
+
+
+ After creating or modifying `privateConfig.yml`, you must restart the Pangolin container for changes to take effect.
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Archiving_&_Blocking.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Archiving_&_Blocking.md
new file mode 100644
index 00000000..bd932d18
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Archiving_&_Blocking.md
@@ -0,0 +1,54 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Archiving & Blocking
+
+> Manage clients and block unwanted connections
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+## Blocking Devices
+
+To block a device that has been compromised or lost:
+
+1. Navigate to the device in your client list
+2. Click the Action Menu (three dots)
+3. Select **Block**
+
+When you block a device, it is immediately moved to a restricted list and loses access to all resources or the ability
+to connect.
+
+## Archiving Devices
+
+Devices cannot be permanently deleted from Pangolin. Instead, you can archive devices to remove them from your active
+client list.
+
+To archive a device:
+
+1. Navigate to the device in your client list
+2. Click the Action Menu (three dots)
+3. Select **Archive**
+
+### Why Archive Instead of Delete?
+
+Pangolin maintains a permanent audit trail of all devices that have accessed your resources. This ensures:
+
+* Block rules remain effective even for archived devices
+* Security logs and access history are preserved
+
+Archiving keeps your interface clean by hiding inactive or duplicate devices while maintaining the integrity of your
+security records.
+
+## Filtering
+
+You can filter your client list to show only active, blocked, or archived devices.
+
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Client_Credentials.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Client_Credentials.md
new file mode 100644
index 00000000..6daed64f
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Client_Credentials.md
@@ -0,0 +1,74 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Client Credentials
+
+> Understanding how client credentials work and how they can be rotated & regenerated
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+## Understanding Credentials
+
+Every machine client is provisioned with a unique identifier (ID), secret, and endpoint. The client uses the combination
+of these three to establish a secure, encrypted connection to the server.
+
+User devices use a special combination of credentials and temporary session tokens tied to the user account. Therefore,
+these credentials are obscured and can not be regenerated for user devices. To invalidate a user device, the user should
+logout via the client of choice.
+
+### ID
+
+Example: `ln8yqs6w85la5zg`
+
+The ID represents the client connection in the system. Every machine client has an ID.
+
+This value is not a secret and it is okay if made publically available.
+
+### Secret
+
+Example: `tfpwoc580jf1l1glfagix0o97p8kirjogdflqg604n0tr3to`
+
+The secret represents the "password" of the client. This secret must match the secret hashed in the system for the
+relevant ID.
+
+
+ This is a *secret*! Only share it with trusted people and be sure to store it safely and securely.
+
+
+When the client connects, it uses this secret as a first handshake with the server. The server then passes temporary
+session credentials back to the site before it can initiate a websocket connection. Once the websocket connection is
+established, ephemeral keys are used to establish tunnels using WireGuard.
+
+### Endpoint
+
+Example: `https://app.pangolin.net` or `https://pangolin.my-server.com`
+
+The endpoint is how the client knows which server to connect to. This is the fully qualified hostname of the Pangolin
+server (the URL you use to access the dashboard). For Pangolin cloud, the endpoint is `https://app.pangolin.net`. The
+client uses this endpoint ot establish a websocket connection and receive control messages from the server.
+
+## Rotating and Regenerating Credentials
+
+
+ This is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
+
+
+Client credentials can be regenerated. Regenerating credentials will completely invalidate the previous ID and secret.
+Use this feature if you have lost the secret and need to reset the credentials, or if you wish to rotate credentials on
+a regular basis for extra security.
+
+To regenerate credentials, visit Clients > Machines > Your Client > Credentials in the Pangolin admin dashboard.
+
+### Regenerate vs. Regenerate and Disconnect
+
+Regenerate simply recreates the credentials and invalidates the old ones. The client will remain connected until you
+restart it with the new credentials.
+
+Regenerate and Disconnect recreates the credentials and invalides the old ones. The client will instantly disconnect and
+will require you to restart it with the new credentials.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Client_Fingerprinting.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Client_Fingerprinting.md
new file mode 100644
index 00000000..82d25f4b
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Client_Fingerprinting.md
@@ -0,0 +1,87 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Client Fingerprinting
+
+> A summary of device information that is collected during the connection
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+## Device Fingerprinting
+
+Pangolin clients collect device fingerprinting information and can perform
+security posture checks to help determine trusted devices. This information is
+used to enforce security policies, audit device configurations, and monitor
+compliance with organizational requirements. Snapshots of device information are
+collected periodically on each platform when clients are connected.
+
+## Collected Fingerprint Information
+
+The following device attributes are collected on each device when available:
+
+* Username
+* Hostname
+* OS version
+* Kernel version
+* Architecture
+* Device model
+* Serial number
+
+## Available Posture Checks
+
+
+ Posture checks are only collected on Pangolin Cloud and self-hosted [Enterprise Edition](/self-host/enterprise-edition).
+
+
+Posture checks are also collected on each platform; this is device state that
+could potentially change, such as biometric availability, firewall settings, and
+other related information if it is available.
+
+Posture checks are supported on a per-platform basis.
+
+### Windows
+
+| Posture Check | What It Reports |
+|-----------------------|-------------------------------------------------------------------|
+| Hard drive encryption | Whether the system disk and other disks are encrypted (BitLocker) |
+| Firewall | If the firewall (Windows or third party) is enabled |
+| Antivirus | If antivirus (Windows or third party) is installed and active |
+| TPM availability | If a Trusted Platform Module is available |
+
+### macOS
+
+| Posture Check | What It Reports |
+|-----------------------------------|------------------------------------------|
+| Hard drive encryption | Whether the system disk is encrypted |
+| Biometric configuration | If Touch ID or Face ID is configured |
+| Firewall | If the macOS firewall is enabled |
+| System Integrity Protection (SIP) | Whether SIP is active |
+| Gatekeeper | Whether Gatekeeper is active |
+| Firewall stealth mode | Whether firewall stealth mode is enabled |
+| Auto updates | If automatic updates are enabled |
+
+### Linux
+
+| Posture Check | What It Reports |
+|-----------------------|--------------------------------------------------|
+| Hard drive encryption | If LUKS devices are detected on the system |
+| Firewall | Whether UFW, firewalld, or iptables are enabled |
+| AppArmor | If AppArmor is active |
+| SELinux | If SELinux is active |
+| TPM availability | If a Trusted Platform Module device is available |
+
+### iOS
+
+No posture checks are currently supported on iOS.
+
+### Android
+
+| Posture Check | What It Reports |
+|-----------------------|-------------------------------------|
+| Hard drive encryption | If File-Based Encryption is enabled |
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Configure_Clients.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Configure_Clients.md
new file mode 100644
index 00000000..b32315ab
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Configure_Clients.md
@@ -0,0 +1,384 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Configure Clients
+
+> Configure Olm for connecting to Pangolin clients
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+## GUI Clients (Mac, Windows, Android, iOS/iPadOS)
+
+Each respective client has a preferences window with all currently available configuration parameters. In your desktop
+client, click the menu bar or system tray icon, select "More" in the menu, and click "Preferences". In the mobile apps,
+navigate to the "Settings" screen.
+
+## Preferences
+
+The following preferences control how your client handles DNS resolution and network routing. Understanding these
+settings helps you configure Pangolin to work best with your network setup.
+
+#### Enable Aliases (Override DNS)
+
+When enabled, the client uses custom DNS servers to resolve internal resources and aliases. This overrides your system's
+default DNS settings. Queries that cannot be resolved as a Pangolin resource will be forwarded to your configured
+Upstream DNS Server.
+
+**When to use it**: This is required if you use aliases on resources in Pangolin. Aliases are friendly domain names
+assigned to private resources. Pangolin resolves these alias addresses over a private DNS server running in your client.
+
+**How it works**: The client loops back to itself to resolve the alias. This is why you may see your DNS server as an
+unfamiliar address (often like `100.90.128.x`) when this is enabled. When a request doesn't resolve to a Pangolin
+resource and is bound for another website (like `google.com`), it falls back to your configured upstream DNS server.
+
+#### DNS Over Tunnel
+
+When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly,
+you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server.
+
+**When to use it**: Tunnel DNS is used when you want to send all DNS queries over the tunnel to a private resource made
+available in Pangolin. For example, if you host a DNS server like Pi-hole, you could define a private resource for
+Pi-hole on your remote network. Then in the Pangolin client, you would enable Tunnel DNS and set the host of the Pi-hole
+private resource as the tunnel DNS server.
+
+**How it works**: When a request needs to be resolved, Pangolin sends it over the tunnel to the site of the private
+resource with your DNS server. You must enable DNS Over Tunnel and also set the upstream DNS server to your private DNS
+server.
+
+This requires aliases "override DNS" to be enabled as well. This is because the client must take control of your DNS
+settings to route queries through the tunnel to your private DNS server.
+
+
+ You cannot use an alias name for your DNS server. It must be the IP address of the resource. This is because it's pointing to the DNS server, so the DNS server can't resolve itself.
+
+
+#### Primary Upstream DNS
+
+This is the DNS server that will be used if Override DNS is enabled or DNS Over Tunnel is enabled. It serves as the
+primary resolver for queries that cannot be resolved as Pangolin resources. Not used when override DNS (aliases) are
+disabled.
+
+#### Secondary Upstream DNS
+
+This is a fallback DNS server that the system can use if the primary server is unavailable. Ordering and priority of the
+server is not guaranteed, but it provides redundancy for DNS resolution. Not used when override DNS (aliases) are
+disabled.
+
+## Android Battery Optimization
+
+To ensure Pangolin functions correctly in the background on Android devices, it's recommended to disable battery
+optimization for the app. This prevents the operating system from restricting its background activities, which could
+lead to disconnections.
+
+1. Open the **Settings** app on your Android device.
+2. Navigate to **Apps & notifications** (or simply **Apps** on some devices).
+3. Find and select the Pangolin app from the list of installed apps.
+4. Tap on **App battery usage**.
+5. Select **Allow background usage** and enable if disabled.
+6. From the options menu, choose **Unrestricted**.
+
+
+
+
+
+## Pangolin CLI
+
+Refer to the [documentation in the official repository](https://github.com/fosrl/cli/blob/main/docs/pangolin.md) for the
+available commands, default values, and more.
+
+## Olm (Advanced)
+
+
+
+ We recommend using the Pangolin CLI for both user and machine clients if you're looking for a CLI interface. Olm is the underlying client for the Pangolin CLI.
+
+
+Olm is a command-line client for connecting machine clients in Pangolin. You can configure it using command-line flags,
+environment variables, or a configuration file. Expand the section below to view all available configuration options.
+
+
+ ### Flags
+
+
+ Olm ID generated by Pangolin to identify the client.
+
+ **Example**: `31frd0uzbjvp721`
+
+
+
+ A unique secret used to authenticate the client ID with the websocket.
+
+ **Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6`
+
+
+ Keep this secret private and secure. It's used for authentication.
+
+
+
+
+ The endpoint where both Gerbil and Pangolin reside for websocket connections.
+
+ **Example**: `https://pangolin.example.com`
+
+
+
+ Organization ID to connect to.
+
+
+
+ User authentication token.
+
+
+
+ MTU for the internal WireGuard interface.
+
+ **Default**: `1280`
+
+
+
+ DNS server to use to resolve the endpoint.
+
+ **Default**: `8.8.8.8`
+
+
+
+ Upstream DNS server(s), comma-separated.
+
+ **Default**: `8.8.8.8:53`
+
+
+
+ The log level to use for Olm output.
+
+ **Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
+
+ **Default**: `INFO`
+
+
+
+ Interval for pinging the server.
+
+ **Default**: `3s`
+
+
+
+ Timeout for each ping.
+
+ **Default**: `5s`
+
+
+
+ Name of the WireGuard interface.
+
+ **Default**: `olm`
+
+
+
+ Enable API server for receiving connection requests.
+
+ **Default**: `false`
+
+
+
+ HTTP server address (e.g., ':9452').
+
+ **Default**: `:9452`
+
+
+
+ Unix socket path (or named pipe on Windows).
+
+ **Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
+
+
+
+ Disable hole punching.
+
+ **Default**: `false`
+
+
+
+ When enabled, the client uses custom DNS servers to resolve internal resources and aliases. This overrides your system's default DNS settings. Queries that cannot be resolved as a Pangolin resource will be forwarded to your configured Upstream DNS Server. (default true)
+
+ **Default**: `false`
+
+
+
+ When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly, you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server.
+
+ **Default**: `false`
+
+
+
+ Disable relay connections.
+
+ **Default**: `false`
+
+
+ ### Environment Variables
+
+ All CLI arguments can be set using environment variables as an alternative to command line flags. Environment variables are particularly useful when running Olm in containerized environments.
+
+
+ When both environment variables and CLI arguments are provided, CLI arguments take precedence.
+
+
+
+ Endpoint of your Pangolin server (equivalent to `--endpoint`)
+
+
+
+ Olm ID generated by Pangolin (equivalent to `--id`)
+
+
+
+ Olm secret for authentication (equivalent to `--secret`)
+
+
+
+ Organization ID to connect to (equivalent to `--org`)
+
+
+
+ User authentication token (equivalent to `--user-token`)
+
+
+
+ MTU for the internal WireGuard interface (equivalent to `--mtu`)
+
+ **Default**: `1280`
+
+
+
+ DNS server to use to resolve the endpoint (equivalent to `--dns`)
+
+ **Default**: `8.8.8.8`
+
+
+
+ Upstream DNS server(s), comma-separated (equivalent to `--upstream-dns`)
+
+ **Default**: `8.8.8.8:53`
+
+
+
+ Log level (equivalent to `--log-level`)
+
+ **Default**: `INFO`
+
+
+
+ Interval for pinging the server (equivalent to `--ping-interval`)
+
+ **Default**: `3s`
+
+
+
+ Timeout for each ping (equivalent to `--ping-timeout`)
+
+ **Default**: `5s`
+
+
+
+ Name of the WireGuard interface (equivalent to `--interface`)
+
+ **Default**: `olm`
+
+
+
+ Enable API server for receiving connection requests (equivalent to `--enable-api`)
+
+ Set to "true" to enable
+
+ **Default**: `false`
+
+
+
+ HTTP server address (equivalent to `--http-addr`)
+
+ **Default**: `:9452`
+
+
+
+ Unix socket path or Windows named pipe (equivalent to `--socket-path`)
+
+ **Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
+
+
+
+ Disable hole punching (equivalent to `--disable-holepunch`)
+
+ Set to "true" to disable
+
+ **Default**: `false`
+
+
+
+ Override system DNS settings (equivalent to `--override-dns`)
+
+ Set to "true" to enable
+
+ **Default**: `false`
+
+
+
+ Disable relay connections (equivalent to `--disable-relay`)
+
+ Set to "true" to disable
+
+ **Default**: `false`
+
+
+
+ Set to the location of a JSON file to load secret values
+
+
+ ### Loading secrets from files
+
+ You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs.
+
+ ```
+ $ cat ~/.config/olm-client/config.json
+ {
+ "id": "spmzu8rbpzj1qq6",
+ "secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
+ "endpoint": "https://app.pangolin.net",
+ "org": "",
+ "userToken": "",
+ "mtu": 1280,
+ "dns": "8.8.8.8",
+ "upstreamDNS": ["8.8.8.8:53"],
+ "interface": "olm",
+ "logLevel": "INFO",
+ "enableApi": false,
+ "httpAddr": "",
+ "socketPath": "/var/run/olm.sock",
+ "pingInterval": "3s",
+ "pingTimeout": "5s",
+ "disableHolepunch": false,
+ "overrideDNS": false,
+ "disableRelay": false,
+ "tlsClientCert": ""
+ }
+ ```
+
+ This file is also written to when olm first starts up. So you do not need to run every time with --id and secret if you have run it once!
+
+ Default locations:
+
+ * **macOS**: `~/Library/Application Support/olm-client/config.json`
+ * **Windows**: `%PROGRAMDATA%\olm\olm-client\config.json`
+ * **Linux/Others**: `~/.config/olm-client/config.json`
+
+ ### API
+
+ Olm can be started with a HTTP or socket API to configure and manage it. See the [API documentation](https://github.com/fosrl/olm/blob/main/API.md) for more details.
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Install_Clients.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Install_Clients.md
new file mode 100644
index 00000000..e1e72f00
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Install_Clients.md
@@ -0,0 +1,474 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Install Clients
+
+> Install native clients for Mac, Windows, and Linux
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+## Windows
+
+* [Pangolin for Windows Installer](https://pangolin.net/downloads/windows) - This is the official page to download the
+ latest installer file for Windows.
+* [All Versions](https://github.com/fosrl/windows/releases) - The releases section of this repository contains release
+ notes and download artifacts for the latest version and all older versions.
+
+### Installation Steps
+
+1. **Download and install the Pangolin client**
+
+ Download and install the Pangolin client using the official .msi installer from the download button above.
+
+2. **Launch Pangolin**
+
+ Open Pangolin from the Start menu or the shortcut on your Desktop.
+
+3. **Log in with your Pangolin account**
+
+ Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
+
+ * Click the Pangolin icon in the task bar's system tray and select Log in.
+
+## Mac
+
+* [Pangolin for macOS Installer](https://pangolin.net/downloads/mac) - This is the official page to download the latest
+ installer file for macOS.
+* [All Versions](https://github.com/fosrl/apple/releases) - The releases section of this repository contains release
+ notes and download artifacts for the latest version and all older versions.
+
+### Installation Steps
+
+1. **Download and install the Pangolin client**
+
+ Download and install the Pangolin client using the official .dmg installer from the download button above.
+
+ * Open the downloaded .dmg file
+ * Drag and drop Pangolin.app into your Applications folder
+
+2. **Launch Pangolin**
+
+ Open Pangolin from your Applications folder.
+
+3. **Install the VPN configuration**
+
+ Follow the Pangolin onboarding flow, which will guide you to install the Pangolin VPN configuration.
+
+ * Select Open System Settings on startup when it asks to install a network extension.
+ * In System Settings, under General > Login Items & Extension > By Category > Network Extensions, ensure that
+ Pangolin.app is toggled on.
+ * Select Allow when Pangolin asks to add a VPN configuration.
+
+4. **Log in with your Pangolin account**
+
+ Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
+
+ * Click the Pangolin icon in the menu bar and select Log in.
+
+## iOS/iPadOS
+
+* [Pangolin on the App Store](https://apps.apple.com/us/app/pangolin-client/id6757407406) - This is the official page to
+ download the latest Pangolin app for iOS and iPadOS.
+
+### Installation Steps
+
+1. **Download and install the Pangolin app**
+
+ Download and install the Pangolin app from the App Store using the link above.
+
+2. **Launch Pangolin**
+
+ Open the Pangolin app from your home screen.
+
+3. **Install the VPN configuration**
+
+ When prompted, allow Pangolin to add VPN configurations to your device.
+
+ You may be asked to enter your device passcode or use Face ID/Touch ID to authorize the VPN configuration.
+
+4. **Log in with your Pangolin account**
+
+ Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
+
+5. **Connect to Pangolin**
+
+ Tap the Connect button to establish a VPN connection.
+
+## Android
+
+* [Pangolin on Google Play](https://play.google.com/store/apps/details?id=net.pangolin.Pangolin) - This is the official
+ page to download the latest Pangolin app for Android devices.
+* [All Versions](https://github.com/fosrl/android/releases) - The releases section of this repository contains release
+ notes and download artifacts for the latest version and all older versions.
+
+### Installation Steps
+
+1. **Download and install the Pangolin app**
+
+ Download and install the Pangolin app from the Google Play Store using the link above.
+
+2. **Launch Pangolin**
+
+ Open the Pangolin app from your app drawer or home screen.
+
+3. **Log in with your Pangolin account**
+
+ Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
+
+4. **Connect to Pangolin**
+
+ Tap the Connect button to establish a VPN connection. On the first connection, you may be prompted to allow the VPN
+ connection.
+
+## Pangolin CLI (Linux)
+
+Pangolin CLI is the recommended way to run a client using a command line interface on Mac or Linux. Support for Windows
+is coming soon.
+
+Pangolin CLI supports running as user device with authentication or a machine client.
+
+### Quick Install (Recommended)
+
+Use this command to automatically install Pangolin CLI. It detects your system architecture automatically and always
+pulls the latest version, adding `pangolin` to your PATH:
+
+```bash theme={null}
+curl -fsSL https://static.pangolin.net/get-cli.sh | bash
+```
+
+### Manual Download
+
+Binaries for Linux and macOS are available in the [GitHub releases](https://github.com/fosrl/cli/releases) for ARM and
+AMD64 (x86\_64) architectures.
+
+Download and install manually:
+
+```bash theme={null}
+wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin
+```
+
+
+ Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/cli/releases) for the latest information.
+
+
+### Installation Steps
+
+1. **Download and install the Pangolin client**
+
+ Install Pangolin using the installation script:
+
+ ```bash theme={null}
+ curl -fsSL https://static.pangolin.net/get-cli.sh | bash
+ ```
+
+2. **Log in with your Pangolin account**
+
+ Log in on your Pangolin Cloud account or your self-hosted Pangolin instance:
+
+ ```bash theme={null}
+ pangolin login
+ ```
+
+3. **Start Pangolin**
+
+ When logged in as a Pangolin user, connect by running:
+
+ ```bash theme={null}
+ pangolin up
+ ```
+
+ To launch a machine client without logging in, use your client credentials:
+
+ ```bash theme={null}
+ pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
+ ```
+
+
+ The `--attach` flag runs the client in the foreground instead of spawning it as a background process.
+
+
+Pangolin CLI can be installed as a systemd service or run in a container. See the sections below for advanced setups.
+
+### Systemd Service (Pangolin CLI)
+
+Create a basic systemd service for Pangolin CLI:
+
+```ini title="/etc/systemd/system/pangolin-cli.service" theme={null}
+[Unit]
+Description=Pangolin CLI
+After=network.target
+
+[Service]
+ExecStart=/usr/local/bin/pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
+Restart=always
+User=root
+
+[Install]
+WantedBy=multi-user.target
+```
+
+
+ Make sure to move the binary to `/usr/local/bin/pangolin` before creating the service. Replace `{client_id}`, `{client_secret}`, and `{endpoint_url}` with your machine client credentials and endpoint.
+
+
+### Docker (Pangolin CLI)
+
+You can run Pangolin CLI with Docker Compose. For example, a service in your `docker-compose.yml` might look like this
+using environment variables (recommended):
+
+```yaml theme={null}
+services:
+ pangolin-cli:
+ image: fosrl/pangolin-cli:latest
+ container_name: pangolin-cli
+ restart: unless-stopped
+ network_mode: host
+ cap_add:
+ - NET_ADMIN
+ devices:
+ - /dev/net/tun:/dev/net/tun
+ environment:
+ - PANGOLIN_ENDPOINT=https://app.pangolin.net
+ - CLIENT_ID=5n52gnzfgl3tdox
+ - CLIENT_SECRET=wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9
+```
+
+You can also pass the CLI args to the container:
+
+```yaml theme={null}
+services:
+ pangolin-cli:
+ image: fosrl/pangolin-cli:latest
+ container_name: pangolin-cli
+ restart: unless-stopped
+ network_mode: host
+ cap_add:
+ - NET_ADMIN
+ devices:
+ - /dev/net/tun:/dev/net/tun
+ command:
+ - up
+ - --id
+ - "5n52gnzfgl3tdox"
+ - --secret
+ - "wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9"
+ - --endpoint
+ - https://app.pangolin.net
+ - --attach
+```
+
+**Docker Configuration Notes:**
+
+* `network_mode: host` brings the Pangolin CLI network interface to the host system, allowing the WireGuard tunnel to
+ function properly
+* `cap_add: - NET_ADMIN` is required to grant the container permission to manage network interfaces
+* `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating
+ WireGuard interfaces
+
+## Olm (Advanced)
+
+
+ Olm CLI is the most basic form of a client. All other clients implement Olm under the hood in some form.
+
+If you're looking for a CLI interface for a client, we recommend using Pangolin CLI where possible.
+
+Olm CLI is mainly only used for machine clients. Though the Pangolin CLI can also be used for machine clients, use
+Pangolin CLI if you expect to log in as a user.
+
+### Binary Installation (Linux)
+
+#### Quick Install (Recommended)
+
+Use this command to automatically install Olm. It detects your system architecture automatically and always pulls the
+latest version, adding Olm to your PATH:
+
+ ```bash theme={null}
+ curl -fsSL https://static.pangolin.net/get-olm.sh | bash
+ ```
+
+#### Windows
+
+If you would like to use Olm on Windows, wintun.dll is required. Please use latest installer
+from [GitHub releases](https://github.com/fosrl/olm/releases/latest).
+
+#### Manual Download
+
+Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/olm/releases) for
+ARM and AMD64 (x86\_64) architectures.
+
+Download and install manually:
+
+ ```bash theme={null}
+ wget -O olm "https://github.com/fosrl/olm/releases/download/{version}/olm_{architecture}" && chmod +x ./olm
+ ```
+
+
+ Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/olm/releases) for the latest information.
+
+
+### Running Olm
+
+Run Olm with the configuration from Pangolin:
+
+ ```bash theme={null}
+ olm \
+ --id 31frd0uzbjvp721 \
+ --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
+ --endpoint https://example.com
+ ```
+
+### Systemd Service
+
+Create a basic systemd service:
+
+ ```ini title="/etc/systemd/system/olm.service" theme={null}
+ [Unit]
+ Description=Olm
+ After=network.target
+
+ [Service]
+ ExecStart=/usr/local/bin/olm --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://example.com
+ Restart=always
+ User=root
+
+ [Install]
+ WantedBy=multi-user.target
+ ```
+
+
+ Make sure to move the binary to `/usr/local/bin/olm` before creating the service!
+
+
+### Docker
+
+You can also run it with Docker compose. For example, a service in your `docker-compose.yml` might look like this using
+environment vars (recommended):
+
+ ```yaml theme={null}
+ services:
+ olm:
+ image: fosrl/olm
+ container_name: olm
+ restart: unless-stopped
+ network_mode: host
+ cap_add:
+ - NET_ADMIN
+ devices:
+ - /dev/net/tun:/dev/net/tun
+ environment:
+ - PANGOLIN_ENDPOINT=https://example.com
+ - OLM_ID=31frd0uzbjvp721
+ - OLM_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
+ ```
+
+You can also pass the CLI args to the container:
+
+ ```yaml theme={null}
+ services:
+ olm:
+ image: fosrl/olm
+ container_name: olm
+ restart: unless-stopped
+ network_mode: host
+ cap_add:
+ - NET_ADMIN
+ devices:
+ - /dev/net/tun:/dev/net/tun
+ command:
+ - --id 31frd0uzbjvp721
+ - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
+ - --endpoint https://example.com
+ ```
+
+**Docker Configuration Notes:**
+
+* `network_mode: host` brings the olm network interface to the host system, allowing the WireGuard tunnel to function
+ properly
+* `cap_add: - NET_ADMIN` is required to grant the container permission to manage network interfaces
+* `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating
+ WireGuard interfaces
+
+### Windows Service
+
+On Windows, olm has to be installed and run as a Windows service. When running it with the cli args, it will attempt to
+install and run the service to function like a cli tool.
+
+Minimum Windows version: Windows 10
+
+#### Service Management Commands
+
+ ```
+ # Install the service
+ olm.exe install
+
+ # Start the service
+ olm.exe start
+
+ # Stop the service
+ olm.exe stop
+
+ # Check service status
+ olm.exe status
+
+ # Remove the service
+ olm.exe remove
+
+ # Run in debug mode (console output) with our without id & secret
+ olm.exe debug
+
+ # Show help
+ olm.exe help
+ ```
+
+Note running the service requires credentials in `%PROGRAMDATA%\olm\olm-client\config.json`.
+
+#### Service Configuration
+
+When running as a service, Olm will read configuration from environment variables or you can modify the service to
+include command-line arguments:
+
+1. Install the service: `olm.exe install`
+2. Set the credentials in `%PROGRAMDATA%\olm\olm-client\config.json`. Hint: if you run olm once with --id and --secret
+ this file will be populated!
+3. Start the service: `olm.exe start`
+
+#### Service Logs
+
+When running as a service, logs are written to:
+
+* Windows Event Log (Application log, source: "OlmWireguardService")
+* Log files in: `%PROGRAMDATA%\olm\logs\olm.log`
+
+You can view the Windows Event Log using Event Viewer or PowerShell:
+
+ ```powershell theme={null}
+ Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10
+ ```
+
+### Gotchas
+
+Olm creates a native tun interface. This usually requires sudo / admin permissions. Some notes:
+
+* **Windows**: Olm will run as a service. You can use the commands
+ described [Configure Client](/manage/clients/configure-client) to manage it. You can use this to run it in the
+ background if needed!
+* **LXC containers**: Need to be configured to allow tun access. On Proxmox see below.
+* **Linux**: May require root privileges or specific capabilities to create tun interfaces.
+* **macOS**: May require additional permissions for network interface creation.
+
+#### LXC Proxmox
+
+1. Create your LXC container.
+2. Go to the Resources tab of the container.
+3. Select Add. Then select Device Passthrough.
+4. On the Add Device prompt, enter dev/net/tun in the Device Path field and select Add.
+5. If the container is running, shut it down and start it up again.
+
+Once /dev/net/tun is available, the olm can run within the LXC.
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Understanding_Clients.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Understanding_Clients.md
new file mode 100644
index 00000000..41ce30a8
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Understanding_Clients.md
@@ -0,0 +1,98 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Understanding Clients
+
+> Create a client to connect to your Pangolin network from a remote computer
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+A client is a way to access resources on sites remotely and privately via a virtual private network. Clients are used
+with private resources to faciliate zero-trust network access.
+
+By default a client does not have access to any hosts on the local network of the site. Admins must explicitly define
+resources on the site and give specific users and roles access to the resources.
+
+Users must log in and connect from a Pangolin client available
+on [Windows, Mac, Linux, iOS/iPadOS, and Android](/manage/clients/install-client). Machines (automated systems and
+servers) connect with an ID and secret.
+
+## Client Types
+
+There are two types of clients: user devices and machines.
+
+
+
+ * Associated with a user in your Pangolin organization
+ * Requires login to connect (password, 2fa, etc)
+ * Available for download on Mac, Windows, and Linux
+
+
+
+ * Represent a server or automated system instead of a user
+ * Connect with an ID and secret
+ * Available in CLI form with Pangolin CLI
+
+
+
+### User Devices
+
+A user may download a client for their specific system. Before they can connect, they must select a Pangolin server to
+authenticate to using their provided Pangolin account. Users can log in as a Pangolin user or with your attached
+external identity provider.
+
+Examples include:
+
+* **SSH**: Admins and developers can connect with their client to specific hosts for SSH.
+* **RDP**: Users can connect to a remote host using familiar remote desktop software.
+
+Then, just like in the Pangolin dashboard, a user selects the organization to connect to. Once connected, all resources
+made available to the user in that organization become available via the tunnel.
+
+### Machines
+
+Machine clients are for servers and automated systems that are not associated with a specific user.
+
+Examples include:
+
+* **CICD**: Access remote resources like a database in an automated deployment pipeline.
+* **Servers**: Provide a VPS with access to a resource running in a different network.
+
+Though you may connect a server via a user account using a CLI client, we recommend you specifically use a machine
+client.
+
+Machine clients authenticate with an ID and secret string. These credentials are passed via arguments into one of the
+supported Pangolin CLI clients. They can be revoked and rotated.
+
+## Client Modalities
+
+Clients have two major operation modalities. A client will first attempt to hole punch before falling back to relaying.
+
+### Relaying
+
+Clients can relay traffic through a Pangolin server - through Gerbil specifically. Gerbil listens on UDP port 21820 for
+new WireGuard connections and forwards the packets down the Newt site tunnels to the right peers. This means your
+connections back to your site do not require firewall config and uses the existing NAT holepunching capabilities of
+Newt.
+
+### NAT Hole Punching
+
+NAT hole punching establishes a direct peer-to-peer connection between the client and site, bypassing the need to route
+traffic through the Pangolin server. The server coordinates the initial connection by helping both peers discover each
+other's network addresses, allowing them to establish a direct tunnel through their respective NATs and firewalls.
+
+If the site and client are unable to hole punch, they fall back to relaying through your Pangolin server.
+
+Take a look at [some things you can do to improve reliability](/manage/sites/configure-site#nat-traversal-tweaks) if you
+are not getting reliable hole punching.
+
+This should help to:
+
+* Increase performance (speed/bandwidth)
+* Reduce VPS transit costs
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Update_Clients.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Update_Clients.md
new file mode 100644
index 00000000..f10a57b3
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Update_Clients.md
@@ -0,0 +1,65 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Update Clients
+
+> Update your installed client to the latest version
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+## Mac and Windows
+
+### Automatic Updates (Recommended)
+
+The desktop clients for Mac and Windows will periodically check for updates in the background. When an update is
+available, they will request permission to update. However, you can manually check for updates in the menu bar or system
+tray menu, or by restarting the application.
+
+Once you accept the update, these clients will automatically download the latest version and replace itself on your
+computer.
+
+### Manual Updates
+
+* **Mac**: Find the latest version in the [GitHub releases](https://github.com/fosrl/apple/releases).
+* **Windows**: Find the latest version in the [GitHub releases](https://github.com/fosrl/windows/releases).
+
+You can download the latest installer files and restart the installation process to install the latest version.
+Visit [https://pangolin.net/downloads](https://pangolin.net/downloads) to find the latest official installers for your
+platform.
+
+## Pangolin CLI
+
+Find the latest version in the [GitHub releases](https://github.com/fosrl/cli/releases).
+
+### Automatic Updates (Recommended)
+
+If you already have Pangolin CLI installed, use the update command:
+
+```bash theme={null}
+pangolin update
+```
+
+Or you can re-run the installation script:
+
+```bash theme={null}
+curl -fsSL https://static.pangolin.net/get-cli.sh | bash
+```
+
+### Manual Updates
+
+Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/cli/releases) and replace
+your existing binary.
+
+```bash theme={null}
+wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin
+```
+
+
+ Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/cli/releases) for the latest information.
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Domains.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Domains.md
new file mode 100644
index 00000000..6cb6649c
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Domains.md
@@ -0,0 +1,121 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Domains
+
+> Learn how to configure domains for your Pangolin resources and understand the different domain types available
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Domains allow you to access your Pangolin resources through custom URLs. Pangolin supports different domain types
+depending on your deployment model and requirements.
+
+## Getting Started
+
+In Pangolin Cloud, a domain is not required. You can use our provided domain endings like `.hostlocal.app` or
+`.tunneled.to` for your resources.
+
+## Domain Types
+
+### Wildcard (A Records)
+
+This is the most common type used for Self-Hosted
+
+Wildcard domains allow you to use any subdomain under a specified base domain or the domain itself.
+
+* **Exact or Subdomains**: Both the base domain and any subdomains work (e.g., `example.com`, `app.example.com`,
+ `db.example.com`)
+* **A Records**: Uses A records pointing to Pangolin's IP addresses
+* **Simple**: Just pointed to the IP of your server
+
+More about self-hosted DNS and networking can be found in the [DNS & Networking Section](/self-host/dns-and-networking).
+
+### Domain Delegation (NS Records)
+
+Cloud & [Enterprise Edition](/self-host/enterprise-edition) Only
+
+Gives Pangolin full DNS control over your domain.
+
+Domain delegation is ideal when you want Pangolin to manage your entire domain and all its subdomains.
+
+* **Full Domain Control**: Includes the base domain and all subdomains
+* **NS Records**: Uses nameserver delegation for complete DNS management
+* **Automatic Subdomains**: All subdomains work automatically
+
+### Single Domain (CNAME Records)
+
+Cloud & [Enterprise Edition](/self-host/enterprise-edition) Only
+
+Single domain is limited to the exact domain you specify.
+
+CNAME domains are useful when your domain is already controlled by another provider but you still want to expose
+resources via Pangolin.
+
+* **Exact Domain Only**: Only the specific domain provided works
+* **CNAME Records**: Uses CNAME records pointing to Pangolin
+* **No Subdomains**: Subdomains will not work with CNAME domains
+* **External DNS**: Your domain remains controlled by your existing DNS provider
+
+## DNS Configuration
+
+### For Wildcard Domains
+
+When using wildcard domains, you'll need to add the following DNS records:
+
+**Example Wildcard Records:**
+
+```dns theme={null}
+Record 1:
+Type: A
+Name: *.example.com
+Value: 192.0.2.1
+
+Record 2:
+Type: A
+Name: example.com
+Value: 192.0.2.1
+```
+
+You then access your resources via subdomains like `app.example.com` or `db.example.com` or `example.com`.
+
+### For Domain Delegation
+
+
+ Some domain providers, namely Cloudflare, do not allow adding NS records for the root of your domain. This would prevent you from delegating all `*.example` to Pangolin. However, you can usually delegate everything after the first level, like `*.subdomain.example.com`. If your provider restricts you in this way, you could either move your domain, or use CNAME records for individual subdomains of the root domain.
+
+
+When using domain delegation, you'll need to update your domain's nameservers:
+
+**Example NS Records:**
+
+```dns theme={null}
+Type: NS
+Name: test.example.com
+Value: ns1.pangolin.net
+ ns2.pangolin.net
+ ns3.pangolin.net
+```
+
+### For Single Domain (CNAME)
+
+When using CNAME domains, you'll need to add CNAME records:
+
+**Example CNAME Records:**
+
+```dns theme={null}
+Record 1:
+Type: CNAME
+Name: test.example.com
+Value: 0nbn5rpcq4wthq6.cname.pangolin.net
+
+Record 2:
+Type: CNAME
+Name: _acme-challenge.test.example.com
+Value: _acme-challenge.0nbn5rpcq4wthq6.cname.pangolin.net
+```
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Add_Identity_Providers.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Add_Identity_Providers.md
new file mode 100644
index 00000000..e8e9a786
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Add_Identity_Providers.md
@@ -0,0 +1,130 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Add Identity Providers
+
+> Configure external identity providers for user authentication to resources and the organization
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Identity providers allow your users to log into Pangolin and Pangolin resources using their existing accounts from
+external identity systems like Google, Microsoft Azure, or Okta. Instead of creating separate Pangolin accounts, users
+can authenticate with their familiar work or personal credentials.
+
+Here is an example using Microsoft Azure Entra ID as SSO for Pangolin:
+
+
+
+**This feature is for you if:**
+
+* Your organization already uses an identity provider like Google Workspace, Microsoft Entra ID, Okta, or similar
+ systems
+* You want to centralize user management and avoid maintaining separate Pangolin accounts
+* You need to control who can access Pangolin resources through your existing user directory
+* You want users to access Pangolin using their existing credentials without creating new passwords
+
+
+
+
+
+## Identity Provider Types
+
+### Organization Identity Providers
+
+Organization identity providers are configured per organization and only apply to that specific organization. Each org
+can have its own identity providers, allowing for authentication methods based on the organization's needs.
+
+
+ Available in Pangolin Cloud and [Enterprise Edition](/self-host/enterprise-edition). For [Enterprise Edition](/self-host/enterprise-edition), you must set `app.identity_provider_mode: "org"` in the [private config file](/self-host/advanced/private-config-file#param-identity-provider-mode) `privateConfig.yml`.
+
+
+### Global Identity Providers
+
+Global identity providers are managed at the server level and not the individual organization. They can apply to all or
+some organizations on the server. This means you must define policies per organization to map users to specific
+organizations and roles within those organizations.
+
+
+ Global identity providers are the only supported method in Pangolin Community.
+
+
+## Supported Identity Providers
+
+### OAuth2/OIDC
+
+This can be used to connect to any external identity provider that supports the OpenID Connect protocol such as:
+
+* Authentik
+* Keycloak
+* Okta
+* Other OIDC-compliant providers
+
+### Google
+
+
+ Google IdP is only available in Pangolin Cloud or self-hosted [Enterprise Edition](/self-host/enterprise-edition) with organization identity providers. See above to enable.
+
+
+Easily set up Google Workspace authentication for your organization. Users can sign in with their Google accounts and
+access Pangolin resources using their existing Google credentials. Perfect for organizations already using Google
+Workspace for email, calendar, and other services.
+
+### Azure Entra ID
+
+
+ Azure Entra ID IdP is only available in Pangolin Cloud or self-hosted [Enterprise Edition](/self-host/enterprise-edition) with organization identity providers. See above to enable.
+
+
+Integrate with Microsoft's enterprise identity platform to allow users to authenticate using their Azure Active
+Directory accounts. Ideal for organizations using Microsoft 365 or other Azure services, providing seamless single
+sign-on across your Microsoft ecosystem.
+
+## How to Add an Identity Provider
+
+
+ When using global IDPs, identity providers are created and managed via the Server Admin UI rather than the organization settings.
+
+
+
+
+ In the Pangolin organization, select the "Identity Providers" section in the sidebar.
+
+
+
+ Click on the "Add Identity Provider" button.
+
+
+
+ Select the type of identity provider you want to add (OAuth2/OIDC, Google, Azure Entra ID).
+
+
+
+ Select the "Auto Provision Users" checkbox to automatically provision users and assign roles in Pangolin when they log in using an external identity provider. See [Auto Provision](/manage/identity-providers/auto-provisioning) for more information.
+
+ If this is disabled, you will need to pre-provision a user in Pangolin before they can log in using an external identity provider.
+
+
+
+
+ Fill in the required fields for the selected identity provider type.
+
+
+
+## Custom Login Page
+
+You can [configure a custom login page](/manage/access-control/login-page) for your organization to be served at a
+domain of your choice. The log in page for every resource will be served at this URL. Additionally, you can visit this
+url to log in to the organization itself to access the Pangolin dashboard. This is particularly useful for identity
+providers because it creates a place for your users to go to select the identity provider of choice to access the
+Pangolin dashboard.
+
+## Auto Provisioning
+
+See [Auto Provision](/manage/identity-providers/auto-provisioning) for more information on how to automatically
+provision users and assign orgs and roles in Pangolin when they log in using an external identity provider.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Auto_Provisioning.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Auto_Provisioning.md
new file mode 100644
index 00000000..40d94ef4
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Auto_Provisioning.md
@@ -0,0 +1,236 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Auto Provisioning
+
+> Automatically create and manage user accounts from external identity providers
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Auto provisioning is a feature that allows you to automatically create and manage user accounts in Pangolin when they
+log in using an external identity provider rather than pre-provisioning a user with a role. This is useful for
+organizations that want to streamline the onboarding process for new users and ensure that their user accounts are
+always up-to-date.
+
+You will be able to programmatically decide the roles and organizations for new users based on the information provided
+by the identity provider.
+
+## Enable Auto Provision
+
+Toggle the "Auth Provision Users" switch when creating or editing an identity provider.
+
+
+
+
+
+## What if Auto Provisioning is Disabled?
+
+If auto provision is disabled, organization admins will need to manually create the user accounts and select the role
+for each user. When creating a user, you can select the identity provider that the user will be associated with. A user
+will not be able to log in using the identity provider if a user is not pre-provisioned in the system.
+
+
+
+
+
+## Configuration Options
+
+## Selecting Roles
+
+You can choose between "Select a Role" and "Expression". Selecting a role will apply that role to all auto provisioned
+users. The expression will be evaluated against the token response from the IdP on each login (see examples below). You
+can always manually change the role of the user after they're provisioned.
+
+### Expressions
+
+Use JMESPath to map attributes from the identity provider to roles in Pangolin. See [JMESPath](https://jmespath.org/)
+for more information on how to use JMESPath.
+
+The expression will be matched against each organization. Meaning:
+
+* The result of the expression must return the exact string of the role name as it is defined in the organization.
+* If no matching role is found, the user will not be added to the organization.
+
+### Example: Role Selection
+
+**Expression:**
+
+
+ When entering in a string, JMESPatch requires it be surrounded by `'` (single quotes). See below:
+
+
+```
+contains(groups, 'admin') && 'Admin' || 'Member'
+```
+
+**Identity Provider Data:**
+
+```json theme={null}
+{
+ ...
+ "sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
+ "aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
+ "exp": 1745790819,
+ "iat": 1745789019,
+ "auth_time": 1745789019,
+ "email": "user@example.com",
+ "email_verified": true,
+ "name": "Example User",
+ "groups": [
+ "home-lab",
+ "admin"
+ ]
+}
+```
+
+This example will return the string "Admin". If the user is not a member of the "admin" group, it will return "Member".
+
+## Global Identity Providers
+
+After you create an IdP, on the edit page, you can manage organization policies via the "Organization Policies" tab. You
+can set default (fallback) policies, or define them on a per org basis.
+
+### How Organization Policies Are Evaluated
+
+It is helpful to think of the auto provisioning process as follows:
+
+
+
+ User successfully logs in using an identity provider.
+
+
+
+ Pangolin creates a user account for the user.
+
+
+
+ Pangolin will loop through each organization and evaluate the JMESPath expression for the organization. If the expression does not return true or the same ID as the current organization, the user will not be added to the organization.
+
+
+
+ For each organization, Pangolin will evaluate the JMESPath expression for the role. If no role is found with the exact name in that organization, the user will not be added to the organization.
+
+
+
+### Selecting Roles
+
+See above examples.
+
+### Selecting Organizations
+
+Use JMESPath to map attributes from the identity provider to organizations in Pangolin.
+See [JMESPath](https://jmespath.org/) for more information on how to use JMESPath.
+
+The expression will be matched against each organization. Meaning:
+
+* The result of the expression must return true or the organization ID as it is defined in the system.
+* If no matching organization is found, the user will not be added to the organization.
+
+You can insert the template variable `{{orgId}}` in the expression. This will be replaced with the organization ID when
+the expression is evaluated.
+
+### Example 1: Group-based Selection
+
+**Expression:**
+
+```
+contains(groups, 'home-lab')
+```
+
+**Identity Provider Data:**
+
+```json theme={null}
+{
+ ...
+ "sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
+ "aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
+ "exp": 1745790819,
+ "iat": 1745789019,
+ "auth_time": 1745789019,
+ "email": "user@example.com",
+ "email_verified": true,
+ "name": "Example User",
+ "groups": [
+ "home-lab",
+ "admin"
+ ]
+}
+```
+
+This example will return true since the user is a member of the "home-lab" group.
+
+### Example 2: Fixed Organization
+
+
+ When entering in a string, JMESPatch requires it be surrounded by `'` (single quotes). See below:
+
+
+**Expression:**
+
+```
+'home-lab'
+```
+
+**Identity Provider Data:**
+
+```json theme={null}
+{
+ ...
+ "sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
+ "aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
+ "exp": 1745790819,
+ "iat": 1745789019,
+ "auth_time": 1745789019,
+ "email": "user@example.com",
+ "email_verified": true,
+ "name": "Example User",
+ "groups": [
+ "home-lab",
+ "admin"
+ ]
+}
+```
+
+### Default (Fallback) Policy
+
+You can optionally configure a default policy for all organizations. This will be used if the organization does not have
+its own policy configured.
+
+This example will always return 'home-lab' meaning the user will always be added to the "home-lab" organization.
+
+### Example 1: Dynamic Organization Selection
+
+**Expression:**
+
+```
+contains(groups, '{{orgId}}')
+```
+
+**Identity Provider Data:**
+
+```json theme={null}
+{
+ ...
+ "sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
+ "aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
+ "exp": 1745790819,
+ "iat": 1745789019,
+ "auth_time": 1745789019,
+ "email": "user@example.com",
+ "email_verified": true,
+ "name": "Example User",
+ "groups": [
+ "home-lab",
+ "admin"
+ ]
+}
+```
+
+When Pangolin evaluates this expression against the "home-lab" organization, it will replace `{{orgId}}` with "
+home-lab". The result of the expression will return true since the user is a member of the "home-lab" group.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Azure_Entra_ID.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Azure_Entra_ID.md
new file mode 100644
index 00000000..f4d5dac2
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Azure_Entra_ID.md
@@ -0,0 +1,76 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Azure Entra ID
+
+> Configure Azure Entra ID Single Sign-On
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ Azure SSO is only available on Pangolin Cloud and [Enterprise Edition](/self-host/enterprise-edition) deployments. In [Enterprise Edition](/self-host/enterprise-edition), you must set `app.identity_provider_mode: "org"` in your [private config file](/self-host/advanced/private-config-file) `privateConfig.yml`.
+
+
+The following steps will integrate Microsoft SSO using the built in Azure Entra ID identity provider in Pangolin.
+
+
+
+
+ #### Create an App Registration
+
+In Azure, go to "Microsoft Entra ID". Under "Manage", click "App registrations". On the "All applications" tab, select "
+Register an application".
+
+Give it a name like "Pangolin", select your preferred supported account types, and click "Register". Leave the redirect
+URI blank for now; we will come back to this.
+
+#### Copy Credentials
+
+On the new app registration, select the "Overview" tab. Here, you can copy the "Application (client) ID" and save for
+later.
+
+Now we need to generate the client secret. Click "Add a certificate or secret". Then click "New client secret". Enter a
+description like "Pangolin credentials" and choose an expiration time. Note that once this secret expires, you will need
+to generate a new one and replace it in the Pangolin dashboard for the associated IdP.
+
+Copy the "Value" field and save for later.
+
+
+ We will revisit the **Authorised redirect URIs** field later, as we do not have Pangolin set up for Azure yet.
+
+
+
+## Creating an Azure Entra ID IdP in Pangolin
+
+In Pangolin, go to "Identity Providers" and click "Add Identity Provider". Select the Azure Entra ID provider option.
+
+
+
+
+
+In the OAuth2/OIDC Configuration, you'll need the following fields:
+
+
+ The application (client) ID from the "Overview" section of your app registration
+
+
+
+ The client secret value from the "Certificates and secrets" section of your app registration
+
+
+## Token Configuration
+
+When you're done, click "Create Identity Provider". Then, copy the Redirect URL in the "General" tab as you will now
+need this for your app registration.
+
+## Returning to Azure
+
+Lastly, you'll need to return to your app registration in order to add the redirect URI created by Pangolin. On the "
+Overview" tab, click "Add a Redirect URI". The click "Add a platform", and select "Web". Here, you can add the redirect
+URL from Pangolin and click "Configure". Your configuration should now be complete. You'll now need to add an external
+user to Pangolin, or if you have "Auto Provision Users" enabled, you can now log in using Azure SSO.
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Google.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Google.md
new file mode 100644
index 00000000..55f9d17f
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Google.md
@@ -0,0 +1,89 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Google
+
+> Configure Google Single Sign-On
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ Google SSO is only available on Pangolin Cloud and [Enterprise Edition](/self-host/enterprise-edition) deployments. In [Enterprise Edition](/self-host/enterprise-edition), you must set `app.identity_provider_mode: "org"` in your [private config file](/self-host/advanced/private-config-file#param-use-org-only-idp) `privateConfig.yml`.
+
+
+The following steps will integrate Google SSO using the built in Google identity provider in Pangolin.
+
+
+
+
+ [Create a new Project](https://console.cloud.google.com/projectcreate), or use an [existing Project](https://console.developers.google.com/) you've already created in the Google Developers Console. Setting the organization isn't required, unless you intend to use SSO for [more than 100 users](https://support.google.com/cloud/answer/13464323) externally (not via Google Workspace).
+
+Once created, or you've opened an existing Project, you may be on the project dashboard, where you will need to open the
+sidebar. If you are on the welcome page, continue by
+selecting [OAuth consent screen](https://console.cloud.google.com/auth/overview) in "APIs and services".
+
+You should see that Google Auth Platform is not configured. Press "Get started" and fill in the relevant information,
+such as your "App name" and "User support email". These will be visible when the user is authenticating.
+
+After continuing, you can select an "Audience". If you are using Pangolin for friends and family, use the "External"
+Audience. You can only have 100 users authenticated with a "Testing" status.
+
+
+ Depending on your use case, you may want to use the "Internal" Audience if you are utilising Google Workspace SSO.
+
+
+Once completed, you will then need to open the [Branding](https://console.cloud.google.com/auth/branding) tab.
+
+Locate "Authorized domains", then press "Add domain" to add an authorized domain. You'll need to authorize the top
+private (root) domain here, such as `example.com`. Your SSO *may* function without an authorized domain, though setting
+this field should guarantee functionality.
+
+### Creating an OAuth client ID in your Project
+
+Go to the [Clients](https://console.cloud.google.com/auth/clients) tab, and click "Create client" below the top bar.
+
+For "Application type", select `Web application`. Any "Name" can be set. Leave "Authorised JavaScript origins" and "
+Authorised redirect URIs" empty.
+
+
+ We will revisit the "Authorised redirect URIs" field later, as we do not have Pangolin set up for Google yet.
+
+
+After hitting "Create", you will be able to see the "Client ID" and "Client secret", you may want to copy these
+somewhere as these will be needed momentarily, though they will still be accessible in the future.
+
+
+## Creating a Google IdP in Pangolin
+
+In Pangolin, go to "Identity Providers" and click "Add Identity Provider". Select the Google provider option.
+
+
+
+
+
+In the "Google Configuration", you'll need the following fields:
+
+
+ The Client ID from your Web application client.
+
+
+
+ The Client secret from your Web application client.
+
+
+## Token Configuration
+
+When you're done, click "Create Identity Provider". Then, copy the Redirect URL in the "General" tab as you will now
+need this for your **Web application client**.
+
+## Returning to Google Developers Console
+
+Lastly, you'll need to return to your "Web application client" in order to add the redirect URI created by Pangolin. Add
+the URI to "Authorized redirect URIs", then hit "Save"! Your configuration should now be complete. You'll now need to
+add an external user to Pangolin, or if you have "Auto Provision Users" enabled, you can now log in using Google SSO.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/OAuth2-OIDC.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/OAuth2-OIDC.md
new file mode 100644
index 00000000..12a4a3d6
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/OAuth2-OIDC.md
@@ -0,0 +1,79 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# OAuth2/OIDC
+
+> Configure OpenID Connect identity provider for external authentication
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+This identity provider follows the OpenID Connect protocol. This means that it can be used to connect to any external
+identity provider that supports the OpenID Connect protocol such as Authentik, Keycloak, Okta, etc.
+
+## Creating a Generic OAuth2/OIDC IdP in Pangolin
+
+In Pangolin, go to "Identity Providers" and click "Add Identity Provider". Select the OAuth2/OIDC provider option.
+
+
+
+
+
+In the OAuth2/OIDC Configuration, you'll need the following fields:
+
+
+ The client identifier provided by your identity provider.
+
+
+
+ The client secret provided by your identity provider.
+
+
+
+ The authorization endpoint URL from your identity provider.
+
+
+
+ The token endpoint URL from your identity provider.
+
+
+## Token Configuration
+
+Use JMESPath to select attributes from the claims token. See [JMESPath](https://jmespath.org/) for more information on
+how to use JMESPath.
+
+Determine how to access information from the claims token returned by the identity provider. This is used to map the
+user information from the identity provider to the user information in Pangolin.
+
+
+ This must be unique for each user within an identity provider.
+
+**Example**: `sub` or `user_id`
+
+
+
+ Path to the user's email address in the claims token.
+
+**Example**: `email`
+
+
+
+ Path to the user's display name in the claims token.
+
+**Example**: `name` or `preferred_username`
+
+
+
+ The scopes to request from the identity provider (not JMESPath; must be space-delimited strings).
+
+**Default**: `openid profile email`
+
+
+ Generally, `openid profile email` is sufficient for most use cases.
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Pocket_ID.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Pocket_ID.md
new file mode 100644
index 00000000..17344ed7
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Pocket_ID.md
@@ -0,0 +1,94 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Pocket ID
+
+> Configure Pocket ID Single Sign-On using OpenID Connect
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+The following steps will integrate Pocket ID with Pangolin SSO using OpenID Connect (OIDC).
+
+## Prerequisites
+
+Before you can start, you'll need to have Pocket ID accessible and ensure it's not secured with Pangolin SSO.
+
+### Creating an OIDC Client in Pocket ID
+
+In Pocket ID, create a new OIDC Client.
+
+
+
+ Set the name to something memorable (eg. Pangolin).
+
+
+
+ Leave blank or set a placeholder. We will come back to this step after creating the IdP and we know the redirect URL.
+
+
+
+ All other values can be kept as default.
+
+
+
+
+ The callback URL is displayed in the IdP settings after you create the IdP in Pangolin.
+
+
+After you have created the OIDC Client, take note of the following fields from the top of the page (click "Show more
+details" to see all of them):
+
+* **Client ID**
+* **Client secret**
+* **Authorization URL**
+* **Token URL**
+
+## Configuring Identity Providers in Pangolin
+
+In Pangolin, go to “Identity Providers” and click “Add Identity Provider”. Select the OAuth2/OIDC provider option.
+
+"Name" should be set to something memorable (eg. Pocket ID). The "Provider Type" should be set to the default
+`OAuth2/OIDC`.
+
+### OAuth2/OIDC Configuration (Provider Credentials and Endpoints)
+
+In the OAuth2/OIDC Configuration, you'll need the following fields:
+
+
+ The Client ID from your Pocket ID OIDC client.
+
+
+
+ The Client secret from your Pocket ID OIDC client.
+
+
+
+ The Authorization URL from your Pocket ID OIDC client.
+
+
+
+ The Token URL from your Pocket ID OIDC client.
+
+
+## Token Configuration
+
+You should leave all of the paths default. In the "Scopes" field, add `openid profile email`.
+
+
+ Set the "Identifier Path" to `preferred_username` for Pocket ID integration.
+
+
+When you're done, click "Create Identity Provider"! Then, copy the Redirect URL in the "General" tab as you will now
+need this for your Pocket ID OIDC client.
+
+## Returning to Pocket ID
+
+Lastly, you'll need to return to your Pocket ID OIDC client in order to add the redirect URI created by Pangolin. Add
+the URI to "Callback URLs", then save your changes! Your configuration should now be complete. You'll now need to add an
+external user to Pangolin, or if you have "Auto Provision Users" enabled, you can now log in using Pocket ID SSO.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Zitadel.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Zitadel.md
new file mode 100644
index 00000000..b1e09e6b
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Identity_Providers/Zitadel.md
@@ -0,0 +1,113 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Zitadel
+
+> Configure Zitadel Single Sign-On using OpenID Connect
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+The following steps will integrate Zitadel with Pangolin SSO using OpenID Connect (OIDC).
+
+## Prerequisites
+
+These instructions assume you have a working Zitadel organization and project setup already.
+
+### Creating an Application in Zitadel
+
+You need to configure an application in Zitadel:
+
+
+
+ Open an existing project and in `Applications` click `New`.
+
+
+
+ Set the name to something memorable (eg. Pangolin).
+
+
+
+ For `Type of application` choose `Web`.
+
+
+
+ For `Authentication Method` choose `Code`.
+
+
+
+ Leave `Redirect URIs` blank for now. We'll come back to this once the IdP is created.
+
+
+
+
+ When you click create, you'll be shown the `ClientSecret` and `ClientId`. Make sure to save these somewhere secure - you won't be able to see the Client Secret again.
+
+
+
+
+ Click `Token settings` then change `Auth Token Type` to `JWT` and check the `User Info inside ID Token` box finally hit `Save`.
+
+
+
+ Still in `Token settings`, check the box for `Include user's roles in the ID Token`. This enables Zitadel to include necessary user profile claims (including `preferred_username`) in the ID token, which Pangolin requires for user identification.
+
+
+
+ Open `URLs` and make note of:
+
+ * `Authorization Endpoint`
+ * `Token Endpoint`
+
+
+
+
+## Configuring Identity Providers in Pangolin
+
+In Pangolin, go to “Identity Providers” and click “Add Identity Provider”. Select the OAuth2/OIDC provider option.
+
+"Name" should be set to something memorable (eg. Zitadel). The "Provider Type" should be set to the default
+`OAuth2/OIDC`.
+
+### OAuth2/OIDC Configuration (Provider Credentials and Endpoints)
+
+In the OAuth2/OIDC Configuration, you'll need the following fields:
+
+
+ The Client ID from your Zitadel application.
+
+
+
+ The Client Secret from your Zitadel application.
+
+
+
+ Use the `Authorization Endpoint` from your Zitadel application.
+
+
+
+ Use the `Token Endpoint` from your Zitadel application.
+
+
+## Token Configuration
+
+You should leave all of the paths default. In the "Scopes" field, add `openid profile email`.
+
+
+ Set the "Identifier Path" to `preferred_username` for Zitadel integration.
+
+
+When you're done, click "Create Identity Provider"! Then, copy the Redirect URL in the "General" tab as you will now
+need this for your **Zitadel application**.
+
+## Returning to Zitadel
+
+Lastly, you need to edit your `Redirect Settings` in your Zitadel application. Add the URL you copied to the
+`Redirect URIs`, then hit the `+` button and finally `Save`. Your configuration should now be complete. You'll now need
+to add an external user] to Pangolin, or if you have "Auto Provision Users" enabled, you can now log in using Zitadel
+SSO.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Integration_API.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Integration_API.md
new file mode 100644
index 00000000..5d8fd01a
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Integration_API.md
@@ -0,0 +1,115 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Integration API
+
+> Learn how to use Pangolin's REST API to automate and script operations with fine-grained permissions
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ Pangolin is in heavy development. The REST API routes and behavior may include breaking changes between updates. We will do our best to document large changes.
+
+
+The API is REST-based and supports many operations available through the web interface. Authentication uses Bearer
+tokens, and you can create multiple API keys with specific permissions for different use cases.
+
+For Pangolin Community Edition, the integration API must be enabled. Check
+out [the documentation](/self-host/advanced/integration-api) for how to enable the integration API.
+
+## Authentication
+
+All API requests require authentication using a Bearer token in the Authorization header:
+
+
+ ```bash cURL theme={null}
+ curl -H "Authorization: Bearer YOUR_API_KEY" \
+ https://api.example.com/v1/
+ ```
+
+ ```javascript JavaScript theme={null}
+ const response = await fetch('https://api.example.com/v1/endpoint', {
+ headers: {
+ 'Authorization': `Bearer ${apiKey}`
+ }
+ });
+ ```
+
+ ```python Python theme={null}
+ import requests
+
+ headers = {'Authorization': f'Bearer {api_key}'}
+ response = requests.get('https://api.example.com/v1/endpoint', headers=headers)
+ ```
+
+
+
+## API Key Types
+
+Pangolin supports two types of API keys with different permission levels:
+
+### Organization API Keys
+
+Organization API keys are created by organization admins and have limited scope to perform actions only in that
+organization.
+
+### Root API Keys
+
+Root API keys have some extra permissions and can execute operations across orgs. They are only available in the
+Community Edition of Pangolin:
+
+
+ Root API keys have elevated permissions and should be used carefully. Only create them when you need server-wide access.
+
+
+## Creating API Keys
+
+
+
+ Navigate to your admin panel:
+
+ * **Organization keys**: Organization → API Keys
+ * **Root keys**: Server Admin → API Keys (self-hosted only)
+
+
+
+
+ Click "Create API Key" and provide a descriptive name for the key.
+
+
+
+ Select the specific permissions your API key needs from the permissions selector.
+
+
+
+
+
+
+
+
+ Copy the generated API key immediately. It won't be shown again.
+
+
+ Store API keys securely and never commit them to version control. Use environment variables or secure secret management.
+
+
+
+
+
+## API Documentation
+
+View the Swagger docs here: [https://api.pangolin.net/v1/docs](https://api.pangolin.net/v1/docs).
+
+Interactive API documentation is available through Swagger UI:
+
+
+
+
+
+For self-hosted Pangolin, access the documentation at `https://api.your-domain.com/v1/docs`.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Logs_&_Analytics/Access_Logs.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Logs_&_Analytics/Access_Logs.md
new file mode 100644
index 00000000..df7002e5
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Logs_&_Analytics/Access_Logs.md
@@ -0,0 +1,66 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Access Logs
+
+> Access logs are a record of each access attempt to a Pangolin resource
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Access logs provide detailed information about each access attempt made to your Pangolin resources. These logs help you
+monitor and analyze user activity each time they attempt to authenticate.
+
+
+ Access logs are an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
+
+
+## What are Access Logs?
+
+Access logs capture authentication events when users or API keys attempt to access a resource. They record whether the
+authentication was successful or failed, along with contextual information about the attempt. These logs are useful for:
+
+* Monitoring authentication patterns and login attempts
+* Tracking which users are accessing which resources
+* Identifying failed authentication attempts for security analysis
+* Understanding geographic distribution of access attempts
+* Analyzing user agent and device information
+
+
+
+
+
+Make sure to enable access logs in the org settings
+
+## Access Log Fields
+
+Each access log entry contains the following fields:
+
+| Field | Type | Description |
+|--------------|---------|-------------------------------------------------------------------------|
+| `timestamp` | number | Unix timestamp (in seconds) when the access attempt occurred |
+| `action` | boolean | Whether the access was allowed (`true`) or denied (`false`) |
+| `type` | string | The type of authentication event (e.g., "login", "password", "pincode") |
+| `actorType` | string | The type of actor making the access attempt ("user" or "apiKey") |
+| `actor` | string | The display name of the actor (username or API key name) |
+| `actorId` | string | The unique identifier for the actor (user ID or API key ID) |
+| `resourceId` | number | The ID of the resource being accessed (if applicable) |
+| `ip` | string | The IP address of the client making the access attempt |
+| `location` | string | The geographic location (country code) based on IP address |
+| `userAgent` | string | The user agent string of the client browser or application |
+| `metadata` | string | Additional contextual information in JSON format |
+
+## Log Retention
+
+Access log retention is controlled by the organization setting. By default, access logs are retained for 0 days (
+disabled).
+
+## Exporting
+
+Logs can be exported into CSV format for external analysis and archival. Logs can be exported from the table view in the
+Pangolin dashboard or via the Pangolin API. When exporting, you can specify date ranges and filters to narrow down the
+logs you need.
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Logs_&_Analytics/Action_Logs.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Logs_&_Analytics/Action_Logs.md
new file mode 100644
index 00000000..bdece09d
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Logs_&_Analytics/Action_Logs.md
@@ -0,0 +1,63 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Action Logs
+
+> Action logs are a record of each event taken by users in the Pangolin system
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Action logs provide an audit trail of administrative actions and configuration changes made within your Pangolin
+organization. These logs help you track who made what changes and when.
+
+
+ Action logs are an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
+
+
+## What are Action Logs?
+
+Action logs capture administrative events and configuration changes performed by users or API keys in the Pangolin
+dashboard. They record management operations such as creating resources, modifying settings, managing users, and other
+organizational changes. These logs are useful for:
+
+* Maintaining an audit trail of configuration changes
+* Tracking administrative actions for compliance
+* Identifying who made specific changes to your infrastructure
+* Troubleshooting configuration issues by reviewing recent changes
+* Meeting security and compliance requirements
+
+
+
+
+
+Make sure to enable access logs in the org settings
+
+## Action Log Fields
+
+Each action log entry contains the following fields:
+
+| Field | Type | Description |
+|-------------|--------|-------------------------------------------------------------------------------------------------------|
+| `timestamp` | number | Unix timestamp (in seconds) when the action was performed |
+| `action` | string | The specific action that was performed (e.g., "createResource", "updateUser", "deleteTarget") |
+| `actorType` | string | The type of actor performing the action ("user" or "apiKey") |
+| `actor` | string | The display name of the actor (username or API key name) |
+| `actorId` | string | The unique identifier for the actor (user ID or API key ID) |
+| `metadata` | string | Additional contextual information about the action in JSON format (often contains request parameters) |
+
+## Log Retention
+
+Action log retention is controlled by the organization settings. By default, action logs are retained for 0 days (
+disabled).
+
+## Exporting
+
+Logs can be exported into CSV format for external analysis and archival. Logs can be exported from the table view in the
+Pangolin dashboard or via the Pangolin API. When exporting, you can specify date ranges and filters to narrow down the
+logs you need.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Logs_&_Analytics/Request_Logs.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Logs_&_Analytics/Request_Logs.md
new file mode 100644
index 00000000..ce1acce2
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Logs_&_Analytics/Request_Logs.md
@@ -0,0 +1,73 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Request Logs
+
+> Request logs are a record of each HTTP request to a resource
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Request logs provide detailed information about every HTTP request made to your Pangolin resources. These logs capture
+both successful and denied requests along with comprehensive request metadata.
+
+## What are Request Logs?
+
+Request logs capture every HTTP request that passes through Pangolin's reverse proxy, including the request details, the
+decision made (allow or deny), and the reason for that decision. These logs are useful for:
+
+* Monitoring traffic patterns and request volumes
+* Debugging access issues and rule configurations
+* Analyzing API usage and endpoint popularity
+* Understanding geographic distribution of requests
+* Identifying potential security threats or unusual traffic patterns
+* Troubleshooting connectivity and routing issues
+
+
+
+
+
+## Request Log Fields
+
+Each request log entry contains the following fields:
+
+| Field | Type | Description |
+|----------------------|---------|--------------------------------------------------------------------------------|
+| `timestamp` | number | Unix timestamp (in seconds) when the request was made |
+| `action` | boolean | Whether the request was allowed (`true`) or denied (`false`) |
+| `reason` | number | Numeric code indicating the reason for the decision |
+| `actorType` | string | The type of actor making the request ("user", "apiKey", or null for anonymous) |
+| `actor` | string | The display name of the authenticated actor (username or API key name) |
+| `actorId` | string | The unique identifier for the authenticated actor |
+| `resourceId` | number | The ID of the resource that received the request |
+| `ip` | string | The IP address of the client making the request |
+| `location` | string | The geographic location (country code) based on IP address |
+| `userAgent` | string | The user agent string of the client browser or application |
+| `metadata` | string | Additional contextual information in JSON format |
+| `headers` | string | HTTP request headers in JSON format |
+| `query` | string | URL query parameters in JSON format |
+| `originalRequestURL` | string | The full original URL of the request |
+| `scheme` | string | The protocol scheme (http or https) |
+| `host` | string | The hostname from the request |
+| `path` | string | The URL path of the request |
+| `method` | string | The HTTP method (GET, POST, PUT, DELETE, etc.) |
+| `tls` | boolean | Whether the connection used TLS/SSL |
+
+## Log Retention
+
+Request log retention is controlled by the organization setting. By default, request logs are retained for 7 days.
+
+
+ Request logs can generate significant data volume depending on your traffic. Consider your storage capacity when configuring retention periods.
+
+
+## Exporting
+
+Logs can be exported into CSV format for external analysis and archival. Logs can be exported from the table view in the
+Pangolin dashboard or via the Pangolin API. When exporting, you can specify date ranges and filters to narrow down the
+logs you need.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Organization/Organization_ID.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Organization/Organization_ID.md
new file mode 100644
index 00000000..7cafc3a1
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Organization/Organization_ID.md
@@ -0,0 +1,29 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Organization ID
+
+> Understand organization IDs and how to locate yours in the dashboard
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Pangolin is multi-tenant. All sites, resources, clients, and other items belong to an organization, and a server can
+host more than one organization.
+
+Each organization has a unique ID that Pangolin generates when you create the organization. You cannot change the ID
+after creation, and it is separate from the display name.
+
+## Finding your organization ID
+
+You can find your organization ID in two ways:
+
+1. Check the general settings page for your organization. The ID appears at the top of the info card.
+
+2. Check the URL path when viewing your dashboard. The org ID is the first slug in the URL. For example, in
+ `https://app.pangolin.net/home-lab/settings/sites`, the org ID is `home-lab`.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Remote_Nodes/Configuration_File.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Remote_Nodes/Configuration_File.md
new file mode 100644
index 00000000..fd5426a2
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Remote_Nodes/Configuration_File.md
@@ -0,0 +1,93 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Configuration File
+
+> Configure your remote node using the config.yml file
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+The `config.yml` file includes basic config variable for your remote node. This file is mounted at `config/config.yml`
+in your Docker container.
+
+Minimal configuration file:
+
+```yaml title="config.yml" theme={null}
+gerbil:
+ start_port: 51820
+ base_endpoint: "154.123.45.67" # REPLACE WITH YOUR IP OR DOMAIN
+
+managed:
+ id: "he4g78wevj25msf"
+ secret: "n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7d"
+```
+
+### Gerbil Tunnel Controller
+
+
+ Gerbil tunnel controller settings for WireGuard tunneling.
+
+
+
+ Domain name included in WireGuard configuration for tunnel connections.
+
+ **Example**: `pangolin.example.com`
+
+
+
+ Starting port for WireGuard tunnels.
+
+ **Example**: `51820`
+
+
+
+
+
+### Remote Node Configuration
+
+
+ Settings for connecting the remote node to the Pangolin head server.
+
+
+
+ Unique identifier for the managed deployment. Generated from the installer or the [Pangolin dashboard](https://app.pangolin.net).
+
+ **Example**: `he4g78wevj25msf`
+
+
+
+ Secret key for authenticating with the managed service. Generated from the installer or the [Pangolin dashboard](https://app.pangolin.net).
+
+ **Example**: `n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7d`
+
+
+ Keep this secret secure and do not share it publicly.
+
+
+
+
+ The managed service endpoint to connect to. This can only change with enterprise deployments.
+
+ **Example**: `https://app.pangolin.net`
+
+ **Default**: `https://app.pangolin.net`
+
+
+
+ Custom redirect endpoint for authentication flows. This can only change for enterprise deployments.
+
+ **Example**: `https://my-pangolin.example.com`
+
+
+ If not specified, the default dashboard URL will be used.
+
+
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Remote_Nodes/Quick_Install_Guide.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Remote_Nodes/Quick_Install_Guide.md
new file mode 100644
index 00000000..9754b85c
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Remote_Nodes/Quick_Install_Guide.md
@@ -0,0 +1,114 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Quick Install Guide
+
+> Deploy your own remote Pangolin node in under 10 minutes with our automated installer
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+* **Pangolin Cloud** account. You can [create a free account here](https://app.pangolin.net/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).
+
+
+ **Recommended**: Ubuntu 20.04+ or Debian 11+ for best compatibility and performance.
+
+
+## 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
+
+
+
+ Connect to your server via SSH and download the installer:
+
+ ```bash theme={null}
+ curl -fsSL https://static.pangolin.net/get-node-installer.sh | bash
+ ```
+
+ The installer supports both AMD64 (x86\_64) and ARM64 architectures.
+
+
+
+
+ Execute the installer with root privileges:
+
+ ```bash theme={null}
+ sudo ./installer
+ ```
+
+ The installer places all files in the current directory. Move the installer to your desired installation directory before running it.
+
+
+
+
+ If you are on your game and have already generated credentials for this node in the dashboard enter them here.
+
+
+ If you don't have them yet you can just select no when asked and we will create it in a later step.
+
+
+
+
+
+ Enter either the public IP address of your server or a domain name that resolves to it.
+
+
+ The installer will attempt resolve and prefill your public IP address. Verify this is correct before preceding.
+
+
+
+ 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.
+
+
+
+
+
+ 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://app.pangolin.net/) 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.
+
+
+ More than one account can use the same node credentials. This is useful for teams.
+
+
+
+
+
+## Post-Installation Setup
+
+Once installation completes successfully, you'll see:
+
+```
+Installation complete!
+```
+
+Navigate to the [Pangolin dashboard](https://app.pangolin.net/) and create sites, resources, and targets for your remote
+node.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Remote_Nodes/Remote_Nodes.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Remote_Nodes/Remote_Nodes.md
new file mode 100644
index 00000000..df58d31b
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Remote_Nodes/Remote_Nodes.md
@@ -0,0 +1,63 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Remote Nodes
+
+> Control your own Pangolin node with cloud management
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ Remote Nodes are available in Pangolin Cloud and self-hosted [Enterprise Edition](/self-host/enterprise-edition).
+
+
+Remote nodes, you run your own Pangolin node - your tunnels, SSL termination, and traffic all stay on your server and
+use your bandwidth. The difference is that management and monitoring are handled through our cloud or your central
+self-hosted [Enterprise Edition](/self-host/enterprise-edition) server. The node just handles terminating Wireguard
+tunnels, serving HTTP(S) traffic, and routing relayed client connections - it is essentially a remote networking hub.
+
+Think of different nodes as the "front doors" to your applications - users connect to the closest one, and it securely
+routes their requests to your backend services.
+
+
+ You can deploy a remote Pangolin node [using the installer](/manage/remote-node/quick-install-remote).
+
+
+## How It Works
+
+* **Host the Node**: Run Gerbil, Traefik, and a light weight agent on your server that communicates with the central
+ Pangolin control plane with a websocket connection.
+* **Delegate the DNS**: Your domain and DNS config is still controlled by the Pangolin control plane and the central DNS
+ server routes to the right node when connecting.
+* **Certificates and Config**: The control plane pushes down WireGuard configs, SSL certificates, and routing rules to
+ your node as you create resources and sites.
+* **Failover**: If you have multiple nodes, the control plane will failover between them. If one node becomes
+ unavailable, traffic can optionally fail over to our cloud infrastructure or other nodes until you restore service.
+
+
+
+
+
+## Some Benefits
+
+### Automatic Updates and Less Maintenance
+
+The cloud dashboard evolves quickly, so you get new features and bug fixes without having to manually pull new
+containers every time. Because the remote node is just handling the networking you do not need to do database
+migrations, or backups.
+
+### Cloud Failover
+
+If your nodes goes down, your tunnels can temporarily fail over to our cloud points of presence or another node until
+you bring it back online. This ensures continuous availability.
+
+### High Availability (PoPs)
+
+You can attach multiple nodes to your account for redundancy and better performance. For example, deploy nodes across
+different regions or providers for decreased latency.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Aliases.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Aliases.md
new file mode 100644
index 00000000..b62ab4da
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Aliases.md
@@ -0,0 +1,69 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Aliases
+
+> Set a friendly alias hostname that resolves to a host
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Aliases provide a secondary, user-friendly address for any of your Resources, allowing users to access the Resource
+using this alternate name in addition to the original address.
+
+For instance, a router with the address `10.0.0.1` could be assigned the alias `router.internal`, and users could
+connect using either. Aliases are accessible to anyone who has access to the Resource, and they are exclusively
+accessible when connected with a Pangolin client, meaning they function without requiring any external DNS record setup.
+Furthermore, aliases are protocol agnostic, which means they will work with any network protocol, essentially acting as
+a pseudo-A record for an address that is only functional within the Pangolin environment.
+
+## CIDRs Vs. IPs
+
+A alias can only be created for a Resource that is a single host (IP or FQDN). Aliases cannot be created for Resources
+that are CIDR ranges because it would be ambiguous which host within the range the alias should point to.
+
+## Domain Structure
+
+Since aliases cannot be single-label domains, you must avoid using domain names that do not contain a dot (e.g.,
+`pangolin`). A domain like `pangolin.net`, which includes a dot, is acceptable. Instead of a single-label domain, you
+should consider using a subdomain of a domain you control, such as `router.mywebsite.com`, or an existing
+private/internal domain name, like `router.internal` or `router.corp`.
+
+### Wildcards
+
+Wildcards allow you to define aliases that match multiple hostnames using special characters in the FQDN. For example,
+in an alias like `*.host-0?.autoco.internal`, the asterisk `*` matches any sequence of characters (including none), and
+the question mark `?` matches exactly one character.
+
+If you use a wildcard such as `*.proxy.internal`, it will match any hostname that ends with `.proxy.internal` and has
+something before the dot—such as `host.proxy.internal`, `longerhost.proxy.internal`, or even `sub.host.proxy.internal`.
+However, the wildcard will not match the base domain itself (`autoco.internal` without anything before the dot).
+
+## Custom Upstream DNS
+
+Aliases work by overriding the DNS of your computer running the client so that all DNS requests are sent to the Pangolin
+client for resolution. The dns server on your computer is typically `100.96.128.1` (the first address inside of your
+utility subnet on the org) when connected to the tunnel which will forward request to an upstream server. By default, we
+use `9.9.9.9`, but this upstream address can be configured in the CLI or in the client settings.
+
+**If you are attempting to set an upstream DNS server that is only accessible via the tunnel, ensure that you create a
+resource and check the tunnel DNS option in the client configuration settings or use the --tunnel-dns flag.** Otherwise,
+connectivity to the server may fail when connected to the tunnel. You must also be overriding the dns of the computer (
+as discussed above) for this to work because the client needs to intercept the DNS request to forward it to the upstream
+server.
+
+## Disable Aliases
+
+If you wish to disable this behavior and prevent aliases from being resolved and leave your DNS alone, you can do so by
+adding `--override-dns=false` to the CLI or disable override dns in the client settings.
+
+## ICMP Ping
+
+Aliases do not currently support ICMP ping requests. If you attempt to ping an alias, it will not respond, even if the
+underlying Resource is reachable. This is because the Pangolin client does not intercept ICMP packets for alias
+resolution.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Authentication.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Authentication.md
new file mode 100644
index 00000000..84d15ba2
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Authentication.md
@@ -0,0 +1,48 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Authentication
+
+> Only allow access to Resources to specific users, roles, and machines
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+When a client connects into an organization they will **NOT** have access to any Resources by default. Access must be
+explicitly granted to users, roles, or machines for a WireGuard tunnel to be established to the site hosting the
+Resource. The Client will show no peers unless access is granted.
+
+Access can be granted in several ways:
+
+* **Roles:** Assign access to Resources to specific roles. Any user or machine with that role will gain access to the
+ Resource when they connect.
+* **Users:** Assign access to Resources to specific users. Only those users will gain access to the Resource when they
+ connect.
+* **Machines:** Assign access to Resources to specific machines. Only those machines will gain access to the Resource
+ when they connect. Note that machines can not be put into roles.
+
+When removing access to a resource, the client will automatically tear down the WireGuard tunnel to that Resource if
+there are no other Resources accessible on that site.
+
+
+
+
+
+### Port Restrictions
+
+By default, when access to a Resource is granted, all ports on that Resource are accessible. However, you can restrict
+access to specific ports on a Resource by defining port restrictions. When port restrictions are defined, only the
+specified ports will be accessible to users, roles, or machines that have access to the Resource. To specify specific
+ports, enter either a single port (e.g., `80`), a comma-separated list of ports (e.g., `80,443,8080`), or a port range
+using a hyphen (e.g., `8000-8100`).
+
+### ICMP Access
+
+By default, ICMP (ping) access to Resources is enabled. To disable ICMP access, you can uncheck the "ICMP" option when
+configuring access to a Resource. This will prevent users, roles, or machines with access to the Resource to send ICMP
+echo requests (ping) to the Resource's destination. Currently you can not ping an alias.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Destinations.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Destinations.md
new file mode 100644
index 00000000..a26ed37c
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Destinations.md
@@ -0,0 +1,63 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Destinations
+
+> Understand connection options to the remote network
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+A Resource's **destination** can be defined in several ways:
+
+* **Fully Qualified Domain Name (FQDN):** For example, `host.autoco.internal`.
+* **IP Address:** For example, `10.1.0.35`.
+* **IP CIDR Range:** For example, `10.1.0.0/16`.
+
+When defining a Resource with an FQDN, the Pangolin site will resolve the FQDN to an IP address on the remote network.
+This allows you to create Resources that point to hosts whose IP addresses may change over time, as long as the FQDN
+remains consistent.
+
+When defining a Resource with an IP address, the Pangolin client will connect directly to that specific IP address on
+the remote network. It will insert routes for that single IP address into the network route table of the host when users
+connect with the client.
+
+When defining a Resource with a CIDR range, all IP addresses within that range will be accessible to users who have been
+granted access to the Resource. This is useful for providing access to entire subnets or network segments. It will
+insert routes for that single IP address into the network route table of the host when users connect with the client.
+
+### Additional Notes on Resource Destinations
+
+* **Reserved IP Addresses:** The Pangolin client reserves the CGNAT subnet 100.96.128.0/24. Accessing resources via an
+ IP address within this reserved range will be blocked by the client, though its use is uncommon. This range can be
+ configured for newly created orgs in the self-hosted Pangolin configuration file.
+* **Resource Destination Resolution:** The configured address of the Resource is resolved by the site the resource
+ points to. Make sure the site can resolve the address correctly.
+
+### What about overlaps?
+
+Pangolin smooths away overlapping networks and arbitrarily chooses a single site to resolve the IP address or range to.
+This is because we want connection requests to any Resource to be as simple as possible for the end users: when they
+connect to a particular IP address or FQDN, Pangolin figures out which site to send it to and the end user never needs
+to figure this out.
+
+It is recommended that you create overlapping resources only if absolutely required. If you do,
+use [Aliases](/manage/resources/private/alias) to explicitly defined which host should be used for a given FQDN or IP
+address and use the alias to connect.
+
+### ICMP End to End?
+
+Pangolin supports testing connectivity to Resources using ICMP ping requests. However, it's important to note that while
+the Pangolin client can send ICMP echo requests to the destination, **the actual ping request is captured and replayed
+from the Newt binary to the actually destination**. This means that requests are not end to end but are still an
+effective way to test connectivity to a resource.
+
+### Unicast Only?
+
+Right now unicast TCP and UDP traffic is supported through the Pangolin client. Multicast and broadcast traffic is not
+supported at this time.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/Authentication.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/Authentication.md
new file mode 100644
index 00000000..17d1ed74
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/Authentication.md
@@ -0,0 +1,57 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Authentication
+
+> Create identity and context aware rules to allow access
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Though public resources are public and accessible to via a web browser, admins can create rules to enable a layer of
+authenticated protection in front of public resources. By default, all public resources have Pangolin auth (Platform
+SSO) enabled, but a number of other authentication methods are available.
+
+When an unauthenticated user visits a resource in their web browser, they will be redirected to a Pangolin-controlled
+authentication page where they must complete authentication.
+
+## User Login
+
+* **Pangolin (Platform) SSO** - Users must log in with a valid Pangolin account before they can log in.
+* **External Identity Provider** - Enable log in to resources via your organization's identity provider of choice (
+ Google, Azure, Okta, etc).
+* **Users and Roles** - Assign specific users accesss to resources. Group users by roles and assign entire roles access
+ to resources.
+
+## PIN and Passcode
+
+Add simple PIN or passcode authentication to resources. Similarly to user login, users will need to first enter a PIN or
+passcode before they can gain access to the resource.
+
+## Shareable Links and Access Tokens
+
+Generate temporary self-destructing links that provide authenticated access to resources. Set specific expiration times
+for when all users who used the link will lose access and when the link becomes invalid. Links can optionally grant more
+permanent access with no expiration. Delete links when you want to revoke access.
+
+You can also pass access tokens via query params or headers to resources to enable programmatic access.
+
+## Email-based One Time Passcode (OTP)
+
+First whitelist specific emails or wildcards, like `*@.example.com`. When users visit the resource, they will be
+prompted to enter an email. If the email they enter is on the whitelist, a temporary one time passcode will be sent to
+their email. Users can then enter this OTP to gain access to the resource.
+
+## Rules to Access or Deny
+
+Define ranked rules to either block or allow access from specific IPs, geolocation, URL paths, and more.
+
+## More
+
+Read about more authentication options and specific settings in [Access Control](/manage/access-control/)
+and [Identity Providers](/manage/identity-providers/).
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/Health_Checks.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/Health_Checks.md
new file mode 100644
index 00000000..9f7478e0
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/Health_Checks.md
@@ -0,0 +1,153 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Health Checks
+
+> Configure automated health monitoring and failover for resources
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Pangolin provides automated health checking for targets to ensure traffic is only routed to healthy services. Health
+checks are essential for building highly available services, as they automatically remove unhealthy targets from traffic
+routing and load balancing.
+
+## How Health Checks Work
+
+### Monitoring Process
+
+Health checks operate continuously in the background:
+
+1. **Periodic Checks**: Pangolin sends requests to your target endpoints at configured intervals.
+2. **Status Evaluation**: Responses are evaluated against your configured criteria.
+3. **Traffic Management**: Healthy targets receive traffic, unhealthy targets are excluded.
+4. **Automatic Recovery**: Targets are automatically re-enabled when they become healthy again.
+
+## Target Health States
+
+Targets can exist in three distinct states that determine how traffic is routed:
+
+
+
+ **Initial State**: Targets start in this state before first health check
+
+ **Traffic Behavior**: Unknown targets still route traffic normally
+
+ **Duration**: Until first health check completes
+
+
+
+
+ **Failed Checks**: Target has failed health check criteria
+
+ **Traffic Behavior**: No traffic is routed to unhealthy targets
+
+ **Load Balancing**: Excluded from load balancing rotation
+
+
+
+
+ **Passing Checks**: Target is responding correctly to health checks
+
+ **Traffic Behavior**: Receives traffic according to load balancing rules
+
+ **Load Balancing**: Included in load balancing rotation
+
+
+
+
+## Configuring Health Checks
+
+
+
+ In the Pangolin dashboard, navigate to your resource and locate the target in the table.
+
+
+
+ Click the settings wheel (⚙️) next to the health check endpoint column.
+
+
+
+ Fill out the health check configuration with your desired parameters.
+
+
+
+ Save your settings to enable health checking for the target.
+
+
+
+## Health Check Parameters
+
+### Endpoint Configuration
+
+* **Target Endpoint**: The URL or address to monitor for health status
+* **Default Behavior**: Usually the same as your target endpoint
+* **Custom Endpoints**: Can monitor different endpoints (e.g., `/health`, `/status`)
+
+### Timing Configuration
+
+#### Healthy Interval
+
+* **Purpose**: How often to check targets that are currently healthy
+* **Typical Range**: 30-60 seconds
+* **Consideration**: Less frequent checks reduce overhead
+
+#### Unhealthy Interval
+
+* **Purpose**: How often to check targets that are currently unhealthy
+* **Typical Range**: 10-30 seconds
+* **Consideration**: More frequent checks enable faster recovery
+
+### Response Configuration
+
+#### Timeout Settings
+
+* **Request Timeout**: Maximum time to wait for a health check response
+* **Default Behavior**: Requests exceeding timeout are considered failed
+* **Recommended**: Set based on your service's typical response time
+
+#### HTTP Response Codes
+
+* **Healthy Codes**: Which HTTP status codes indicate a healthy target
+* **Common Settings**: 200, 201, 202, 204
+* **Custom Codes**: Configure based on your service's health endpoint behavior
+
+## High Availability Strategies
+
+### Multi-Target Redundancy
+
+#### Service Redundancy
+
+Deploy multiple instances of your service across different targets to ensure availability even when some targets fail.
+
+```
+Resource: web-application
+├── Target 1: web-01.local:8080 (Site A) - Healthy ✅
+├── Target 2: web-02.local:8080 (Site A) - Unhealthy ❌
+└── Target 3: web-03.local:8080 (Site B) - Healthy ✅
+
+Traffic routes to: Target 1 & Target 3 only
+```
+
+### Cross-Site Failover
+
+#### Geographic Distribution
+
+Distribute targets across multiple sites to protect against site-level failures.
+
+```
+Resource: api-service
+├── Primary Site Targets
+│ ├── api-01.primary:8443 - Healthy ✅
+│ └── api-02.primary:8443 - Healthy ✅
+└── Backup Site Targets
+ ├── api-01.backup:8443 - Healthy ✅
+ └── api-02.backup:8443 - Healthy ✅
+
+All targets receive traffic via load balancing
+```
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/Maintenance_Page.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/Maintenance_Page.md
new file mode 100644
index 00000000..c2074428
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/Maintenance_Page.md
@@ -0,0 +1,58 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Maintenance Page
+
+> Show a maintenance page to users when a resources is down for maintenance or targets are unhealthy
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ Maintenance pages are only available in [Enterprise Edition](/self-host/enterprise-edition).
+
+
+Pangolin can display a customizable maintenance page to users when a resource is undergoing maintenance or when all
+targets are unhealthy. This ensures users are informed about the downtime and provides a better user experience.
+
+
+
+
+
+## Configuration
+
+Title: The main title text displayed on the maintenance page.
+
+Message: A descriptive message informing users about the maintenance status.
+
+Estimated completion time: Optionally provide an estimated time for when the resource will be back online.
+
+## Enabling Maintenance Page
+
+To enable the maintenance page for a resource, navigate to the general resource settings in the Pangolin dashboard.
+Under the "Maintenance Page" section, you can customize the title, message, and estimated completion time. This can also
+be set using Blueprints.
+
+## When is the Maintenance Page Shown?
+
+There are two modes that control when the page is shown:
+
+#### Forced
+
+In forced mode, the maintenance page is displayed to all users regardless of the health status of the resource targets.
+This is useful for planned maintenance windows.
+
+#### Automatic
+
+In automatic mode, the maintenance page is shown only when all targets associated with the resource are unhealthy or all
+of the sites are offline. This is useful for unplanned outages and can be used to inform the user that the resource is
+temporarily unavailable by customizing the above settings.
+
+## Remote Nodes
+
+Maintenance pages do not work on remote nodes at this time.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/TCP_&_UDP.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/TCP_&_UDP.md
new file mode 100644
index 00000000..bdd17bb5
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/TCP_&_UDP.md
@@ -0,0 +1,129 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# TCP & UDP
+
+> Configure raw TCP and UDP traffic through Pangolin tunnels
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ This feature is only available in self-hosted Pangolin instances. If you're using Pangolin Cloud, you will need to deploy a remote node.
+
+
+Pangolin supports raw TCP and UDP traffic because Newt can pass anything through the tunnel.
+
+In Pangolin Community Edition, ensure you have the flag enabled in the config file:
+
+```
+flags:
+ allow_raw_resources: true
+```
+
+You map the resource to a port on the host Pangolin server, so you can access the resource from
+`:`. This is useful if you want to access the resource over the public internet, such as
+exposing a game server like Minecraft.
+
+## Proxied Resources
+
+Proxied resources require extra configuration to expose on the Pangolin server. You'll need to configure firewall rules,
+Docker port mappings, and Traefik entry points. These steps require a server restart.
+
+
+
+ In the Pangolin dashboard, go to Resources and click Add Resource. Select "Raw TCP/UDP resource", and enter your desired publicly mapped port. This is the port you'll use to access the proxied resource.
+
+
+
+ Open your desired ports on your VPS firewall, just like you did for ports 51820, 443, and 80. This is highly OS and VPS dependent.
+
+
+ In this example, we're exposing two resources: TCP 1602 and UDP 1704.
+
+
+
+
+
+ Add port mappings to your `docker-compose.yml` file:
+
+ ```yaml title="docker-compose.yml" highlight={4,5} theme={null}
+ gerbil:
+ ports:
+ # ... existing ports ...
+ - 1704:1704/udp # ADDED: Your UDP port
+ - 1602:1602 # ADDED: Your TCP port
+ ```
+
+
+
+
+ Add entry points to your `config/traefik/traefik_config.yml`:
+
+ ```yaml title="traefik_config.yml" highlight={12-15} theme={null}
+ entryPoints:
+ web:
+ address: ":80"
+ websecure:
+ address: ":443"
+ http:
+ tls:
+ certResolver: letsencrypt
+ transport:
+ respondingTimeouts:
+ readTimeout: 30m
+ tcp-1602:
+ address: ":1602/tcp"
+ udp-1704:
+ address: ":1704/udp"
+ ```
+
+
+ **Important**: Always name your entry points in the format `protocol-port` (e.g., `tcp-1602`, `udp-1704`). This naming is required for Pangolin's dynamic configuration.
+
+
+
+
+
+ Restart your Docker stack to apply all changes:
+
+ ```bash theme={null}
+ sudo docker compose down
+ sudo docker compose up -d
+ ```
+
+
+
+
+
+ In this example, we expose port 1602 for TCP and port 1704 for UDP. You can use any available ports on your VPS.
+
+
+## Proxy Protocol
+
+On TCP resources you can enable Proxy Protocol support to forward the original client IP address to your backend
+service. This is useful for logging and access control.
+
+In order to enable proxy protocol, simply check the "Enable Proxy Protocol" box when creating or editing a TCP resource.
+
+Your backend application must be configured to accept Proxy Protocol connections. If your backend doesn't support
+Proxy Protocol, enabling this will break all connections so only enable this if you know what you're doing. Make sure to
+configure your backend to trust Proxy Protocol headers from Traefik.
+
+To enable Proxy Protocol in Traefik, add the following to the bottom of your `config/traefik/dynamic_config.yml`:
+
+```yaml theme={null}
+tcp:
+ serversTransports:
+ pp-transport-v1:
+ proxyProtocol:
+ version: 1
+ pp-transport-v2:
+ proxyProtocol:
+ version: 2
+```
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/Targets.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/Targets.md
new file mode 100644
index 00000000..3a1e4634
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/Targets.md
@@ -0,0 +1,232 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Targets
+
+> Configure destination endpoints for resource routing and load balancing
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+When you create a resource in Pangolin, you define different targets that specify where traffic should be routed within
+your network. Each target represents a specific destination that the resource can proxy to when handling incoming
+requests.
+
+## How Targets Work
+
+### Target Routing
+
+Targets function as destination endpoints for your resources:
+
+1. **Resource Creation**: When you create a resource, you configure one or more targets
+2. **Traffic Routing**: Incoming traffic is routed to the appropriate target based on your configuration
+3. **Network Access**: Newt proxy routes traffic to the local network through the tunnel
+4. **Direct Connection**: No additional routing is necessary on the remote network
+
+## Multi-Site Targets
+
+Targets have sites associated with them. This provides significant benefits for reliability and load distribution
+described below.
+
+### Site-Distributed Resources
+
+You can now configure targets across different sites for the same resource:
+
+
+ Distribute your resources across multiple sites so that if one site goes down, traffic automatically continues to be served from other available sites.
+
+
+
+ Set up load balancing across sites to distribute traffic in a round-robin fashion between all available targets.
+
+
+### Distributing Sites Load Across Servers
+
+
+ This is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
+
+
+This refers to having more than on Pangolin server node that a site can connect to. If one of the server nodes goes
+down, the site moves to another node. This has some implications for site-based load balancing, because DNS must can
+only route a FQDN to one Pangolin server node at a time.
+
+Load balancing between different targets only works when sites are connected to the same Pangolin node. In Pangolin
+instances with multiple remote nodes, ensure load balancing occurs on the same node.
+
+To ensure effective load balancing in multi-node environments:
+
+```bash theme={null}
+newt --prefer-endpoint
+```
+
+## Path-Based Routing
+
+Path-based routing allows you to direct traffic to different targets based on the request path. This enables
+sophisticated routing scenarios where different services can handle different parts of your application.
+
+### How Path-Based Routing Works
+
+Each target can be configured with optional path routing parameters:
+
+* **Path**: The path pattern to match against incoming requests
+* **Match**: The matching strategy to use when comparing the request path
+
+When a request comes in, Pangolin evaluates the path against all targets and routes traffic to the target with the
+matching path configuration.
+
+### Match Types
+
+Pangolin supports three different matching strategies:
+
+#### Exact Match
+
+**exact**: The request path must match the configured path exactly.
+
+Example: Path `/api/users` with exact match only matches `/api/users`
+
+#### Prefix Match
+
+**prefix**: The request path must start with the configured path.
+
+Example: Path `/api` with prefix match matches `/api/users`, `/api/orders`, `/api/users/123`, etc.
+
+#### Regex Match
+
+**regex**: The request path is matched against a regular expression pattern.
+
+Example: Path `^/api/users/[0-9]+$` with regex match matches `/api/users/123` but not `/api/users/abc`
+
+
+
+
+
+### Load Balancing with Path-Based Routing
+
+When multiple targets have the same path and match configuration, Pangolin will load balance between them using
+round-robin distribution.
+
+**Example Scenario:**
+
+* Target 1: Path `/api`, Match `prefix`, Address `10.0.1.10:8080`
+* Target 2: Path `/api`, Match `prefix`, Address `10.0.1.11:8080`
+* Target 3: Path `/web`, Match `prefix`, Address `10.0.1.12:80`
+
+In this configuration:
+
+* Requests to `/api/users` will be load balanced between Target 1 and Target 2
+* Requests to `/web/dashboard` will only go to Target 3
+
+## Path Rewriting
+
+Path rewriting allows you to modify the request path before it reaches your backend service. This enables you to expose
+different URL structures to your users while maintaining your existing backend API paths.
+
+
+ Path rewriting requires path-based routing to be configured first. You must set up a Path Match before you can configure path rewriting.
+
+
+### How Path Rewriting Works
+
+After Pangolin matches a request using path-based routing, it can rewrite the path before forwarding the request to your
+target service. Each target with path matching configured can optionally include path rewriting:
+
+* **Rewrite Type**: The strategy to use for rewriting the path
+* **Rewrite Value**: The new path or pattern to apply (optional for Strip Prefix)
+
+The rewriting happens after the path match evaluation but before the request reaches your backend service.
+
+### Rewrite Types
+
+Pangolin supports four different rewriting strategies:
+
+#### Prefix Rewrite
+
+**prefix**: Replaces the matched portion with a new prefix, preserving the rest of the path.
+
+* With Prefix Match: `/api` → `/v2/api` transforms `/api/users` into `/v2/api/users`
+* With Exact Match: `/old` → `/new` transforms `/old` into `/new`
+* With Regex Match: Uses the regex pattern with the rewrite value as replacement
+
+#### Exact Rewrite
+
+**exact**: Replaces the matched path with the exact rewrite path.
+
+Example: Match path `/api/users` → Rewrite to `/users` transforms `/api/users` into `/users`
+
+#### Regex Rewrite
+
+**regex**: Uses regular expression substitution to transform the path. Works with any match type.
+
+* With Regex Match: Uses the regex pattern directly
+* With Prefix Match: Automatically captures everything after the prefix with `(.*)`
+* With Exact Match: Matches the exact path
+
+Example: Match path `^/api/v1/(.*)` (regex) → Rewrite to `/api/v2/$1` transforms `/api/v1/users` into `/api/v2/users`
+
+#### Strip Prefix
+
+**stripPrefix**: Removes the matched prefix from the path.
+
+* With Prefix Match: Efficiently strips the prefix using Traefik's stripPrefix middleware
+* With Exact/Regex Match: Uses regex replacement to remove the matched portion
+* Optionally add a new prefix after stripping by providing a rewrite value
+
+Example: Match path `/api` (prefix) → Strip Prefix transforms `/api/users` into `/users`
+
+Example with new prefix: Match path `/old` (prefix) → Strip Prefix + Rewrite to `/new` transforms `/old/users` into
+`/new/users`
+
+
+
+
+
+### Configuration Requirements
+
+
+ Path rewriting validation ensures your configuration is valid:
+
+* Path rewriting requires path matching to be configured first
+* When using rewrite types other than Strip Prefix, both rewrite path and rewrite type must be specified together
+* For regex path matching, the path pattern must be a valid regular expression
+* Strip Prefix works with any match type, but is most effective with Prefix match type
+
+
+### Automatic Path Normalization
+
+Pangolin automatically normalizes paths to ensure correct routing:
+
+* Non-regex paths that don't start with `/` will have `/` prepended automatically
+* Non-regex rewrite paths that don't start with `/` will have `/` prepended automatically
+* This ensures consistent behavior across different configurations
+
+### Load Balancing with Path Rewriting
+
+All targets with identical path match and path rewrite configurations will be load balanced together.
+
+**Example:**
+
+* Target 1: Match `/api` (prefix), Rewrite `/v2` (prefix), Address `10.0.1.10:8080`
+* Target 2: Match `/api` (prefix), Rewrite `/v2` (prefix), Address `10.0.1.11:8080`
+* Target 3: Match `/api` (prefix), Strip Prefix, Address `10.0.1.12:8080`
+
+Requests to `/api/users` will:
+
+* Load balance between Target 1 and Target 2 (both rewrite to `/v2/users`)
+* NOT be sent to Target 3 (different rewrite configuration - strips to `/users`)
+
+### Priority Calculation
+
+When using path rewriting, request priority is automatically calculated to ensure proper routing order:
+
+* Base priority: 100
+* Path matching adds +10 to priority
+* Exact match adds +5 more
+* Prefix match adds +3 more
+* Regex match adds +2 more
+* Root path `/` gets priority 1 (lowest, acts as catch-all)
+* Custom priorities override the automatic calculation
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Understanding Resources.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Understanding Resources.md
new file mode 100644
index 00000000..8cb41a7a
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Understanding Resources.md
@@ -0,0 +1,77 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Understanding Resources
+
+> Resources are any network address you want to make available to users
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Resources represent the applications, hosts, or ranges you make available for remote access to users. Resources exist on
+the remote networks of your sites. Users only ever think about connecting to resources and not specific sites.
+
+By default, no resources are made available on sites. Admins must define resources with backend targets, and assign
+specific access policies before any users can gain access.
+
+## Resources Types
+
+There are two types of resources: public resources and private resources.
+
+
+
+ * Reverse proxies to backend services
+ * Optionally have authentication
+ * Anyone with web browser can access
+
+
+
+ * Zero-trust VPN
+ * Access to every resource requires authentication
+ * Users and machines access when connected with a client
+
+
+
+### Public Resources
+
+Public resources are protocol-aware and TCP/UDP proxies to services that are made available to the public internet.
+
+#### HTTPS Resources
+
+Examples of HTTP resources include, APIs, websites, and dashboards. These are served with a fully qualified domain name
+and HTTPS with a valid SSL certificate.
+
+All requests go through an authenticated reverse proxy. **Thus, public resources do not require client-side software to
+be installed on user devices for access. Anyone with a web browser can access public resources.**
+
+HTTP resources are also identity and context aware, meaning you can create policies and rules to only let certain users,
+roles, countries, IPs, CIDRs, etc have access. When users visit an authenticated public resource, they are greeted with
+a Pangolin login page where they must complete authentication in order to get to the underlying resource. Therefore,
+Pangolin acts as a frontdoor barrier to these resources.
+
+#### Raw TCP/UDP Resources
+
+Raw resources are a way to proxy any TCP and UDP traffic through the Pangolin reverse proxy. Instead of a fully
+qualified domain name and certificate, these resources are bound to one or more ports on the Pangolin host.
+
+Since these resources are not protocol aware and are publicly proxied, they do not support identity and context policies
+and rules.
+
+### Private Resources
+
+Private resources require users to be connected with Pangolin client in order for them to be accessed. Any TCP and UDP
+traffic can be made available.
+
+**Private resources function like a zero-trust virtual private network (VPN).** Explicit access to resources must be
+granted for users and roles to be able to access them. For this reason, we recommend using private resources for all raw
+TCP/UDP traffic that doesn't need a public proxy, instead of relying on raw TCP/UDP public resources (as discussed
+above).
+
+Private resources support single hosts or entire network ranges (CIDR). Private resources can also have internal DNS
+alias hostnames assigned for easy, human-readable naming. Users don't choose to connect to specific resources; rather,
+when they connect via a client to your organization, they can access all resources their account has access to at once.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Configure_Sites.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Configure_Sites.md
new file mode 100644
index 00000000..eeab9ec0
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Configure_Sites.md
@@ -0,0 +1,522 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Configure Sites
+
+> Configure Newt for connecting to Pangolin sites
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+## Flags
+
+
+ Newt ID generated by Pangolin to identify the client.
+
+**Example**: `31frd0uzbjvp721`
+
+
+
+ A unique secret used to authenticate the client ID with the websocket.
+
+**Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6`
+
+
+ Keep this secret private and secure. It's used for authentication.
+
+
+
+
+ The endpoint where both Gerbil and Pangolin reside for websocket connections.
+
+**Example**: `https://pangolin.example.com`
+
+
+
+ Port for the peers to connect to Newt on. This can be used to keep a static port open in firewalls instead of default random ports.
+
+**Example**: `34534`
+
+
+
+ MTU for the internal WireGuard interface.
+
+**Default**: `1280`
+
+
+
+ DNS server to use for resolving the endpoint.
+
+**Default**: `9.9.9.9`
+
+
+
+ The log level to use for Newt output.
+
+**Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
+
+**Default**: `INFO`
+
+
+
+ Interval for pinging the server.
+
+**Default**: `3s`
+
+
+
+ Timeout for each ping.
+
+**Default**: `5s`
+
+
+
+ Set the Docker socket path for container discovery integration.
+
+**Example**: `/var/run/docker.sock`
+
+
+
+ Validate the container target is on the same network as the Newt process.
+
+**Default**: `false`
+
+
+
+ Check if connection to WireGuard server (Pangolin) is ok. Creates a file if ok, removes it if not ok. Can be used with Docker healthcheck to restart Newt.
+
+**Example**: `/tmp/healthy`
+
+
+
+ Script to be called when targets are added or removed.
+
+**Example**: `/path/to/updown.sh`
+
+
+
+ Path to blueprint file to define Pangolin resources and configurations.
+
+**Example**: `/path/to/blueprint.yaml`
+
+
+
+ Don't fail over to the cloud when using managed nodes in Pangolin Cloud.
+
+**Default**: `false`
+
+
+
+ Disable clients on the WireGuard interface.
+
+**Default**: `false` (clients enabled)
+
+
+
+ Name of the WireGuard interface.
+
+**Default**: `newt`
+
+
+
+ Enable Prometheus /metrics exporter.
+
+**Default**: `true`
+
+
+
+ Enable OTLP exporters (metrics/traces) to OTEL\_EXPORTER\_OTLP\_ENDPOINT.
+
+**Default**: `false`
+
+
+
+ Admin/metrics bind address.
+
+**Default**: `127.0.0.1:2112`
+
+
+
+ Enable async bytes counting (background flush; lower hot path overhead).
+
+**Default**: `false`
+
+
+
+ Optional region resource attribute for telemetry and metrics.
+
+**Example**: `us-west-2`
+
+
+
+ Enforce certificate validation for health checks.
+
+**Default**: `false` (accepts any cert)
+
+
+
+ Path to client certificate file (PEM/DER format) for mTLS.
+
+**Example**: `/path/to/client.crt`
+
+
+
+ Path to client private key file (PEM/DER format) for mTLS.
+
+**Example**: `/path/to/client.key`
+
+
+
+ Path to CA certificate file for validating remote certificates (can be specified multiple times).
+
+**Example**: `/path/to/ca.crt`
+
+
+
+ Path to client certificate (PKCS12 format) - DEPRECATED: use `--tls-client-cert-file` and `--tls-client-key` instead.
+
+**Example**: `/path/to/client.p12`
+
+
+
+ Prefer this endpoint for the connection (if set, will override the endpoint from the server).
+
+**Example**: `https://preferred.endpoint.com`
+
+
+## Environment Variables
+
+All CLI arguments can be set using environment variables as an alternative to command line flags. Environment variables
+are particularly useful when running Newt in containerized environments.
+
+
+ When both environment variables and CLI arguments are provided, CLI arguments take precedence.
+
+
+
+ Endpoint of your Pangolin server (equivalent to `--endpoint`)
+
+
+
+ Newt ID generated by Pangolin (equivalent to `--id`)
+
+
+
+ Newt secret for authentication (equivalent to `--secret`)
+
+
+
+ Port for the peers to connect to Newt on (equivalent to `--port`)
+
+
+
+ MTU for the internal WireGuard interface (equivalent to `--mtu`)
+
+**Default**: `1280`
+
+
+
+ DNS server to use for resolving the endpoint (equivalent to `--dns`)
+
+**Default**: `9.9.9.9`
+
+
+
+ Load the config JSON from this file instead of in the home folder.
+
+
+
+ Path to blueprint file to define Pangolin resources and configurations (equivalent to `--blueprint-file`).
+
+
+
+ Don't fail over to the cloud when using managed nodes in Pangolin Cloud (equivalent to `--no-cloud`).
+
+**Default**: `false`
+
+
+
+ Log level (equivalent to `--log-level`)
+
+**Default**: `INFO`
+
+
+
+ Path to Docker socket for container discovery (equivalent to `--docker-socket`)
+
+
+
+ Interval for pinging the server (equivalent to `--ping-interval`)
+
+**Default**: `3s`
+
+
+
+ Timeout for each ping (equivalent to `--ping-timeout`)
+
+**Default**: `5s`
+
+
+
+ Path to updown script for target add/remove events (equivalent to `--updown`)
+
+
+
+ Validate container targets are on same network (equivalent to `--docker-enforce-network-validation`)
+
+**Default**: `false`
+
+
+
+ Path to health file for connection monitoring (equivalent to `--health-file`)
+
+
+
+ Disable clients on the WireGuard interface (equivalent to `--disable-clients`).
+
+**Default**: `false`
+
+
+
+ Name of the WireGuard interface (equivalent to `--interface`)
+
+**Default**: `newt`
+
+
+
+ Enable Prometheus /metrics exporter (equivalent to `--metrics`).
+
+**Default**: `true`
+
+
+
+ Enable OTLP exporters (metrics/traces) to OTEL\_EXPORTER\_OTLP\_ENDPOINT (equivalent to `--otlp`).
+
+**Default**: `false`
+
+
+
+ Admin/metrics bind address (equivalent to `--metrics-admin-addr`).
+
+**Default**: `127.0.0.1:2112`
+
+
+
+ Enable async bytes counting (background flush; lower hot path overhead, equivalent to `--metrics-async-bytes`).
+
+**Default**: `false`
+
+
+
+ Optional region resource attribute for telemetry and metrics (equivalent to `--region`).
+
+
+
+ Enforce certificate validation for health checks (equivalent to `--enforce-hc-cert`).
+
+**Default**: `false`
+
+
+
+ Path to client certificate file (PEM/DER format) for mTLS (equivalent to `--tls-client-cert-file`)
+
+
+
+ Path to client private key file (PEM/DER format) for mTLS (equivalent to `--tls-client-key`)
+
+
+
+ Comma-separated list of CA certificate file paths for validating remote certificates (equivalent to multiple `--tls-client-ca` flags)
+
+
+
+ Path to client certificate (PKCS12 format) - DEPRECATED: use `TLS_CLIENT_CERT` and `TLS_CLIENT_KEY` instead
+
+
+## Loading secrets from files
+
+You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs.
+
+```
+$ cat ~/.config/newt-client/config.json
+{
+ "id": "spmzu8rbpzj1qq6",
+ "secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
+ "endpoint": "https://app.pangolin.net",
+ "tlsClientCert": ""
+}
+```
+
+This file is also written to when newt first starts up. So you do not need to run every time with --id and secret if you
+have run it once!
+
+Default locations:
+
+* **macOS**: `~/Library/Application Support/newt-client/config.json`
+* **Windows**: `%PROGRAMDATA%\newt\newt-client\config.json`
+* **Linux/Others**: `~/.config/newt-client/config.json`
+
+## Docker Socket Integration
+
+Newt can integrate with the Docker socket to provide remote inspection of Docker containers. This allows Pangolin to
+query and retrieve detailed information about containers running on the Newt client, including metadata, network
+configuration, port mappings, and more.
+
+**Configuration:**
+
+You can specify the Docker socket path using the `--docker-socket` CLI argument or by setting the `DOCKER_SOCKET`
+environment variable. If the Docker socket is not available or accessible, Newt will gracefully disable Docker
+integration and continue normal operation.
+
+Supported values include:
+
+* Local UNIX socket (default):
+
+ > You must mount the socket file into the container using a volume, so Newt can access it.
+
+ `unix:///var/run/docker.sock`
+
+* TCP socket (e.g., via Docker Socket Proxy):
+
+ `tcp://localhost:2375`
+
+* HTTP/HTTPS endpoints (e.g., remote Docker APIs):
+
+ `http://your-host:2375`
+
+* SSH connections (experimental, requires SSH setup):
+
+ `ssh://user@host`
+
+```yaml theme={null}
+services:
+ newt:
+ image: fosrl/newt
+ container_name: newt
+ restart: unless-stopped
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock:ro
+ environment:
+ - PANGOLIN_ENDPOINT=https://example.com
+ - NEWT_ID=2ix2t8xk22ubpfy
+ - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
+ - DOCKER_SOCKET=unix:///var/run/docker.sock
+```
+
+
+ If the Docker socket is not available or accessible, Newt will gracefully disable Docker integration and continue normal operation.
+
+
+**Hostnames vs IPs**
+
+When the Docker Socket Integration is used, depending on the network which Newt is run with, either the hostname (
+generally considered the container name) or the IP address of the container will be sent to Pangolin:
+
+* **Running in Network Mode 'host'**: IP addresses will be used
+* **Running in Network Mode 'bridge'**: IP addresses will be used
+* **Running in docker-compose without a network specification**: Docker compose creates a network for the compose by
+ default, hostnames will be used
+* **Running on docker-compose with defined network**: Hostnames will be used
+
+**Docker Enforce Network Validation**
+
+When run as a Docker container, Newt can validate that the target being provided is on the same network as the Newt
+container and only return containers directly accessible by Newt. Validation will be carried out against either the
+hostname/IP Address and the Port number to ensure the running container is exposing the ports to Newt.
+
+Validation is `false` by default. It can be enabled via setting the `--docker-enforce-network-validation` CLI argument
+or by setting the `DOCKER_ENFORCE_NETWORK_VALIDATION` environment variable.
+
+
+ If the Newt container is run with a network mode of `host`, this feature will not work. Running in `host` mode causes the container to share its resources with the host machine, making it impossible to retrieve specific host container information for network validation.
+
+
+## Updown Scripts
+
+You can pass in an updown script for Newt to call when it is adding or removing a target:
+
+```bash theme={null}
+--updown "python3 test.py"
+```
+
+The script will be called with arguments when a target is added or removed:
+
+```bash theme={null}
+python3 test.py add tcp localhost:8556
+python3 test.py remove tcp localhost:8556
+```
+
+
+ Returning a string from the script in the format of a target (`ip:dst` so `10.0.0.1:8080`) will override the target and use this value instead to proxy.
+
+
+
+ You can look at `updown.py` as a reference script to get started!
+
+
+## mTLS Authentication
+
+Newt supports mutual TLS (mTLS) authentication if the server is configured to request a client certificate. You can use
+either a PKCS12 (.p12/.pfx) file or split PEM files for the client cert, private key, and CA.
+
+### Option 1: PKCS12 (Legacy)
+
+
+ This is the original method and still supported.
+
+
+**Requirements:**
+
+* File must contain:
+ * Client private key
+ * Public certificate
+ * CA certificate
+* Encrypted `.p12` files are **not supported**
+
+**Example:**
+
+```bash theme={null}
+newt \
+--id 31frd0uzbjvp721 \
+--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
+--endpoint https://example.com \
+--tls-client-cert ./client.p12
+```
+
+### Option 2: Split PEM Files (Preferred)
+
+You can now provide separate files for:
+
+* `--tls-client-cert-file`: client certificate (`.crt` or `.pem`)
+* `--tls-client-key`: client private key (`.key` or `.pem`)
+* `--tls-client-ca`: CA cert to verify the server (can be specified multiple times)
+
+**Example:**
+
+```bash theme={null}
+newt \
+--id 31frd0uzbjvp721 \
+--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
+--endpoint https://example.com \
+--tls-client-cert-file ./client.crt \
+--tls-client-key ./client.key \
+--tls-client-ca ./ca.crt
+```
+
+## NAT Traversal Tweaks
+
+Newt supports NAT traversal to allow clients to connect directly to Newt sites without relaying through the Pangolin
+server, improving performance and reducing latency.
+
+In some environment depending on the NAT type and firewall, you may need to tweak some settings to get optimal
+connectivity in the firewall itself. Take a look at [these docs](https://tailscale.com/kb/1361/firewall) for some
+firewall changes you might be able to make.
+
+Another option is to keep newt listening for client connections on a static port. This allows you to open a specific
+port in your firewall for Newt client connections instead of random high ports. You can do this by setting the `--port`
+flag or `PORT` environment variable and then opening this port in the your firewall to DNAT to Newt.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Install_Sites.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Install_Sites.md
new file mode 100644
index 00000000..9068b7d9
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Install_Sites.md
@@ -0,0 +1,239 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Install Sites
+
+> Install Newt as a binary or Docker container
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Newt can be installed as either a static binary executable or a Docker container. You must first create a site and copy
+the Newt config in Pangolin before running Newt.
+
+## Binary Installation
+
+### Quick Install (Recommended)
+
+Use this command to automatically install Newt. It detects your system architecture automatically and always pulls the
+latest version, adding Newt to your PATH:
+
+```bash theme={null}
+curl -fsSL https://static.pangolin.net/get-newt.sh | bash
+```
+
+#### Windows
+
+If you would like to use Newt on Windows as a service or with clients, wintun.dll is sometimes required. Please use
+latest installer from [GitHub releases](https://github.com/fosrl/newt/releases/latest).
+
+### Manual Download
+
+Binaries for Linux, macOS, and Windows are available in
+the [GitHub releases](https://github.com/fosrl/newt/releases/latest) for ARM and AMD64 (x86\_64) architectures.
+
+Download and install manually:
+
+```bash theme={null}
+wget -O newt "https://github.com/fosrl/newt/releases/download/{version}/newt_{architecture}" && chmod +x ./newt
+```
+
+
+ Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/newt/releases) for the latest information.
+
+
+### Running Newt
+
+Run Newt with the configuration from Pangolin:
+
+```bash theme={null}
+newt \
+--id 31frd0uzbjvp721 \
+--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
+--endpoint https://app.pangolin.net
+```
+
+### Systemd Service
+
+Create a basic systemd service:
+
+```ini title="/etc/systemd/system/newt.service" theme={null}
+[Unit]
+Description=Newt
+After=network.target
+
+[Service]
+ExecStart=/usr/local/bin/newt --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://app.pangolin.net
+Restart=always
+User=root
+
+[Install]
+WantedBy=multi-user.target
+```
+
+
+ Make sure to move the binary to `/usr/local/bin/newt` before creating the service!
+
+
+## Docker Installation
+
+### Pull the Image
+
+Pull the latest Newt image from Docker Hub:
+
+```bash theme={null}
+docker pull fosrl/newt:latest
+```
+
+### Run with Docker
+
+Run Newt with CLI arguments from Pangolin:
+
+```bash theme={null}
+docker run -it fosrl/newt --id 31frd0uzbjvp721 \
+--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
+--endpoint https://app.pangolin.net
+```
+
+### Docker Compose
+
+#### Environment Variables (Recommended)
+
+```yaml title="docker-compose.yml" theme={null}
+services:
+ newt:
+ image: fosrl/newt
+ container_name: newt
+ restart: unless-stopped
+ environment:
+ - PANGOLIN_ENDPOINT=https://app.pangolin.net
+ - NEWT_ID=2ix2t8xk22ubpfy
+ - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
+```
+
+#### Config File Injected as Compose Secret
+
+A safer but slightly more complex way is to use [Compose Secrets](https://docs.docker.com/compose/how-tos/use-secrets/).
+First, create a `JSON` file containing your configuration:
+
+```json title="newt-config.secret" theme={null}
+{
+ "id": "2ix2t8xk22ubpfy",
+ "secret": "nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2",
+ "endpoint": "https://app.pangolin.net",
+ "tlsClientCert": ""
+}
+```
+
+Then register and reference the secret in your `docker-compose.yml`:
+
+```yaml title="docker-compose.yml" theme={null}
+services:
+ newt:
+ image: fosrl/newt
+ container_name: newt
+ restart: unless-stopped
+ environment:
+ - CONFIG_FILE=/run/secrets/newt-config
+ secrets:
+ - newt-config
+
+secrets:
+ newt-config:
+ file: ./newt-config.secret
+```
+
+This allows you to separate sensitive secrets from plain configuration, improving security when storing or sharing your
+`docker-compose.yml` anywhere else.
+
+#### CLI Arguments
+
+```yaml title="docker-compose.yml" theme={null}
+services:
+ newt:
+ image: fosrl/newt
+ container_name: newt
+ restart: unless-stopped
+ command:
+ - --id 31frd0uzbjvp721
+ - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
+ - --endpoint https://app.pangolin.net
+```
+
+Start the service:
+
+```bash theme={null}
+docker compose up -d
+```
+
+## Platform-Specific Installation
+
+### Unraid
+
+Newt is available in the Unraid Community Applications store. Search for "Newt" and follow the installation prompts.
+Enter the ID, secret, and endpoint from Pangolin in the template fields.
+
+
+
+
+
+### Portainer and Other UIs
+
+Container management UIs like Portainer typically allow passing commands and environment variables to containers similar
+to Docker Compose. Look for a commands or arguments configuration section and follow the relevant guides.
+
+### Windows Service
+
+On Windows, newt can to be installed and run as a Windows service to remain persistent.
+
+#### Service Management Commands
+
+```
+# Install the service
+newt.exe install
+
+# Start the service
+newt.exe start
+
+# Stop the service
+newt.exe stop
+
+# Check service status
+newt.exe status
+
+# Remove the service
+newt.exe remove
+
+# Show help
+newt.exe service-help
+```
+
+Note running the service requires credentials in `%PROGRAMDATA%\newt\newt-client\config.json`.
+
+#### Service Configuration
+
+When running as a service, newt will read configuration from environment variables or you can modify the service to
+include command-line arguments:
+
+1. Install the service: `newt.exe install`
+2. Set the credentials in `%PROGRAMDATA%\newt\newt-client\config.json`. Hint: if you run newt once with --id and
+ --secret this file will be populated!
+3. Start the service: `newt.exe start`
+
+#### Service Logs
+
+When running as a service, logs are written to:
+
+* Windows Event Log (Application log, source: "newtWireguardService")
+* Log files in: `%PROGRAMDATA%\newt\logs\newt.log`
+
+You can view the Windows Event Log using Event Viewer or PowerShell:
+
+```powershell theme={null}
+Get-EventLog -LogName Application -Source "newtWireguardService" -Newest 10
+```
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Kubernetes.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Kubernetes.md
new file mode 100644
index 00000000..ef0285a7
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Kubernetes.md
@@ -0,0 +1,113 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Kubernetes
+
+> How to deploy a Newt Site on Kubernetes
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+This guide walks you through setting up Newt on Kubernetes using Helm.
+
+This guide assumes you already are familiar with Kubernetes concepts and you fulfill the following Global prerequisites:
+
+## Global Prerequisites
+
+* Kubernetes Cluster (v1.28.15+)
+* Access to the Kubernetes Cluster
+* Helm (v3.0+) installed, see Helm install docs
+
+## Helm Installation
+
+All Fossorial Helm charts are available on Artifact Hub.
+See Fossorial Charts.
+
+
+
+ ```bash theme={null}
+ helm repo add fossorial https://charts.fossorial.io
+ helm repo update fossorial
+ helm search repo fossorial
+ ```
+
+
+
+ Prepare your Newt credentials:
+
+ ```env title="newt-cred.env" theme={null}
+ PANGOLIN_ENDPOINT=
+ NEWT_ID=
+ NEWT_SECRET=
+ ```
+
+ Prepare a values file with your desired configuration.
+
+ See Newt chart values configuration options.
+
+ ```yaml title="values-newt.yaml" theme={null}
+ newtInstances:
+ - name: main
+ enabled: true
+ auth:
+ existingSecretName: newt-cred
+ keys:
+ endpointKey: PANGOLIN_ENDPOINT
+ idKey: NEWT_ID
+ secretKey: NEWT_SECRET
+ ```
+
+
+
+
+ Create a Kubernetes Secret from the env file created earlier:
+
+ ```bash theme={null}
+ kubectl create secret generic newt-cred -n newt --from-env-file=newt-cred.env
+ ```
+
+ Install Newt with Helm:
+
+ ```bash theme={null}
+ helm install my-newt fossorial/newt \
+ -n newt --create-namespace \
+ -f values-newt.yaml
+ ```
+
+ Change the release name (`my-newt`), namespace (`newt`), and values filename as needed.
+
+
+
+
+ ```bash theme={null}
+ # Update repo to get latest charts
+ helm repo update fossorial
+ # Upgrade Newt (after editing values)
+ helm upgrade my-newt fossorial/newt -n newt -f values-newt.yaml
+ ```
+
+ ```bash theme={null}
+ # Roll back to a previous revision
+ helm rollback my-newt 1 -n newt
+ ```
+
+
+
+
+## Customizing Your Values
+
+All configuration options are documented in the respective repositories:
+
+* Newt Helm chart values
+
+## References
+
+* All Fossorial Helm Charts repo
+* All Fossorial Kubernetes resources
+* Pangolin Kubernetes Controller
+* Helm documentation
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Site_Credentials.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Site_Credentials.md
new file mode 100644
index 00000000..6dc3f41a
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Site_Credentials.md
@@ -0,0 +1,70 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Site Credentials
+
+> Understanding how site credentials work and how they can be rotated & regenerated
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+## Understanding Credentials
+
+Every site is provisioned with a unique identifier (ID), secret, and endpoint. The site uses the combination of these
+three to establish a secure, encrypted connection to the server.
+
+### ID
+
+Example: `ln8yqs6w85la5zg`
+
+The ID represents the site connection type in the system. Every Newt site has an ID.
+
+This value is not a secret and it is okay if made publically available.
+
+### Secret
+
+Example: `tfpwoc580jf1l1glfagix0o97p8kirjogdflqg604n0tr3to`
+
+The secret represents the "password" of the site. This secret must match the secret hashed in the system for the
+relevant ID.
+
+
+ This is a *secret*! Only share it with trusted people and be sure to store it safely and securely.
+
+
+When the site connects, it uses this secret as a first handshake with the server. The server then passes temporary
+session credentials back to the site before it can initiate a websocket connection. Once the websocket connection is
+established, ephemeral keys are used to establish tunnels using WireGuard.
+
+### Endpoint
+
+Example: `https://app.pangolin.net` or `https://pangolin.my-server.com`
+
+The endpoint is how the site knows which server to connect to. This is the fully qualified hostname of the Pangolin
+server (the URL you use to access the dashboard). For Pangolin cloud, the endpoint is `https://app.pangolin.net`. The
+site uses this endpoint ot establish a websocket connection and receive control messages from the server.
+
+## Rotating and Regenerating Credentials
+
+
+ This is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
+
+
+Site credentials can be regenerated. Regenerating credentials will completely invalidate the previous ID and secret. Use
+this feature if you have lost the secret and need to reset the credentials, or if you wish to rotate credentials on a
+regular basis for extra security.
+
+To regenerate credentials, visit Sites > Your Site > Credentials in the Pangolin admin dashboard.
+
+### Regenerate vs. Regenerate and Disconnect
+
+Regenerate simply recreates the credentials and invalidates the old ones. The site will remain connected until you
+restart it with the new credentials.
+
+Regenerate and Disconnect recreates the credentials and invalides the old ones. The site will instantly disconnect and
+will require you to restart it with the new credentials.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Understanding_Sites.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Understanding_Sites.md
new file mode 100644
index 00000000..a382e2cc
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Understanding_Sites.md
@@ -0,0 +1,76 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Understanding Sites
+
+> Create a site to connect to a remote network and expose resources
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+A site is a connection to a network where your resources live. Pangolin uses sites to make public and private resources
+available to users. Every resource belongs to one or more sites. Newt is Pangolin's connector that establishes this
+connection and routes traffic to targets on remote networks.
+
+## The Basics
+
+* **Tunneled sites should always run behind a firewall.** Do not expose a site directly to the public internet.
+* **Users do not connect to a site directly.** Admins define public (browser-based) or private resources on the site's
+ network, and users connect to those resources.
+* **You can run one or multiple sites per network.** You need at least one site to provide access, but you can run
+ multiple sites in the same network for redundancy.
+* **Sites are software-defined proxies and deny traffic by default.** Deploying a site does not automatically expose
+ hosts. Admins must define resources and assign access.
+
+## Site Types
+
+Pangolin supports three different types of sites, each designed for different use cases and deployment scenarios.
+
+### Newt Site (Recommended)
+
+This site type exposes resources on a remote network through a managed tunnel and websocket connection. It requires the
+Newt connector on the remote network. This is the easiest setup and does not require NAT configuration.
+
+Use Newt sites in most deployments. Newt is the primary connector type and supports the broadest feature set.
+
+Newt sites support:
+
+* Public HTTPS proxied resources
+* Private resources
+* Load balancing
+* Health checking
+* Docker socket scanning
+* And more
+
+### Local Site
+
+Use this to expose resources on the same host as your Pangolin server (self-hosted only). No tunnels are created.
+Required ports must be open on the Pangolin host.
+
+Use local sites when the resource runs on the same machine as your self-hosted Pangolin instance.
+
+Local sites do not support:
+
+* Private resources
+* Health checking
+* Docker socket scanning
+
+### Basic WireGuard Site
+
+This option is self-hosted only. It uses a raw WireGuard connection without Newt, so there is no websocket control
+channel and setup is more manual. NAT is required to reach targets on other hosts in the remote network. Without NAT,
+you can expose only resources on the WireGuard peer host itself.
+
+In general, use Basic WireGuard sites only for specific advanced use cases.
+
+Basic WireGuard sites do not support:
+
+* Using LAN-style addresses as targets
+* Private resources
+* Health checking
+* Docker socket scanning
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Update_Sites.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Update_Sites.md
new file mode 100644
index 00000000..e04adf46
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Update_Sites.md
@@ -0,0 +1,59 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Update Sites
+
+> Update Newt to the latest version
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+The update process depends on how you originally installed Newt.
+
+Find the latest version in the [GitHub releases](https://github.com/fosrl/newt/releases).
+
+## Docker Installation
+
+Update the image version in your `docker-compose.yml`:
+
+```yaml title="docker-compose.yml" theme={null}
+services:
+ newt:
+ image: fosrl/newt:{version} # Replace {version} with the latest version tag
+ # ... rest of config
+```
+
+Then pull and restart:
+
+```bash theme={null}
+docker compose pull newt
+docker compose up -d newt
+```
+
+## Binary Installation
+
+### Auto Installer (Recommended)
+
+If you used the auto installer, simply run it again.
+
+```bash theme={null}
+curl -fsSL https://static.pangolin.net/get-newt.sh | bash
+```
+
+### Manual Installation
+
+Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/newt/releases) and replace
+your existing binary.
+
+```bash theme={null}
+wget -O newt "https://github.com/fosrl/newt/releases/download/{version}/newt_{architecture}" && chmod +x ./newt
+```
+
+
+ Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/newt/releases) for the latest information.
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Cloudflare_Proxy.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Cloudflare_Proxy.md
new file mode 100644
index 00000000..b1b308e0
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Cloudflare_Proxy.md
@@ -0,0 +1,163 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Cloudflare Proxy
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Pangolin works with Cloudflare proxy (orange cloud) enabled, but requires specific configuration:
+
+
+ **Terms of Service**: Enabling Cloudflare proxy binds you to Cloudflare's terms of service as traffic routes through their network.
+
+
+### 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)
+
+
+ Pangolin will **not work** with Cloudflare's Full or Automatic SSL/TLS modes. Only Full (Strict) mode is supported.
+
+
+### 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 theme={null}
+gerbil:
+ base_endpoint: "YOUR_VPS_IP_ADDRESS" # Required with Cloudflare proxy
+```
+
+
+
+ Find your VPS public IP address:
+
+ ```bash theme={null}
+ curl ifconfig.io
+ ```
+
+
+
+
+ Add the IP to your `config.yml`:
+
+ ```yaml theme={null}
+ gerbil:
+ base_endpoint: "104.21.16.1" # Replace with your actual IP
+ ```
+
+
+
+
+ Restart Pangolin to apply the changes:
+
+ ```bash theme={null}
+ docker-compose restart
+ ```
+
+
+
+
+### Getting the Real Client IP
+
+Pangolin needs to know the original client IP address for features like rate limiting and logging. When Cloudflare proxy
+is enabled, the API server sees Cloudflare's IP instead of the real client IP.
+
+**Badger**, Pangolin's middleware for Traefik, automatically handles Cloudflare proxy IP extraction. Badger versions
+1.3.0 and later automatically:
+
+* Trust Cloudflare IP ranges
+* Extract the real client IP from the `CF-Connecting-IP` header
+* Set `X-Real-IP` and `X-Forwarded-For` headers for downstream services
+
+
+ **Automatic Configuration**: Pangolin installer versions 1.14.0 and greater automatically add Badger to all Pangolin routes in Traefik. If you're using a newer installer, no manual configuration is needed.
+
+
+#### Manual Configuration
+
+If you're using an older installer or need to manually configure Badger, add it to your Traefik configuration. Badger
+must be applied to all routers that handle Pangolin traffic (API, dashboard, and WebSocket routes):
+
+```yaml title="dynamic_config.yml" theme={null}
+http:
+ middlewares:
+ badger:
+ plugin:
+ badger:
+ disableForwardAuth: true
+
+ routers:
+ # Next.js router (handles dashboard)
+ next-router:
+ rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)"
+ service: next-service
+ entryPoints:
+ - websecure
+ middlewares:
+ - badger
+ tls:
+ certResolver: letsencrypt
+
+ # API router (handles /api/v1 paths)
+ api-router:
+ rule: "Host(`pangolin.example.com`) && PathPrefix(`/api/v1`)"
+ service: api-service
+ entryPoints:
+ - websecure
+ middlewares:
+ - badger
+ tls:
+ certResolver: letsencrypt
+
+ # WebSocket router
+ ws-router:
+ rule: "Host(`pangolin.example.com`)"
+ service: api-service
+ entryPoints:
+ - websecure
+ middlewares:
+ - badger
+ tls:
+ certResolver: letsencrypt
+```
+
+**Why Badger is needed**: When `disableForwardAuth: true` is set, Badger extracts the real client IP from Cloudflare
+proxy headers without performing authentication. This is necessary because forward authentication is only needed for
+resources controlled by Pangolin, not for the main application routes. However, the main Pangolin containers and APIs
+still need the real client IP for proper rate limiting and IP tracking.
+
+#### Pangolin Configuration
+
+Set `trust_proxy: 2` in your Pangolin config file. This tells Pangolin to trust the second-level proxy (Traefik is proxy
+1, Cloudflare is proxy 2):
+
+```yaml theme={null}
+server:
+ trust_proxy: 2
+```
+
+
+ **Update Badger**: Ensure you're running Badger version 1.3.0 or later to get real IP addresses in logs for Public resources. Update Badger if you're using an older version.
+
+
+After making these changes, restart both Traefik and Pangolin for the configuration to take effect.
+
+### Troubleshooting
+
+If websockets are not connecting like from newt or clients, ensure that websockets are enabled in Cloudflare:
+
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Clustering_for_High_Availability.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Clustering_for_High_Availability.md
new file mode 100644
index 00000000..3f0224aa
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Clustering_for_High_Availability.md
@@ -0,0 +1,75 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Clustering for High Availability
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ Clustering is only available in [Enterprise Edition](/self-host/enterprise-edition). [Please reach out to us to deploy](https://pangolin.net/talk-to-us).
+
+
+Deploy multiple Pangolin servers enterprise-grade high availability and performance in large deployments.
+
+## Overview
+
+For organizations requiring maximum uptime and performance, Pangolin supports clustered deployments where multiple
+server instances work together as a unified system. This architecture enables regional distribution, automatic failover,
+and horizontal scaling to handle demanding production workloads.
+
+## How Clustering Works
+
+In a clustered configuration, multiple Pangolin server instances operate together, sharing state and coordinating
+through a Postgres database and Valkey server. Each instance can independently serve user requests, manage
+authentication, and coordinate with multiple Gerbil instances to support thousands of sites.
+
+### Shared Database Backend
+
+All Pangolin instances connect to a shared PostgreSQL database that stores the system's persistent state - including
+user accounts, site configurations, resources, access policies, and organizational settings. This ensures that changes
+made through any server instance are immediately available across the entire cluster.
+
+### Real-time State Synchronization
+
+Redis or Valkey provides real-time state synchronization and pub sub between cluster nodes like active sessions,
+WebSocket connections, and tunnel status. When a user authenticates or a site connector establishes a connection to one
+Pangolin instance, Redis ensures other nodes are aware of these active sessions for failover.
+
+### Tunnel Management with Gerbil
+
+Each Pangolin instance runs alongside its own Gerbil tunnel manager, which handles WireGuard connections to site
+connectors. When a site connector needs to establish a tunnel, it can connect to any available Gerbil instance in the
+cluster. For public resources, Gerbil instances are aware of all of the other nodes in the network and can route
+incoming requests to any other Gerbil to exit through the right site. The distributed architecture ensures that tunnel
+connectivity remains available even if individual nodes fail.
+
+## Benefits of Clustering
+
+**High Availability**: Eliminate single points of failure. If one server instance fails, traffic automatically routes to
+healthy nodes without user disruption.
+
+**Regional Distribution**: Deploy servers closer to your users and sites across different geographic regions to minimize
+latency and improve performance.
+
+**Horizontal Scaling**: Add more server instances to handle increased load as your organization grows, without
+architectural changes.
+
+**Zero-Downtime Updates**: Perform rolling updates by taking nodes offline one at a time while others continue serving
+traffic.
+
+## Enterprise Support
+
+Clustered deployments require careful planning around database replication, Redis configuration, network topology, and
+monitoring. These advanced architectures are available as part of
+Pangolin's [Enterprise Edition](/self-host/enterprise-edition) with dedicated support for design, deployment, and
+ongoing operations.
+
+For organizations interested in clustering for high availability or regional distribution,
+please [contact our enterprise team](https://pangolin.net/talk-to-us) to discuss your requirements and receive
+implementation guidance.
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Configuration_File.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Configuration_File.md
new file mode 100644
index 00000000..f225d2ec
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Configuration_File.md
@@ -0,0 +1,859 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Configuration File
+
+> Configure Pangolin using the config.yml file with detailed settings for all components
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+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" theme={null}
+# To see all available options, please visit the docs:
+# https://docs.pangolin.net/
+
+gerbil:
+ start_port: 51820
+ base_endpoint: "pangolin.example.com" # REPLACE WITH YOUR DOMAIN
+
+app:
+ dashboard_url: "https://pangolin.example.com" # REPLACE WITH YOUR DOMAIN
+ log_level: "info"
+ telemetry:
+ anonymous_usage: true
+
+domains:
+ domain1:
+ base_domain: "example.com" # REPLACE WITH YOUR DOMAIN
+ cert_resolver: "letsencrypt"
+
+server:
+ secret: "your-strong-secret" # REPLACE
+ cors:
+ origins: ["https://pangolin.example.com"] # REPLACE WITH YOUR DOMAIN
+ methods: ["GET", "POST", "PUT", "DELETE", "PATCH"]
+ allowed_headers: ["X-CSRF-Token", "Content-Type"]
+ credentials: false
+
+flags:
+ require_email_verification: false
+ disable_signup_without_invite: true
+ disable_user_create_org: false
+ allow_raw_resources: true
+```
+
+
+ Generate a strong secret for `server.secret`. Use at least 32 characters with a mix of letters, numbers, and special characters.
+
+If you need to CHANGE the server secret after the server has been started you must use the
+`pangctl rotate-server-secret` command to re-encrypt sensitive
+data. [Follow docs here](/self-host/advanced/container-cli-tool#rotate-server-secret).
+
+
+## Reference
+
+This section contains the complete reference for all configuration options in `config.yml`.
+
+### Application Settings
+
+
+ Core application configuration including dashboard URL, logging, and general settings.
+
+
+
+ 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.
+
+
+
+ The logging level for the application.
+
+ **Options**: `debug`, `info`, `warn`, `error`
+
+ **Default**: `info`
+
+
+
+ Whether to save logs to files in the `config/logs/` directory.
+
+ **Default**: `false`
+
+
+ When enabled, logs rotate automatically:
+
+ * Max file size: 20MB
+ * Max files: 7 days
+
+
+
+
+ Whether to log failed authentication attempts for security monitoring.
+
+ **Default**: `false`
+
+
+
+ Telemetry configuration settings.
+
+
+
+ Whether to enable anonymous usage telemetry.
+
+ **Default**: `true`
+
+
+
+
+
+ Notification configuration settings.
+
+
+
+ Whether to enable showing product updates notifications on the UI.
+
+ **Default**: `true`
+
+
+
+ Whether to enable showing new releases notifications on the UI.
+
+ **Default**: `true`
+
+
+
+
+
+
+
+### Server Configuration
+
+
+ Server ports, networking, and authentication settings.
+
+
+
+ The port for the front-end API that handles external requests.
+
+ **Example**: `3000`
+
+
+
+ The port for the internal private-facing API.
+
+ **Example**: `3001`
+
+
+
+ The port for the frontend server (Next.js).
+
+ **Example**: `3002`
+
+
+
+ The port for the integration API (optional).
+
+ **Example**: `3003`
+
+
+
+ The hostname of the Pangolin container for internal communication.
+
+ **Example**: `pangolin`
+
+
+ If using Docker Compose, this should match your container name.
+
+
+
+
+ The name of the session cookie for storing authentication tokens.
+
+ **Example**: `p_session_token`
+
+ **Default**: `p_session_token`
+
+
+
+ Query parameter name for passing access tokens in requests.
+
+ **Example**: `p_token`
+
+ **Default**: `p_token`
+
+
+
+ HTTP headers for passing access tokens in requests.
+
+
+
+ Header name for access token ID.
+
+ **Example**: `P-Access-Token-Id`
+
+
+
+ Header name for access token.
+
+ **Example**: `P-Access-Token`
+
+
+
+
+
+ Query parameter for session request tokens.
+
+ **Example**: `p_session_request`
+
+ **Default**: `p_session_request`
+
+
+
+ Cross-Origin Resource Sharing (CORS) configuration.
+
+
+
+ Allowed origins for cross-origin requests.
+
+ **Example**: `["https://pangolin.example.com"]`
+
+
+
+ Allowed HTTP methods for CORS requests.
+
+ **Example**: `["GET", "POST", "PUT", "DELETE", "PATCH"]`
+
+
+
+ Allowed HTTP headers in CORS requests.
+
+ **Example**: `["X-CSRF-Token", "Content-Type"]`
+
+
+
+ Whether to allow credentials in CORS requests.
+
+ **Default**: `true`
+
+
+
+
+
+ Number of proxy headers to trust for client IP detection.
+
+ **Example**: `1`
+
+ **Default**: `1`
+
+
+ Use `1` if running behind a single reverse proxy like Traefik.
+
+
+
+
+ Dashboard session duration in hours.
+
+ **Example**: `720` (30 days)
+
+ **Default**: `720`
+
+
+
+ Resource session duration in hours.
+
+ **Example**: `720` (30 days)
+
+ **Default**: `720`
+
+
+
+ Secret key for encrypting sensitive data.
+
+ **Environment Variable**: `SERVER_SECRET`
+
+ **Minimum Length**: 8 characters
+
+ **Example**: `"d28@a2b.2HFTe2bMtZHGneNYgQFKT2X4vm4HuXUXBcq6aVyNZjdGt6Dx-_A@9b3y"`
+
+
+ Generate a strong, random secret. This is used for encrypting sensitive data and should be kept secure.
+
+ If you need to CHANGE the server secret after the server has been started you must use the `pangctl rotate-server-secret` command to re-encrypt sensitive data. [Follow docs here](/self-host/advanced/container-cli-tool#rotate-server-secret).
+
+
+
+
+ Path to the MaxMind GeoIP database file for geolocation features.
+
+ **Example**: `./config/GeoLite2-Country.mmdb`
+
+
+ Used for IP geolocation functionality. Requires a MaxMind GeoLite2 or GeoIP2 database file.
+
+
+
+
+
+
+### Domain Configuration
+
+
+ Domain settings for SSL certificates and routing.
+
+At least one domain must be configured.
+
+It is best to add it in the UI for ease of use or when you want the
+domain to *only be present in the org it was created in*.
+
+You should create it in the config file for permanence across installs
+and if you want the domain to be present in all orgs.
+
+
+
+ Domain configuration with a unique key of your choice.
+
+
+
+ The base domain for this configuration.
+
+ **Example**: `example.com`
+
+
+
+ The Traefik certificate resolver name.
+
+ **Example**: `letsencrypt`
+
+
+ This must match the certificate resolver name in your Traefik configuration.
+
+
+
+
+ Whether to prefer wildcard certificates for this domain.
+
+ **Example**: `true`
+
+
+ Useful for domains with many subdomains to reduce certificate management overhead.
+
+
+
+
+
+
+
+
+### Traefik Integration
+
+
+ Traefik reverse proxy configuration settings.
+
+
+
+ The Traefik entrypoint name for HTTP traffic.
+
+ **Example**: `web`
+
+
+ Must match the entrypoint name in your Traefik configuration.
+
+
+
+
+ The Traefik entrypoint name for HTTPS traffic.
+
+ **Example**: `websecure`
+
+
+ Must match the entrypoint name in your Traefik configuration.
+
+
+
+
+ The default certificate resolver for domains created through the UI.
+
+ **Example**: `letsencrypt`
+
+
+ This only applies to domains created through the Pangolin dashboard.
+
+
+
+
+ Whether to prefer wildcard certificates for UI-created domains.
+
+ **Example**: `true`
+
+
+ This only applies to domains created through the Pangolin dashboard.
+
+
+
+
+ Additional Traefik middlewares to apply to resource routers.
+
+ **Example**: `["middleware1", "middleware2"]`
+
+
+ These middlewares must be defined in your Traefik dynamic configuration.
+
+
+
+
+ Path where SSL certificates are stored. This is used only with managed Pangolin deployments.
+
+ **Example**: `/var/certificates`
+
+ **Default**: `/var/certificates`
+
+
+
+ Interval in milliseconds for monitoring configuration changes.
+
+ **Example**: `5000`
+
+ **Default**: `5000`
+
+
+
+ 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`
+
+
+
+ Path to the dynamic router configuration file.
+
+ **Example**: `/var/dynamic/router_config.yml`
+
+ **Default**: `/var/dynamic/router_config.yml`
+
+
+
+ Supported site types for Traefik configuration.
+
+ **Example**: `["newt", "wireguard", "local"]`
+
+ **Default**: `["newt", "wireguard", "local"]`
+
+
+
+ Whether to use file-based configuration mode for Traefik.
+
+ **Example**: `false`
+
+ **Default**: `false`
+
+
+ When enabled, uses file-based dynamic configuration instead of API-based updates.
+
+
+
+
+ Prefix used for transport-related configurations. References servers transport config in dynamic Traefik file.
+
+ **Example**: `pp-transport-v`
+
+ **Default**: `pp-transport-v`
+
+
+
+
+
+### Gerbil Tunnel Controller
+
+
+ Gerbil tunnel controller settings for WireGuard tunneling.
+
+
+
+ Domain name included in WireGuard configuration for tunnel connections.
+
+ **Example**: `pangolin.example.com`
+
+
+
+ Starting port for WireGuard tunnels.
+
+ **Example**: `51820`
+
+
+
+ Starting port for client WireGuard relay and hole punch port.
+
+ **Example**: `21820`
+
+
+
+ Whether to assign unique subdomains to Gerbil exit nodes.
+
+ **Default**: `false`
+
+
+ Keep this set to `false` for most deployments.
+
+
+
+
+ IP address CIDR range for Gerbil exit node subnets.
+
+ **Example**: `10.0.0.0/8`
+
+
+
+ Block size for Gerbil exit node CIDR ranges.
+
+ **Example**: `24`
+
+
+
+ Block size for site CIDR ranges connected to Gerbil.
+
+ **Example**: `26`
+
+
+
+
+
+### Organization Settings
+
+
+ Organization network configuration settings.
+
+
+
+ Block size for organization CIDR ranges.
+
+ **Example**: `24`
+
+ **Default**: `24`
+
+
+ Determines the subnet size allocated to each organization for network isolation.
+
+
+
+
+ IP address CIDR range for organization subnets.
+
+ **Example**: `100.90.128.0/24`
+
+ **Default**: `100.90.128.0/24`
+
+
+ Base subnet from which organization-specific subnets are allocated.
+
+
+
+
+
+
+### Rate Limiting
+
+
+ Rate limiting configuration for API requests.
+
+
+
+ Global rate limit settings for all external API requests.
+
+
+
+ Time window for rate limiting in minutes.
+
+ **Example**: `1`
+
+
+
+ Maximum number of requests allowed in the time window.
+
+ **Example**: `100`
+
+
+
+
+
+ Rate limit settings specifically for authentication endpoints.
+
+
+
+ Time window for authentication rate limiting in minutes.
+
+ **Example**: `1`
+
+ **Default**: `1`
+
+
+
+ Maximum number of authentication requests allowed in the time window.
+
+ **Example**: `10`
+
+ **Default**: `500`
+
+
+ Consider setting this lower than global limits for security.
+
+
+
+
+
+
+
+
+### Email Configuration
+
+
+ SMTP settings for sending transactional emails.
+
+
+
+ SMTP server hostname.
+
+ **Example**: `smtp.gmail.com`
+
+
+
+ SMTP server port.
+
+ **Example**: `587` (TLS) or `465` (SSL)
+
+
+
+ SMTP username.
+
+ **Example**: `no-reply@example.com`
+
+
+
+ SMTP password.
+
+ **Environment Variable**: `EMAIL_SMTP_PASS`
+
+
+
+ Whether to use secure connection (SSL/TLS).
+
+ **Default**: `false`
+
+
+ Enable this when using port 465 (SSL).
+
+
+
+
+ From address for sent emails.
+
+ **Example**: `no-reply@example.com`
+
+
+ Usually the same as `smtp_user`.
+
+
+
+
+ Whether to fail on invalid server certificates.
+
+ **Default**: `true`
+
+
+
+
+
+### Feature Flags
+
+
+ Feature flags to control application behavior.
+
+
+
+ Whether to require email verification for new users.
+
+ **Default**: `false`
+
+
+ Only enable this if you have email configuration set up.
+
+
+
+
+ Whether to disable public user registration.
+
+ **Default**: `false`
+
+
+ Users can still sign up with valid invites when enabled.
+
+
+
+
+ Whether to prevent users from creating organizations.
+
+ **Default**: `false`
+
+
+ Server admins can always create organizations.
+
+
+
+
+ Whether to allow raw TCP/UDP resource creation.
+
+ **Default**: `true`
+
+
+ If set to `false`, users will only be able to create http/https resources.
+
+
+
+
+ Whether to enable the integration API.
+
+ **Default**: `false`
+
+
+
+ Whether to disable local site creation and management.
+
+ **Default**: `false`
+
+
+ When enabled, users cannot create sites that connect to local networks.
+
+
+
+
+ Whether to disable basic WireGuard site functionality.
+
+ **Default**: `false`
+
+
+ When enabled, only advanced WireGuard configurations are allowed.
+
+
+
+
+ Whether to disable product help banners in the UI at the top of screens.
+
+ **Default**: `false`
+
+
+
+ Whether to disable domains managed through the configuration file.
+
+ **Default**: `false`
+
+
+ When enabled, only domains created through the UI are allowed.
+
+
+
+
+ Whether to disable features that are only available in the Enterprise Edition from showing in the UI.
+
+ **Default**: `false`
+
+
+ When enabled, Enterprise-only features are hidden from the UI.
+
+
+
+
+
+
+### Database Configuration
+
+
+ PostgreSQL database configuration (optional).
+
+
+
+ PostgreSQL connection string.
+
+ **Example**: `postgresql://user:password@host:port/database`
+
+
+ See [PostgreSQL documentation](/self-host/advanced/database-options#postgresql) for setup instructions.
+
+
+
+
+ Read-only replica database configurations for load balancing.
+
+
+
+ Connection string for the read replica database.
+
+ **Example**: `postgresql://user:password@replica-host:port/database`
+
+
+
+
+
+ Database connection pool settings.
+
+
+
+ Maximum number of connections to the primary database.
+
+ **Default**: `20`
+
+ **Example**: `50`
+
+
+
+ Maximum number of connections to replica databases.
+
+ **Default**: `10`
+
+ **Example**: `25`
+
+
+
+ Time in milliseconds before idle connections are closed.
+
+ **Default**: `30000` (30 seconds)
+
+ **Example**: `60000`
+
+
+
+ Time in milliseconds to wait for a database connection.
+
+ **Default**: `5000` (5 seconds)
+
+ **Example**: `10000`
+
+
+
+
+
+
+
+## Environment Variables
+
+Some configuration values can be set using environment variables for enhanced security:
+
+| Name | Variable | Config |
+|------------------------------|------------------------------|------------------------------|
+| Server Secret | `SERVER_SECRET` | `server.secret` |
+| Email Password | `EMAIL_SMTP_PASS` | `email.smtp_pass` |
+| PostgreSQL Connection String | `POSTGRES_CONNECTION_STRING` | `postgres.connection_string` |
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Database_Options.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Database_Options.md
new file mode 100644
index 00000000..1afb0bd5
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Database_Options.md
@@ -0,0 +1,109 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Database Options
+
+> Configure SQLite or PostgreSQL database for Pangolin
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Pangolin supports two database options: SQLite for simplicity and PostgreSQL for production deployments.
+
+
+
+ * No configuration required
+ * Easy to use and portable
+ * Built into the main image
+ * Perfect for development
+
+
+
+ * Production-ready database
+ * Better performance at scale
+ * Requires separate image
+ * Advanced configuration options
+
+
+
+## SQLite
+
+By default, Pangolin uses SQLite for its ease of use and portability.
+
+**Docker Image**: `fosrl/pangolin:`
+
+
+ No configuration is required to use SQLite with Pangolin.
+
+
+## PostgreSQL
+
+You can optionally use PostgreSQL for production deployments.
+
+**Docker Image**: `fosrl/pangolin:postgresql-`
+
+### Configuration
+
+Add the following section to your Pangolin configuration file:
+
+```yaml title="config.yml" theme={null}
+postgres:
+ connection_string: postgresql://:@:/
+```
+
+
+ Replace the placeholders with your actual PostgreSQL connection details.
+
+
+### 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" theme={null}
+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
+```
+
+
+ This example is not necessarily production-ready. Adjust the configuration according to your needs and security requirements.
+
+
+
+ Do not use `latest` tags in production. Use specific version tags for stability.
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Enable_ASN_Blocking.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Enable_ASN_Blocking.md
new file mode 100644
index 00000000..dc993954
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Enable_ASN_Blocking.md
@@ -0,0 +1,83 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Enable ASN Blocking
+
+> Configuration requirements to enable ASN blocking in Pangolin
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+To enable ASN blocking in Pangolin Community you must download and place the Maxmind ASN database into the `config/`
+directory and update the config file. This can be done for free.
+
+
+ Remember to keep the ASN database updated regularly, as ASN assignments and network mappings can change over time. You can just repeat the download and extraction steps periodically to ensure your database is current.
+
+
+
+ It is possible to automate this process with a Docker container from Maxmind themself.
+ Have a look at this [Community guide](/self-host/community-guides/geolite2automation) on how to implement this!
+
+
+You can use the installer to download and place the database for you, just grab the latest installer:
+
+```bash theme={null}
+curl -fsSL https://static.pangolin.net/get-installer.sh | bash
+```
+
+Then run the installer again:
+
+```bash theme={null}
+./installer
+```
+
+### Manual Installation Steps
+
+
+
+ Download and extract the GeoLite2 ASN database using the following commands:
+
+ ```bash theme={null}
+ # Download the GeoLite2 ASN database
+ curl -L -o GeoLite2-ASN.tar.gz https://github.com/GitSquared/node-geolite2-redist/raw/refs/heads/master/redist/GeoLite2-ASN.tar.gz
+
+ # Extract the database
+ tar -xzf GeoLite2-ASN.tar.gz
+
+ # Move the .mmdb file to the config directory
+ mv GeoLite2-ASN_*/GeoLite2-ASN.mmdb config/
+
+ # Clean up the downloaded files
+ rm -rf GeoLite2-ASN.tar.gz GeoLite2-ASN_*
+ ```
+
+
+
+
+ Update your Pangolin configuration to point to the new ASN database file. Edit your `config/config.yml` file to include the following entry:
+
+ ```yaml theme={null}
+ server:
+ maxmind_asn_path: "./config/GeoLite2-ASN.mmdb"
+ ```
+
+
+
+
+ Restart your Pangolin instance to apply the changes:
+
+ ```bash theme={null}
+ docker compose restart pangolin
+ ```
+
+
+
+
+Alternatively you can create an account at [Maxmind](https://www.maxmind.com/en/geolite2/signup) to get a license key
+and download the database directly from them.
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Enable_Geo-blocking.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Enable_Geo-blocking.md
new file mode 100644
index 00000000..592aa254
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Enable_Geo-blocking.md
@@ -0,0 +1,83 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Enable Geo-blocking
+
+> Configuration requirements to enable geoblocking in Pangolin
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+To enable geoblocking in Pangolin Community you must download and place the Maxmind geoip database into the `config/`
+directory and update the config file. This can be done for free.
+
+
+ Remember to keep the GeoIP database updated regularly, as IP-to-country mappings can change over time. You can just repeat the download and extraction steps periodically to ensure your database is current.
+
+
+
+ It is possible to automate this process with a Docker container from Maxmind themself.
+ Have a look at this [Community guide](/self-host/community-guides/geolite2automation) on how to implement this!
+
+
+You can use the installer to download and place the database for you, just grab the latest installer:
+
+```bash theme={null}
+curl -fsSL https://static.pangolin.net/get-installer.sh | bash
+```
+
+Then run the installer again:
+
+```bash theme={null}
+./installer
+```
+
+### Manual Installation Steps
+
+
+
+ Download and extract the GeoLite2 Country database using the following commands:
+
+ ```bash theme={null}
+ # Download the GeoLite2 Country database
+ curl -L -o GeoLite2-Country.tar.gz https://github.com/GitSquared/node-geolite2-redist/raw/refs/heads/master/redist/GeoLite2-Country.tar.gz
+
+ # Extract the database
+ tar -xzf GeoLite2-Country.tar.gz
+
+ # Move the .mmdb file to the config directory
+ mv GeoLite2-Country_*/GeoLite2-Country.mmdb config/
+
+ # Clean up the downloaded files
+ rm -rf GeoLite2-Country.tar.gz GeoLite2-Country_*
+ ```
+
+
+
+
+ Update your Pangolin configuration to point to the new GeoIP database file. Edit your `config/config.yml` file to include the following entry:
+
+ ```yaml theme={null}
+ server:
+ maxmind_db_path: "./config/GeoLite2-Country.mmdb"
+ ```
+
+
+
+
+ Restart your Pangolin instance to apply the changes:
+
+ ```bash theme={null}
+ docker compose restart pangolin
+ ```
+
+
+
+
+Alternatively, you can create an account at [Maxmind](https://www.maxmind.com/en/geolite2/signup) to get a license key
+and download the database directly from them.
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Enable_Integration_API.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Enable_Integration_API.md
new file mode 100644
index 00000000..310e5417
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Enable_Integration_API.md
@@ -0,0 +1,82 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Enable Integration API
+
+> Enable and configure the Integration API for external access
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+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" theme={null}
+flags:
+ enable_integration_api: true
+```
+
+If you want to specify a port other than the default `3003`, you can do so in the config as well:
+
+```yaml title="config.yml" theme={null}
+server:
+ integration_port: 3003 # Specify different port
+```
+
+## Configure Traefik Routing
+
+Add the following configuration to your `config/traefik/dynamic_config.yml` to expose the Integration API at
+`https://api.example.com/v1`:
+
+```yaml title="dynamic_config.yml" theme={null}
+ routers:
+ # Add the following two routers
+ int-api-router-redirect:
+ rule: "Host(`api.example.com`)"
+ service: int-api-service
+ entryPoints:
+ - web
+ middlewares:
+ - redirect-to-https
+ - badger # If you have Badger >=1.3.0 and it's enabled in the middlewares section of the dynamic config
+
+ int-api-router:
+ rule: "Host(`api.example.com`)"
+ service: int-api-service
+ entryPoints:
+ - websecure
+ tls:
+ certResolver: letsencrypt
+
+ services:
+ # Add the following service
+ int-api-service:
+ loadBalancer:
+ servers:
+ - url: "http://pangolin:3003"
+```
+
+## Access Documentation
+
+Once configured, access the Swagger UI documentation at:
+
+```
+https://api.example.com/v1/docs
+```
+
+
+
+
+
+
+ The Integration API will be accessible at `https://api.example.com/v1` for external applications.
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Internal_CLI-pangctl.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Internal_CLI-pangctl.md
new file mode 100644
index 00000000..60b9e0c9
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Internal_CLI-pangctl.md
@@ -0,0 +1,135 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Internal CLI (pangctl)
+
+> Command-line tool for managing your Pangolin instance
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+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 theme={null}
+docker exec -it pangolin pangctl
+```
+
+## Available Commands
+
+To see all available commands:
+
+```bash theme={null}
+docker exec -it pangolin pangctl --help
+```
+
+## Set Admin Credentials
+
+Set or reset admin credentials for your Pangolin instance:
+
+```bash theme={null}
+docker exec -it pangolin pangctl set-admin-credentials --email "admin@example.com" --password "Password123!"
+```
+
+
+ Use a strong password and keep your admin credentials secure.
+
+
+## Clear Exit Nodes
+
+Clear all exit nodes from the database:
+
+```bash theme={null}
+docker exec -it pangolin pangctl clear-exit-nodes
+```
+
+
+ This command permanently deletes all exit nodes from the database. This action cannot be undone.
+
+
+## Reset User Security Keys
+
+Reset a user's security keys (passkeys) by deleting all their webauthn credentials:
+
+```bash theme={null}
+docker exec -it pangolin pangctl reset-user-security-keys --email "user@example.com"
+```
+
+
+ This command permanently deletes all security keys for the specified user. The user will need to re-register their security keys to use passkey authentication again.
+
+
+## Rotate Server Secret
+
+Rotate the server secret by decrypting all encrypted values with the old secret and re-encrypting with a new secret.
+This command updates OIDC IdP configurations and license keys in the database, as well as the config file.
+
+```bash theme={null}
+docker exec -it pangolin pangctl rotate-server-secret --old-secret "current-secret" --new-secret "new-secret"
+```
+
+### Options
+
+* `--old-secret` (required): The current server secret (for verification)
+* `--new-secret` (required): The new server secret to use (must be at least 8 characters long)
+* `--force` (optional): Force rotation even if the old secret doesn't match the config file. Use this if you know the
+ old secret is correct but the config file is out of sync.
+
+
+ This command performs a critical operation that affects all encrypted data in your database. Ensure you have a backup before running this command.
+
+**Important considerations:**
+
+* The new secret must be at least 8 characters long
+* The new secret must be different from the old secret
+* The command verifies the old secret matches the config file (unless `--force` is used)
+* After rotation, you must restart the server for the new secret to take effect
+* Using `--force` with an incorrect old secret will cause the rotation to fail or corrupt encrypted data
+
+
+## Clear License Keys
+
+Clear all license keys from the database:
+
+```bash theme={null}
+docker exec -it pangolin pangctl clear-license-keys
+```
+
+
+ This command permanently deletes all license keys from the database. This action cannot be undone.
+
+
+## Delete Client
+
+Delete a client and all associated data (OLMs, current fingerprint, userClients, approvals). Snapshots are preserved.
+
+```bash theme={null}
+docker exec -it pangolin pangctl delete-client --orgId "org-123" --niceId "client-identifier"
+```
+
+### Options
+
+* `--orgId` (required): The organization ID
+* `--niceId` (required): The client niceId (identifier)
+
+
+ This command permanently deletes the client and its associated data:
+
+* All OLMs (One-time Login Mechanisms) associated with the client
+* Current fingerprint entries
+* Approval records
+* UserClient associations
+
+**Note:** Snapshots are preserved and will not be deleted.
+
+This action cannot be undone. Ensure you have backups if needed.
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Metrics.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Metrics.md
new file mode 100644
index 00000000..be7f75a7
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Metrics.md
@@ -0,0 +1,868 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Metrics
+
+> Enable and consume OpenTelemetry & vendor specific metrics
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+The `privateConfig.yml` file provides advanced configuration options for enterprise deployments. This file is mounted at
+`config/privateConfig.yml` in your Docker container.
+
+
+ The private configuration file is only used on enterprise deployments. If you're using Pangolin Community, refer to the [main configuration file documentation](/self-host/advanced/config-file) instead. The private config file is not required.
+
+
+## Setting up your `privateConfig.yml`
+
+Here's a basic example with common settings:
+
+```yaml title="private-config.yml" theme={null}
+app:
+ identity_provider_mode: "org"
+
+branding:
+ app_name: "My Company Portal"
+ hide_auth_layout_footer: false
+```
+
+## Reference
+
+This section contains the complete reference for all configuration options in `private-config.yml`.
+
+### Application Settings
+
+
+ Regional and base domain configuration for multi-region deployments.
+
+
+
+ Set the identity provider (IdP) mode for authentication. By default both global and org pages will show until set. See the [Identity Providers documentation](/manage/identity-providers/add-an-idp#identity-provider-types) for more details on how this affects authentication and user management.
+
+ Possible values:
+
+ * `global`: (default) Both global and organization-level IdP login pages are available. Users can authenticate using either global or organization-specific identity providers.
+ * `org`: Only organization-level IdP login pages are available. Users must authenticate using identity providers defined at the organization
+
+ ```yaml theme={null}
+ app:
+ identity_provider_mode: "org"
+ ```
+
+
+
+ The region identifier for this Pangolin instance. Used for multi-region deployments.
+
+ ```yaml theme={null}
+ app:
+ region: "us-east-1"
+ ```
+
+
+
+
+
+### Server Configuration
+
+
+ Advanced server configuration including encryption keys and API integrations.
+
+
+
+ Path to the RSA private key used for encrypting sensitive data. Must be at least 8 characters long. THIS IS ONLY USED WITH pangolin\_dns FEATURE FLAG ENABLED AND REQUIRES EXTERNAL COMPONENTS.
+
+ ```yaml theme={null}
+ server:
+ encryption_key_path: "./config/encryption.pem"
+ ```
+
+
+ The `encryption_key_path` must point to a valid RSA key file. Generate one using:
+
+ ```bash theme={null}
+ openssl genrsa -out encryption.pem 4096
+ ```
+
+ Keep this key secure and backed up - it encrypts sensitive data in your database.
+
+
+
+
+
+
+### Redis Configuration
+
+
+ Redis connection settings for caching, sessions, and rate limiting. Useful for clustering Pangolin nodes.
+
+
+
+ Redis server hostname or IP address.
+
+ ```yaml theme={null}
+ redis:
+ host: "redis.example.com"
+ ```
+
+
+
+ Redis server port (1-65535).
+
+ ```yaml theme={null}
+ redis:
+ port: 6379
+ ```
+
+
+
+ Redis authentication password.
+
+ ```yaml theme={null}
+ redis:
+ password: "your-secure-password"
+ ```
+
+
+
+ Redis database number (0-15 typically).
+
+ ```yaml theme={null}
+ redis:
+ db: 0
+ ```
+
+
+
+ Array of read replica configurations for high-availability deployments.
+
+ ```yaml theme={null}
+ redis:
+ host: "redis-primary"
+ port: 6379
+ replicas:
+ - host: "redis-replica-1"
+ port: 6379
+ password: "replica-password"
+ db: 0
+ - host: "redis-replica-2"
+ port: 6379
+ password: "replica-password"
+ db: 0
+ ```
+
+
+
+ Replica server hostname.
+
+
+
+ Replica server port.
+
+
+
+ Replica authentication password.
+
+
+
+ Database number on replica.
+
+
+
+
+
+
+
+### Gerbil Tunnel Configuration
+
+
+ Configuration for the Gerbil tunnel exit node integration.
+
+
+
+ URL where the local Gerbil exit node can be reached by Pangolin. Useful when clustering multiple pangolin nodes. Overrides the value stored in the database. Useful when using Docker and address the local gerbil container using the host's address.
+
+ ```yaml theme={null}
+ gerbil:
+ local_exit_node_reachable_at: "http://gerbil:3004"
+ ```
+
+
+
+
+
+### Feature Flags
+
+
+ Feature toggles for advanced functionality.
+
+
+
+ **DEPRECATED**! See `app.identity_provider_mode: "org"` instead.
+
+ Restrict identity provider (IdP) authentication to organization-level only.
+
+ ```yaml theme={null}
+ flags:
+ use_org_only_idp: true
+ ```
+
+
+
+ Enable Redis for caching and session management. Requires `redis` configuration.
+
+ ```yaml theme={null}
+ flags:
+ enable_redis: true
+ ```
+
+
+
+ Use Pangolin DNS servers for client connections instead of external DNS servers for DNS delegation and CNAME setups. Used for clustering Pangolin nodes. REQUIRES EXTERNAL COMPONENTS. PLEASE CONTACT SUPPORT TO OBTAIN ACCESS BEFORE ENABLING.
+
+ ```yaml theme={null}
+ flags:
+ use_pangolin_dns: true
+ ```
+
+
+
+
+
+### Branding Configuration
+
+Please refer to the [branding configuration documentation](/manage/branding).
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Telemetry.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Telemetry.md
new file mode 100644
index 00000000..ab466c9f
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Telemetry.md
@@ -0,0 +1,55 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Telemetry
+
+> Understanding Pangolin's anonymous usage data collection
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+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 theme={null}
+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.
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Wildcard_Domains.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Wildcard_Domains.md
new file mode 100644
index 00000000..a5b73808
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Wildcard_Domains.md
@@ -0,0 +1,286 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Wildcard Domains
+
+> Configure wildcard SSL certificates for automatic subdomain security with DNS-01 challenge
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+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.
+
+
+ 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.
+
+
+
+ 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.
+
+
+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.
+
+
+ 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.
+
+
+## Benefits of Wildcard Certificates
+
+
+
+ Secure unlimited subdomains with one certificate, reducing management overhead.
+
+
+
+ Add new subdomains without waiting for certificate generation (up to a few minutes).
+
+
+
+ Reduce Let's Encrypt rate limit impact by using fewer certificate requests.
+
+
+
+### 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`
+
+
+ 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.
+
+
+## Setting Up Wildcard Certificates
+
+
+
+ Make sure the stack is not running before making configuration changes.
+
+
+
+ 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.
+
+
+
+ Set the `prefer_wildcard_cert` flag to `true` in the Pangolin configuration file for your domain. This is also configurable in the Pangolin dashboard (once restarted).
+
+ ```yaml title="config.yml" highlight={4} theme={null}
+ domains:
+ domain1:
+ base_domain: "example.com"
+ prefer_wildcard_cert: true
+ ```
+
+
+
+
+
+ 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.
+
+
+## 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.
+
+
+
+ Tell Traefik to use the `web` entrypoint for the HTTP challenge.
+
+ ```yaml title="traefik_config.yml" highlight={4,5} theme={null}
+ certificatesResolvers:
+ letsencrypt:
+ acme:
+ httpChallenge:
+ entryPoint: web
+ email: admin@example.com
+ storage: "/letsencrypt/acme.json"
+ caServer: "https://acme-v02.api.letsencrypt.org/directory"
+ ```
+
+
+
+
+ Set the cert resolver to `letsencrypt` and the entrypoint to `websecure` in the dynamic config.
+
+ ```yaml title="dynamic_config.yml" theme={null}
+ next-router:
+ rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)"
+ service: next-service
+ entryPoints:
+ - websecure
+ tls:
+ certResolver: letsencrypt
+ ```
+
+
+
+
+### Wildcard Config for DNS-01 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} theme={null}
+ 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"
+ ```
+
+
+
+
+ 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={8-12} theme={null}
+ 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"
+ ```
+
+
+
+
+ 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} theme={null}
+ 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
+ ```
+
+
+
+
+
+ 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.
+
+
+
+ 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).
+
+
+## Verify it Works
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+ For debugging purposes, you may find it useful to set the log level of Traefik to `debug` in the `traefik_config.yml` file.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+```json highlight={5} theme={null}
+{
+ "Certificates": [
+ {
+ "domain": {
+ "main": "example.com",
+ "sans": [
+ "*.example.com"
+ ]
+ },
+ "certificate": "...",
+ "key": "...",
+ "Store": "default"
+ }
+ ]
+}
+```
+
+## Troubleshooting
+
+
+
+ **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
+
+
+
+
+ **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
+
+
+
+
+ **Problem**: Traefik using old HTTP-01 certificates.
+
+ **Solution**: Delete the `acme.json` file to force new certificate generation.
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Without_Tunneling.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Without_Tunneling.md
new file mode 100644
index 00000000..4e142591
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Without_Tunneling.md
@@ -0,0 +1,44 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Without Tunneling
+
+> Use Pangolin as a local reverse proxy without Gerbil tunneling
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+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.
+
+
+ You can also use "local" sites to expose resources on the same VPS as Pangolin in addition to remote sites.
+
+
+## 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.
+
+
+ All setup remains the same, except Pangolin and Traefik must now be on the same network as the resources you want to proxy to.
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Choosing_a_VPS.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Choosing_a_VPS.md
new file mode 100644
index 00000000..4496a931
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Choosing_a_VPS.md
@@ -0,0 +1,150 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Choosing a VPS
+
+> Compare hosting options and find the best VPS for your Pangolin deployment
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+Pangolin generally requires minimal resources to run effectively. A basic VPS with **1 vCPU, 1GB RAM, and 8GB SSD** is
+sufficient for most deployments.
+
+
+
+ * **CPU**: 1 vCPU
+ * **RAM**: 1GB
+ * **Storage**: 8GB SSD
+
+
+
+ * **CPU**: 2 vCPU
+ * **RAM**: 2GB
+ * **Storage**: 20GB SSD
+
+
+
+## Recommended Options
+
+
+ We're part of RackNerd's affiliate program. Using our links helps support Pangolin development at no extra cost to you.
+
+
+
+
+ **\$11.29/Year**
+
+ * 1 vCPU, 1GB RAM, 24GB SSD, 2TB Bandwidth
+
+
+
+
+ **\$18.29/Year**
+
+ * 1 vCPU, 2GB RAM, 40GB SSD, 3.5TB Bandwidth
+ * Great value for performance
+
+
+
+
+ **\$32.49/Year**
+
+ * 2 vCPU, 3.5GB RAM, 65GB SSD, 7TB Bandwidth
+
+
+
+
+## DigitalOcean Marketplace
+
+Deploy Pangolin with a single click using the DigitalOcean marketplace. The one-click installer automatically provisions
+a DigitalOcean droplet with Pangolin pre-installed and firewall rules configured.
+
+
+ We're part of the DigitalOcean affiliate program. Using our links helps support Pangolin development at no extra cost to you. If you decide to use the DigitalOcean one-click installer, please use our link.
+
+
+
+
+ View Pangolin on the DigitalOcean marketplace
+
+
+
+ Create your droplet with Pangolin pre-installed
+
+
+
+## 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 | 24GB SSD | \$0.94 | \$11.29 | Budget users |
+| **[RackNerd](https://my.racknerd.com/aff.php?aff=13788)** | Basic | 1 vCPU | 2GB | 40GB SSD | \$1.52 | \$18.29 | Small teams |
+| **[RackNerd](https://my.racknerd.com/aff.php?aff=13788)** | Standard | 2 vCPU | 3.5GB | 65GB SSD | \$2.71 | \$32.49 | 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 |
+
+
+ Prices shown are approximate and may vary based on location, promotions, and currency exchange rates. Check provider websites for current pricing.
+
+
+## Selection Criteria
+
+When choosing your VPS provider, consider these factors:
+
+
+
+ **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
+
+
+
+
+ **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
+
+
+
+
+ **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
+
+
+
+
+ **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
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/CrowdSec.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/CrowdSec.md
new file mode 100644
index 00000000..da75c2d8
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/CrowdSec.md
@@ -0,0 +1,226 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# CrowdSec
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ 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).
+
+
+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 theme={null}
+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 theme={null}
+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 theme={null}
+iptables -A INPUT -j LOG --log-prefix "iptables: "
+```
+
+Update the `docker-compose.yml` file as follows:
+
+```yaml theme={null}
+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 theme={null}
+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 theme={null}
+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 theme={null}
+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 theme={null}
+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 theme={null}
+nano /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml
+```
+
+5. Restart the firewall bouncer:
+
+```bash theme={null}
+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 theme={null}
+service:
+ crowdsec:
+ ports:
+ - 6060:6060 # Metrics port
+ - 8080:8080 # Local API port
+```
+
+
+ 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).
+
+
+7. Verify communication between the firewall bouncer and the CrowdSec container by running:
+
+```bash theme={null}
+docker exec crowdsec cscli metrics
+```
+
+The output should look like this:
+
+```bash theme={null}
++------------------------------------------------------------------+
+| 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 theme={null}
+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 theme={null}
+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 theme={null}
+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 `` with
+ your captcha provider (MUST BE either `hcaptcha`, `recaptcha`, or `turnstile`), and `` with the appropriate site
+ and secret keys:
+
+```yaml theme={null}
+http:
+ middlewares:
+ crowdsec:
+ plugin:
+ crowdsec:
+ captchaHTMLFilePath: /etc/traefik/captcha.html
+ captchaGracePeriodSeconds: 300
+ captchaProvider:
+ captchaSiteKey:
+ captchaSecretKey:
+```
+
+## 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 theme={null}
+docker exec crowdsec cscli decisions add --ip -d 1m --type ban
+```
+
+To trigger a captcha challenge:
+
+```bash theme={null}
+docker exec crowdsec cscli decisions add --ip -d 1m --type captcha
+```
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/GeoLite2_Automation.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/GeoLite2_Automation.md
new file mode 100644
index 00000000..0e10a0c2
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/GeoLite2_Automation.md
@@ -0,0 +1,148 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# GeoLite2 Automation
+
+> A simple automation to download & update your GeoLite2 databases with geoipupdate
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ This is a community guide and is not officially supported. If you have any issues, please reach out to the [author](https://github.com/txwgnd).
+
+
+This automation lets your system automatically download & upgrade the `GeoLite2-Country` and `GeoLite2-ASN` databases
+from Maxmind to use for geoblocking and ASN blocking on your Pangolin host. It's utilizing Maxmind'
+s [geoipupdate](https://github.com/maxmind/geoipupdate/tree/main) Docker container to achieve this.
+
+Maxmind's service is free of charge for development, personal or community
+use. [Quote](https://support.maxmind.com/knowledge-base/articles/create-a-maxmind-account#h_01G4G4NG5C63BQ6HRG6MSS50T3)
+
+# Table of Contents
+
+1. **[Requirements](#1-requirements)**
+2. **[Maxmind Account](#2-maxmind-account)**
+3. **[API key creation](#3-api-key-creation)**
+4. **[Modification of Pangolin's `docker-compose.yml`](#4-modification-of-pangolin’s-docker-compose-yml)**
+5. **[Modification of Pangolin's `config.yml`](#5-modification-of-pangolin’s-config-yml)**
+
+## 1. Requirements
+
+* A Maxmind account for API access
+* Pangolin version 1.11.0 or higher
+
+## 2. Maxmind Account
+
+To be able to use Maxmind's service you need to request access to the GeoLite2 databases and create an account on
+their [website](https://www.maxmind.com/en/geolite2/signup?utm_source=kb\&utm_medium=kb-link\&utm_campaign=kb-create-account).
+
+After you successfully created an account visit the mainpage again and login to your new account.
+
+## 3. API key creation
+
+The next step is to create an API key for `geoipupdate`. You'll find an entry called `Manage license keys` in the menu
+on the left side. Head to this page and click on `Generate new license key`.
+
+
+
+
+
+Give your new key a name. E.g. `Pangolin`.
+
+
+
+
+
+After your key got created the webpage will show you your Account ID as well as the API key. Save the key now because it
+can only be seen once. Don't panic if something goes wrong, you can easily create new keys.
+
+
+
+
+
+After you clicked on `Return to list` you should see an overview of your keys bundled with some metadata.
+
+## 4. Modification of Pangolin's `docker-compose.yml`
+
+Now login to your Pangolin host and navigate to `/pangolin` in your user directory:
+
+```bash theme={null}
+cd pangolin
+```
+
+Shut down Pangolin with:
+
+```bash theme={null}
+docker compose down
+```
+
+Open `docker-compose.yml` with your favorite text editor.
+E.g. nano:
+
+```bash theme={null}
+nano docker-compose.yml
+```
+
+Append this Docker compose service at the end of your stack and add your Account ID as well as your API key you created
+in the last step:
+
+```yaml theme={null}
+services:
+ (...)
+ geoipupdate:
+ container_name: geoipupdate
+ image: ghcr.io/maxmind/geoipupdate
+ restart: unless-stopped
+ environment:
+ - 'GEOIPUPDATE_ACCOUNT_ID=' # Account ID
+ - 'GEOIPUPDATE_LICENSE_KEY=' # API key
+ - 'GEOIPUPDATE_EDITION_IDS=GeoLite2-Country GeoLite2-ASN' # Which dbs should be downloaded
+ - 'GEOIPUPDATE_FREQUENCY=72' # Update intervall in hours
+ volumes:
+ - './config/GeoLite2:/usr/share/GeoIP'
+```
+
+#### Note
+
+If you use the standard Pangolin deployment you shouldn't need to modify the path.
+This is the bare minimum to run the container. There are other optional environment variables available. Have a look at
+their [docs](https://dev.maxmind.com/geoip/updating-databases/?lang=en)!
+
+Save and close the file, but don't restart the stack yet!
+
+## 5. Modification of Pangolin's config.yml
+
+Navigate to `/config` within the same folder and open it with a text editor.
+
+```bash theme={null}
+cd config
+```
+
+Add these lines to the `server` object
+
+```yaml theme={null}
+server:
+ maxmind_db_path: "./config/GeoLite2/GeoLite2-Country.mmdb"
+ maxmind_asn_path: "./config/GeoLite2/GeoLite2-ASN.mmdb"
+```
+
+These entries tell the Pangolin application where to find the databases.
+
+Save and close the file then navigate to the `pangolin` folder one level higher.
+
+Restart your Pangolin stack with:
+
+```bash theme={null}
+docker compose up -d
+```
+
+Et voilà, you are now able to define country rules and ASN rules for your ressources! 🏁
+
+btw: you can use these exact databases for your Traefik dashboard
+too -> [Community Guide](/self-host/community-guides/traefiklogsdashboard)
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Home_Assistant_Add-on.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Home_Assistant_Add-on.md
new file mode 100644
index 00000000..655d22ff
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Home_Assistant_Add-on.md
@@ -0,0 +1,157 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Home Assistant Add-on
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ 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).
+
+
+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 theme={null}
+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 theme={null}
+http:
+ use_x_forwarded_for: true
+ trusted_proxies:
+ - 127.0.0.1
+homeassistant:
+ allowlist_external_urls:
+ - "https://.example.com" # <-- Replace with URL of created resource in Pangolin
+```
+
+4.5: If you want 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/rules).
+
+Many thanks to steuerlexi for finding this out!
+
+[https://github.com/fosrl/pangolin/issues/757#issuecomment-2903774897](https://github.com/fosrl/pangolin/issues/757#issuecomment-2903774897)
+
+
+ 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.
+
+
+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 theme={null}
+ 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 theme={null}
+ 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/)
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Metrics.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Metrics.md
new file mode 100644
index 00000000..eb62ea6f
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Metrics.md
@@ -0,0 +1,210 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Metrics
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ 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).
+
+
+This is a basic example of collecting metrics from Traefik and CrowdSec using Prometheus and visualizing them with
+Grafana dashboards.
+
+
+ Important for users with low-powered server (1GB RAM):
+ This setup will increase the use of your server RAM.
+
+
+## Configuration
+
+### Traefik
+
+For claiming metrics from Traefik we have to adjust some configuration files.
+
+1. Update the `docker-compose.yml` file of the Pangolin stack to expose metrics port `8082` for the Prometheus
+ connection:
+
+```yaml theme={null}
+service:
+ gerbil:
+ ports:
+ - 8082:8082
+```
+
+
+ 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).
+
+
+2. Update the `/config/traefik/traefik_config.yml` file to include the following:
+
+```yaml theme={null}
+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 theme={null}
+sudo docker restart traefik gerbil
+```
+
+### Crowdsec
+
+For claiming metrics from Crowdsec we have to adjust the docker compose files.
+
+1. Update the `docker-compose.yml` file of the Pangolin stack to expose metrics port `6060` for the Prometheus
+ connection:
+
+```yaml theme={null}
+service:
+ crowdsec:
+ ports:
+ - 6060:6060
+```
+
+
+ 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).
+
+
+2. Restart the Crowdsec container to apply the changes:
+
+```bash theme={null}
+sudo docker restart crowdsec
+```
+
+## Prometheus
+
+1. Create a new Prometheus container or add it to `docker-compose.yml` of Pangolin stack:
+
+```yaml theme={null}
+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
+```
+
+
+ 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).
+
+
+2. Create a `prometheus.yml` file in the `/config/prometheus` directory with the following content:
+
+```yaml theme={null}
+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 owner and owning group:
+
+```bash theme={null}
+chown nobody:nogroup data
+```
+
+4. Start the Prometheus container:
+
+```bash theme={null}
+sudo docker compose up -d
+```
+
+## Grafana
+
+1. Create a new Grafana container or add it to `docker-compose.yml` of Pangolin stack:
+
+```yaml theme={null}
+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
+```
+
+
+ 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).
+
+
+2. Start the Grafana container:
+
+```bash theme={null}
+sudo docker compose up -d
+```
+
+
+ Default login credentials for Grafana admin user is admin:admin.
+
+
+### 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
+
+
+
+
+
+Template Import ID = 17346
+
+[https://grafana.com/grafana/dashboards/17346-traefik-official-standalone-dashboard/](https://grafana.com/grafana/dashboards/17346-traefik-official-standalone-dashboard/)
+
+#### Crowdsec
+
+[https://github.com/crowdsecurity/grafana-dashboards/tree/master](https://github.com/crowdsecurity/grafana-dashboards/tree/master)
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Middleware_Manager.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Middleware_Manager.md
new file mode 100644
index 00000000..bdd5d781
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Middleware_Manager.md
@@ -0,0 +1,183 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Middleware Manager
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ 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).
+
+
+## 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.
+
+#### 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 theme={null}
+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 theme={null}
+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 theme={null}
+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 theme={null}
+providers:
+ file:
+ directory: "/rules"
+ watch: true
+```
+
+***
+
+## Step 4: Start Services
+
+```bash theme={null}
+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 theme={null}
+middlewares:
+ - id: "rate-limit"
+ type: "rateLimit"
+ config:
+ average: 100
+ burst: 50
+```
+
+### Security Headers
+
+```yaml theme={null}
+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.
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Overview.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Overview.md
new file mode 100644
index 00000000..928b3330
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Overview.md
@@ -0,0 +1,97 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Overview
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ 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://pangolin.net/discord) or [Github discussions](https://github.com/orgs/fosrl/discussions).
+
+
+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.
+
+
+ Pangolin now supports native geoblocking. The GeoBlock plugin is considered legacy in Pangolin setups. If you previously installed it, follow [Remove GeoBlock Plugin](/self-host/community-guides/remove-geoblock-plugin) before enabling native geoblocking.
+
+
+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 visualize 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)
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Remove_GeoBlock_Plugin.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Remove_GeoBlock_Plugin.md
new file mode 100644
index 00000000..96b0e067
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Remove_GeoBlock_Plugin.md
@@ -0,0 +1,83 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Remove GeoBlock Plugin
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ This is a community guide and is not officially supported. If you have any issues, please reach out to the community on [Discord](https://pangolin.net/discord) or [Github discussions](https://github.com/orgs/fosrl/discussions).
+
+
+Pangolin now supports native geoblocking. If you previously installed the Traefik GeoBlock plugin, remove it before
+enabling native geoblocking to avoid duplicate blocking or startup errors.
+
+
+ After cleanup, follow [Enable Geo-blocking](/self-host/advanced/enable-geoblocking) to configure native geoblocking in Pangolin.
+
+
+## Remove the GeoBlock plugin
+
+
+
+ Remove any references to `geoblock@file` from your Traefik entry points, routers, or labels.
+
+ Example removal in `/config/traefik/traefik_config.yml`:
+
+ ```yaml theme={null}
+ entryPoints:
+ websecure:
+ http:
+ middlewares:
+ # Remove this line
+ - geoblock@file
+ ```
+
+
+
+
+ Delete the GeoBlock plugin block from `/config/traefik/traefik_config.yml`:
+
+ ```yaml theme={null}
+ experimental:
+ plugins:
+ geoblock:
+ moduleName: github.com/PascalMinder/geoblock
+ version: v0.3.2
+ ```
+
+
+
+
+ Delete the GeoBlock middleware section from `/config/traefik/dynamic_config.yml`:
+
+ ```yaml theme={null}
+ http:
+ middlewares:
+ geoblock:
+ plugin:
+ geoblock:
+ ...
+ ```
+
+
+
+
+ Restart Traefik to apply the changes:
+
+ ```bash theme={null}
+ docker restart traefik
+ ```
+
+
+
+
+## Next steps
+
+Follow [Enable Geo-blocking](/self-host/advanced/enable-geoblocking) to configure native geoblocking in Pangolin.
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Traefik_Log_Dashboard_v2–Agent_Architecture.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Traefik_Log_Dashboard_v2–Agent_Architecture.md
new file mode 100644
index 00000000..c865a55b
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Traefik_Log_Dashboard_v2–Agent_Architecture.md
@@ -0,0 +1,302 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Traefik Log Dashboard (v2 – Agent Architecture)
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+ 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).
+
+
+If you’re already using the **Pangolin stack with Traefik as your reverse proxy**, you already have robust routing in
+place.\
+However, raw logs can be hard to interpret — making it difficult to visualize request patterns, latency, and geographic
+origins.
+
+The **new Traefik Log Dashboard (v2)** introduces a **lightweight agent-based architecture** with **multi-instance
+scalability, enhanced GeoIP analytics, and a modern Next.js frontend** for real-time insights into your Traefik traffic.
+
+***
+
+## Highlights (New in v2)
+
+* **Agent-based architecture**: The Go-powered agent parses logs, exposes metrics, and supports multiple Traefik
+ instances.
+* **Multi-agent support**: Monitor multiple Traefik setups (e.g., production, staging) from one dashboard.
+* **Next.js 14 frontend**: Real-time charts, filters, and system stats in a responsive UI.
+* **Enhanced GeoIP**: Supports both **City** and **Country** MaxMind databases.
+* **System monitoring**: Built-in CPU, memory, and disk tracking.
+* **Bearer token authentication**: Secure access between dashboard and agents.
+* **Backward compatible** with existing Traefik log setups.
+
+***
+
+## Prerequisites
+
+* Docker + Docker Compose
+* Traefik v2.x or v3.x (logs in JSON format)
+* A working **Pangolin stack**
+* (Optional) MaxMind GeoLite2 databases (City + Country)
+
+***
+
+## Step 1: Configure Traefik Logs
+
+Ensure Traefik is outputting **JSON logs** and **access logs** are written to a file.
+
+Update your `./config/traefik/traefik_config.yml`:
+
+```yaml theme={null}
+log:
+ level: INFO
+ filePath: "/var/log/traefik/traefik.log"
+ format: json
+
+accessLog:
+ filePath: "/var/log/traefik/access.log"
+ format: json
+ fields:
+ defaultMode: keep
+ headers:
+ defaultMode: keep
+```
+
+> Tip: JSON format is required for accurate parsing by the new agent.
+
+***
+
+## Step 2: Add Dashboard and Agent Services
+
+Extend your existing `docker-compose.yml` with the new services.
+
+```yaml theme={null}
+# Traefik Log Dashboard Agent
+ traefik-agent:
+ image: hhftechnology/traefik-log-dashboard-agent:latest
+ restart: unless-stopped
+ ports:
+ - "5000:5000"
+ volumes:
+ - ./data/positions:/data
+ - ./config/traefik/logs:/logs:ro
+ - ./config/maxmind:/geoip:ro
+ environment:
+ # Log Paths
+ - TRAEFIK_LOG_DASHBOARD_ACCESS_PATH=/logs/access.log
+ - TRAEFIK_LOG_DASHBOARD_ERROR_PATH=/logs/traefik.log
+
+ # Authentication
+ - TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN=YOUR_API_TOKEN
+
+ # System Monitoring
+ - TRAEFIK_LOG_DASHBOARD_SYSTEM_MONITORING=true
+
+ # GeoIP Configuration
+ - TRAEFIK_LOG_DASHBOARD_GEOIP_ENABLED=true
+ - TRAEFIK_LOG_DASHBOARD_GEOIP_CITY_DB=/geoip/GeoLite2-City.mmdb
+ - TRAEFIK_LOG_DASHBOARD_GEOIP_COUNTRY_DB=/geoip/GeoLite2-Country.mmdb
+
+ # Log Format
+ - TRAEFIK_LOG_DASHBOARD_LOG_FORMAT=json
+
+ # Server Port
+ - PORT=5000
+ healthcheck:
+ test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:5000/api/logs/status"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 10s
+
+ # Traefik Log Dashboard - Web UI
+ traefik-dashboard:
+ image: hhftechnology/traefik-log-dashboard:latest
+ container_name: traefik-log-dashboard
+ restart: unless-stopped
+ ports:
+ - "3000:3000"
+ environment:
+ # Agent Configuration
+ - AGENT_API_URL=http://traefik-agent:5000
+ - AGENT_API_TOKEN=YOUR_API_TOKEN
+ - NODE_ENV=production
+ - PORT=3000
+ depends_on:
+ traefik-agent:
+ condition: service_healthy
+ healthcheck:
+ test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 30s
+```
+
+Please replace the YOUR\_API\_TOKEN with a secure token of your choice.
+
+> Note: The new agent replaces both `log-dashboard-backend` and `log-dashboard-frontend` from the previous guide.
+
+***
+
+## Step 3: Setup MaxMind GeoIP (City + Country)
+
+GeoIP is optional but highly recommended for geographic analytics and maps.
+
+### 1. Create a free MaxMind account
+
+[GeoLite2 Signup](https://www.maxmind.com/en/geolite2/signup)
+Generate a license key and export it for Docker use:
+
+```bash theme={null}
+export MAXMIND_LICENSE_KEY=your_license_key_here
+mkdir -p ./config/maxmind
+```
+
+### 2. Add the GeoIP Database Updater
+
+Append this to your `docker-compose.yml`:
+
+```yaml theme={null}
+ # Optional: MaxMind GeoIP Database Updater
+ maxmind-updater:
+ image: alpine:latest
+ restart: "no"
+ volumes:
+ - ./config/maxmind:/data
+ environment:
+ - MAXMIND_LICENSE_KEY=${MAXMIND_LICENSE_KEY:-your-license-key-here}
+ command: >
+ sh -c "
+ apk add --no-cache wget tar &&
+ cd /data &&
+ if [ ! -f GeoLite2-City.mmdb ] || [ \"$(find . -name 'GeoLite2-City.mmdb' -mtime +7)\" ]; then
+ echo 'Updating GeoLite2-City database...'
+ 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 --wildcards -xzf GeoLite2-City.tar.gz --strip-components=1 '*/GeoLite2-City.mmdb' &&
+ rm -f GeoLite2-City.tar.gz
+ fi &&
+ if [ ! -f GeoLite2-Country.mmdb ] || [ \"$(find . -name 'GeoLite2-Country.mmdb' -mtime +7)\" ]; then
+ echo 'Updating GeoLite2-Country database...'
+ wget -O GeoLite2-Country.tar.gz 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country&license_key=${MAXMIND_LICENSE_KEY}&suffix=tar.gz' &&
+ tar --wildcards -xzf GeoLite2-Country.tar.gz --strip-components=1 '*/GeoLite2-Country.mmdb' &&
+ rm -f GeoLite2-Country.tar.gz
+ fi &&
+ echo 'GeoIP databases updated successfully.'
+ "
+```
+
+***
+
+## Step 4: Launch the Stack
+
+```bash theme={null}
+docker compose up -d
+docker compose ps
+```
+
+***
+
+## Step 5: Access the Dashboard
+
+* **Web UI** → [http://localhost:3000](http://localhost:3000)
+* Default data source: `traefik-agent:5000`
+
+You should see real-time traffic metrics, GeoIP maps, error tracking, and system performance indicators.
+
+***
+
+## Key Features
+
+**Real-time analytics** for request rates, response times, and errors
+**GeoIP maps** with both City and Country-level resolution
+**System health** (CPU, memory, disk)
+**Multi-agent support** (monitor multiple Traefik instances)
+**Secure API authentication** via token
+**Responsive modern UI**
+
+***
+
+## Advanced: Multi-Agent Setup
+
+You can deploy multiple `traefik-agent` instances across environments and connect them all to a single dashboard.
+
+Example:
+
+```yaml theme={null}
+ traefik-agent-prod:
+ image: hhftechnology/traefik-log-dashboard-agent:latest
+ ports: ["5000:5000"]
+ environment:
+ - TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN=prod_token
+ - TRAEFIK_LOG_DASHBOARD_ACCESS_PATH=/logs/access.log
+ - TRAEFIK_LOG_DASHBOARD_GEOIP_ENABLED=true
+ volumes:
+ - /var/log/traefik/prod:/logs:ro
+ - ./config/maxmind:/geoip:ro
+ - ./data/positions-prod:/data
+
+ traefik-agent-staging:
+ image: hhftechnology/traefik-log-dashboard-agent:latest
+ ports: ["5001:5000"]
+ environment:
+ - TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN=staging_token
+ - TRAEFIK_LOG_DASHBOARD_ACCESS_PATH=/logs/access.log
+ volumes:
+ - /var/log/traefik/staging:/logs:ro
+ - ./config/maxmind:/geoip:ro
+
+ traefik-dashboard:
+ image: hhftechnology/traefik-log-dashboard:latest
+ ports: ["3000:3000"]
+ environment:
+ - NODE_ENV=production
+```
+
+Then, in the **Dashboard → Settings → Agents**, add each agent URL and token.
+
+***
+
+## Performance Tuning
+
+| Setting | Description | Recommended |
+|-------------------------------------------|----------------------|-------------|
+| `TRAEFIK_LOG_DASHBOARD_SYSTEM_MONITORING` | Enables system stats | `true` |
+| `TRAEFIK_LOG_DASHBOARD_LOG_FORMAT` | Log parsing format | `json` |
+
+***
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-----------------------|--------------------------|---------------------------------------------------------------------|
+| Dashboard not loading | Container not healthy | `docker compose ps` → check `health` |
+| No logs appearing | Wrong log path or format | Ensure `access.log` is JSON and volume mounted |
+| GeoIP missing | Missing databases | Run `maxmind-updater` or mount both `.mmdb` files |
+| Auth errors | Token mismatch | Verify `AGENT_API_TOKEN` matches `TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN` |
+| Slow UI | Large logs | Use JSON logs + incremental read; prune logs periodically |
+
+***
+
+## Summary
+
+* Replaces the old `log-dashboard-backend` + `log-dashboard-frontend` with the new **agent-based architecture**
+* Supports **multiple Traefik instances**
+* Adds **GeoLite2 Country + City databases**
+* Integrates **real-time analytics + system monitoring**
+* Uses **MaxMind license key** for GeoIP updates
+* More stable with less memory
+
+***
+
+**Project Repository
+** → [https://github.com/hhftechnology/traefik-log-dashboard](https://github.com/hhftechnology/traefik-log-dashboard)
+
+```
+```
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/DNS_&_Networking.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/DNS_&_Networking.md
new file mode 100644
index 00000000..d646466d
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/DNS_&_Networking.md
@@ -0,0 +1,235 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# DNS & Networking
+
+> Configure your domain, DNS records, and network settings for Pangolin deployment
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+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.
+
+
+
+ Create a wildcard subdomain record for your domain:
+
+ ```
+ Type: A
+ Name: *
+ Value: YOUR_VPS_IP_ADDRESS
+ TTL: 300 (or default)
+ ```
+
+
+ This allows any subdomain (e.g., `app.example.com`, `api.example.com`) to resolve to your VPS.
+
+
+
+
+
+ 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)
+ ```
+
+
+ This is only needed if you want to use `example.com` (not just subdomains) as a resource.
+
+
+
+
+
+ DNS changes can take 5 minutes to 48 hours to propagate globally.
+
+
+ Use Google DNS (8.8.8.8) or your provider's DNS to test changes faster.
+
+
+
+
+
+## Port Configuration
+
+### Required Ports
+
+Pangolin requires these ports to be open on your VPS:
+
+
+
+ **HTTP/SSL Verification**
+
+ * Let's Encrypt domain validation
+ * Non-SSL resources
+ * Can be disabled with wildcard certs
+
+
+
+
+ **HTTPS Traffic**
+
+ * Pangolin web dashboard
+ * SSL-secured resources
+ * Essential for operation
+
+
+
+
+ **Site Tunnels**
+
+ This is the default port for sites (Newt) to establish tunnels to the proxy (Gerbil).
+
+
+
+
+ **Client Tunnels**
+
+ This is the default port for clients relaying through Gerbil to newt. This port is only required for clients.
+
+
+
+
+
+ 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).
+
+
+### Docker Port Exposure
+
+By default, Pangolin exposes these ports on all interfaces:
+
+```yaml theme={null}
+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:
+
+
+
+ Configure security groups/firewall rules in your cloud provider's dashboard to allow:
+
+ * TCP ports 80 and 443
+ * UDP ports 51820 and 21820
+
+
+
+
+ ```bash theme={null}
+ sudo ufw allow 80/tcp
+ sudo ufw allow 443/tcp
+ sudo ufw allow 51820/udp
+ sudo ufw allow 21820/udp
+ sudo ufw enable
+ ```
+
+
+
+ ```bash theme={null}
+ 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
+ ```
+
+
+
+## Internal Network Configuration
+
+### Default Subnet Settings
+
+Pangolin uses these default network settings:
+
+```yaml theme={null}
+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
+
+
+ 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).
+
+
+
+ **Important**: If this subnet conflicts with your network, change it in your config **before** registering your first Gerbil.
+
+
+### Customizing Network Settings
+
+If you need to change the default network:
+
+```yaml theme={null}
+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
+```
+
+
+ For heavy WireGuard usage, consider increasing `site_block_size` to 29 (8 IPs) or 28 (16 IPs) per site.
+
+
+## Docker Networking
+
+### Local Services
+
+When deploying services in Docker alongside Pangolin:
+
+
+
+ **For services in the same Docker Compose:**
+
+ * Use service names as hostnames
+ * Example: `http://pangolin:8080`
+ * Docker Compose creates internal network automatically
+
+
+
+
+ **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`
+
+
+
+
+ **For services outside Docker:**
+
+ * Use the host's public IP address
+ * Ensure firewall allows the required ports
+ * Consider using VPN or secure tunnels
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Enterprise_Edition.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Enterprise_Edition.md
new file mode 100644
index 00000000..e6811424
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Enterprise_Edition.md
@@ -0,0 +1,230 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Enterprise Edition
+
+> Learn about Enterprise Edition features, licensing, and how to get started
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+When self-hosting Pangolin, you can choose to run the **Community Edition** or the **Enterprise Edition**. Both editions
+provide the same core functionality, but the Enterprise Edition unlocks additional features for qualifying users.
+
+## Edition Comparison
+
+### Community Edition
+
+* Fully compliant with AGPL-3 license
+* All core Pangolin features included
+
+### Enterprise Edition
+
+* Distributed under Fossorial Commercial License
+* Includes all Community Edition features
+* Unlocks "Paid Features" for qualifying users (see below)
+* Requires valid license key for activation
+
+## Licensing Overview
+
+The Enterprise Edition is distributed under the **Fossorial Commercial License**, which provides different terms based
+on your organization's revenue:
+
+
+
+ **Free for individuals and small businesses**
+
+ * **Revenue threshold**: Less than \$100,000 USD gross annual revenue
+ * **License cost**: Free
+ * **Features**: Full access to all "Paid Features"
+ * **Usage**: Personal and small business use allowed
+
+
+ You still need to acquire a valid license key to unlock Enterprise features, even with free licensing.
+
+
+
+
+
+ **Larger businesses require a paid license**
+
+ * **Revenue threshold**: \$100,000+ USD gross annual revenue
+ * **License cost**: Paid license required
+ * **Features**: Full access to all "Paid Features"
+ * **Usage**: Business use with commercial terms
+
+
+ Businesses exceeding the revenue threshold must purchase a commercial license to use Enterprise Edition features.
+
+
+
+
+
+To see pricing tiers for the self-hosted Enterprise Edition for
+businesses, [click here](https://pangolin.net/pricing?hosting=self-host). For more on how to purchase a key,
+see [Purchase a license key](/self-host/purchase-license-key).
+
+## Getting Your License Key
+
+
+
+ Visit [app.pangolin.net](https://app.pangolin.net) and create your account.
+
+
+
+ After logging in, go to the **Licenses** section in your account dashboard.
+
+
+
+ Complete the license application form.
+
+
+ Inaccurate representation is a violation of the license and will result in the license being revoked.
+
+
+
+
+
+ Once approved, you'll receive your license key immediately. You can then activate it in your Pangolin instance in the Server Admin panel.
+
+
+
+## License Requirements
+
+
+
+ **One key per Pangolin server instance**
+
+ Each host (server) running Pangolin requires its own license key. You cannot share a single key across multiple servers.
+
+
+ If you're running multiple Pangolin instances for high availability, each database needs its own license key.
+
+
+
+
+
+ Businesses that don't qualify for free personal licensing can reach out to [support@pangolin.net](mailto:support@pangolin.net) for a trial license key to test Enterprise features before purchasing.
+
+
+ Trial keys are only available for organizations that exceed the personal license revenue threshold.
+
+
+
+
+
+ **Contact us for guidance**
+
+ If you're uncertain whether you qualify for free licensing or need a commercial license, reach out to [sales@pangolin.net](mailto:sales@pangolin.net) with your organization details.
+
+ We'll help determine the appropriate license type and pricing for your use case.
+
+
+
+
+## Activating Enterprise Edition
+
+
+
+ Update your Docker Compose configuration to use the Enterprise Edition image:
+
+ ```yaml theme={null}
+ services:
+ pangolin:
+ image: fosrl/pangolin:ee-latest # Enterprise Edition
+ # ... rest of configuration
+ ```
+
+
+ The Enterprise Edition image is tagged with `ee` (e.g., `fosrl/pangolin:ee-latest`) and is different from the Community Edition (`fosrl/pangolin:latest`). Make sure to use the correct image.
+
+
+
+
+
+ Restart your Pangolin services to activate the license:
+
+ ```bash theme={null}
+ sudo docker compose restart pangolin
+ ```
+
+
+
+
+ Log in to the Pangolin instance via the server admin credentials. Visit the Server Admin panel and naviage to the License section (`/admin/license`). Enter and activate the license key.
+
+
+ The license key should be provided exactly as received in your email confirmation.
+
+
+
+
+
+ Check your Pangolin dashboard to confirm Enterprise Edition features are unlocked.
+
+
+
+## Support and Contact
+
+For licensing questions and quotes, email: [sales@pangolin.net](mailto:sales@pangolin.net)
+
+Include your organization details and use case for faster assistance.
+
+## Frequently Asked Questions
+
+
+
+ You can switch from Community to Enterprise Edition by:
+
+ 1. Updating your Docker image to `fosrl/ee-`
+ 2. Adding your license key to the configuration
+ 3. Restarting the services
+
+
+ Switching back to Community Edition will disable Enterprise features and may require data migration.
+
+
+
+
+
+ Enterprise Edition is fully opt-in. You can continue using the Community Edition.
+
+
+ The Community Edition will always remain free and open source with full AGPL-3 compliance.
+
+
+
+
+
+ If your license expires or becomes invalid:
+
+ * Enterprise features will be disabled
+ * You can renew your license to restore Enterprise features
+
+
+
+
+ Individuals and small businesses under the revenue threshold can use Enterprise Edition for personal projects at no cost.
+
+
+ Personal use is explicitly allowed under the free license terms.
+
+
+
+
+
+ **No exceptions - same license terms apply**
+
+ Educational institutions, non-profit organizations, and government entities are subject to the same license terms as all other organizations. There are no special exceptions or discounts for these groups.
+
+
+ If you have questions about how your organization's revenue is calculated for licensing purposes, contact [sales@pangolin.net](mailto:sales@pangolin.net).
+
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/How_to_Update.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/How_to_Update.md
new file mode 100644
index 00000000..d4e888ec
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/How_to_Update.md
@@ -0,0 +1,129 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# How to Update
+
+> Keep your Pangolin deployment up to date with the latest features and security patches
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+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
+
+
+ **Always backup your data before updating.** Copy your `config` directory to a safe location so you can roll back if needed.
+
+
+
+ **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.
+
+
+## Update Process
+
+
+
+ Stop all running containers:
+
+ ```bash theme={null}
+ sudo docker compose down
+ ```
+
+
+
+
+ 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)
+
+
+ Look for the latest stable release (not pre-release or beta versions).
+
+
+
+
+
+ Edit your `docker-compose.yml` file and update the image versions:
+
+ ```yaml title="docker-compose.yml" theme={null}
+ 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" theme={null}
+ experimental:
+ plugins:
+ badger:
+ moduleName: github.com/fosrl/badger
+ version: v1.3.0 # Update to latest version
+ ```
+
+
+ Update each service you want to upgrade. You can update them individually or all at once.
+
+
+
+
+
+ Download the updated Docker images:
+
+ ```bash theme={null}
+ sudo docker compose pull
+ ```
+
+
+
+
+ Start the updated containers:
+
+ ```bash theme={null}
+ sudo docker compose up -d
+ ```
+
+
+
+
+ Watch the logs to ensure everything starts correctly:
+
+ ```bash theme={null}
+ sudo docker compose logs -f
+ ```
+
+
+
+
+ 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
+
+
+ If everything works, your update is complete!
+
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Manual_Installation/Docker_Compose.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Manual_Installation/Docker_Compose.md
new file mode 100644
index 00000000..9ce5ff40
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Manual_Installation/Docker_Compose.md
@@ -0,0 +1,372 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Docker Compose
+
+> Deploy Pangolin manually using Docker Compose without the automated installer
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+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 (*)
+```
+
+
+ Files marked with `(*)` must be created manually. Volumes and other files are generated automatically by the services.
+
+
+
+
+ **`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
+
+
+
+
+ **`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
+
+
+
+
+ **`docker-compose.yml`**: Service definitions
+
+ * Defines Pangolin, Gerbil, and Traefik services
+ * Network configuration and volume mounts
+ * Health checks and dependencies
+
+
+
+
+
+
+ ```bash theme={null}
+ mkdir -p config/traefik config/db config/letsencrypt config/logs
+ ```
+
+
+
+ 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`
+
+
+
+
+ Edit the configuration files to replace:
+
+ * `pangolin.example.com` with your actual domain
+ * `admin@example.com` with your email address
+
+
+ Ensure your domain DNS is properly configured to point to your server's IP address.
+
+
+
+
+
+## Starting the Stack
+
+
+
+ ```bash theme={null}
+ sudo docker compose up -d
+ ```
+
+
+
+ ```bash theme={null}
+ sudo docker compose logs -f
+ ```
+
+
+
+ ```bash theme={null}
+ sudo docker compose ps
+ ```
+
+ All services should show "Up" status after a few minutes.
+
+
+
+
+ Navigate to `https://your-domain.com/auth/initial-setup` to complete the initial setup.
+
+
+ The dashboard should load with SSL certificate automatically configured.
+
+
+
+
+
+## Docker Compose Configuration
+
+Create `docker-compose.yml` in your project root:
+
+```yaml title="docker-compose.yml" theme={null}
+name: pangolin
+services:
+ pangolin:
+ image: docker.io/fosrl/pangolin:latest # https://github.com/fosrl/pangolin/releases
+ container_name: pangolin
+ restart: unless-stopped
+ volumes:
+ - ./config:/app/config
+ healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost:3001/api/v1/"]
+ interval: "10s"
+ timeout: "10s"
+ retries: 15
+
+ gerbil:
+ image: docker.io/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:3004
+ - --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
+ - 80:80
+
+ traefik:
+ image: docker.io/traefik:v3.6
+ 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
+ - ./config/traefik/logs:/var/log/traefik # Volume to store Traefik logs
+
+networks:
+ default:
+ driver: bridge
+ name: pangolin
+ #enable_ipv6: true # activate if your system supports IPv6
+```
+
+## Traefik Static Configuration
+
+Create `config/traefik/traefik_config.yml`:
+
+```yaml title="config/traefik/traefik_config.yml" theme={null}
+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.3.1"
+
+log:
+ level: "INFO"
+ format: "common"
+ maxSize: 100
+ maxBackups: 3
+ maxAge: 3
+ compress: true
+
+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"
+ encodedCharacters:
+ allowEncodedSlash: true
+ allowEncodedQuestionMark: true
+
+serversTransport:
+ insecureSkipVerify: true
+
+ping:
+ entryPoint: "web"
+```
+
+## Traefik Dynamic Configuration
+
+Create `config/traefik/dynamic_config.yml`:
+
+```yaml title="config/traefik/dynamic_config.yml" theme={null}
+http:
+ middlewares:
+ badger:
+ plugin:
+ badger:
+ disableForwardAuth: true
+ 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
+ - badger
+
+ # 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
+ middlewares:
+ - badger
+ 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
+ middlewares:
+ - badger
+ tls:
+ certResolver: letsencrypt
+
+ # WebSocket router
+ ws-router:
+ rule: "Host(`pangolin.example.com`)" # REPLACE WITH YOUR DOMAIN
+ service: api-service
+ entryPoints:
+ - websecure
+ middlewares:
+ - badger
+ 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
+
+tcp:
+ serversTransports:
+ pp-transport-v1:
+ proxyProtocol:
+ version: 1
+ pp-transport-v2:
+ proxyProtocol:
+ version: 2
+```
+
+## Pangolin Configuration
+
+Create `config/config.yml` with your Pangolin settings. See the [configuration guide](/self-host/advanced/config-file)
+for detailed options and examples.
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Manual_Installation/Unraid_Deployment.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Manual_Installation/Unraid_Deployment.md
new file mode 100644
index 00000000..768c7d67
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Manual_Installation/Unraid_Deployment.md
@@ -0,0 +1,421 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Unraid Deployment
+
+> Deploy Pangolin on Unraid for local reverse proxy and tunneling
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+## 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:
+
+
+ You can use any name you want for the network. We will use `mynetwork` in this guide.
+
+
+```bash theme={null}
+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.
+
+
+
+
+
+**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
+
+
+ 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.
+
+
+#### 5. Log in to the dashboard
+
+After successful installation:
+
+1. Complete the initial admin user setup via the dashboard at `https:///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 theme={null}
+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.3.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" theme={null}
+http:
+ middlewares:
+ badger:
+ plugin:
+ badger:
+ disableForwardAuth: true
+ 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
+ - badger
+
+ # 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
+ middlewares:
+ - badger
+ 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
+ middlewares:
+ - badger
+ tls:
+ certResolver: letsencrypt
+
+ # WebSocket router
+ ws-router:
+ rule: "Host(`pangolin.example.com`)" # REPLACE THIS WITH YOUR DOMAIN
+ service: api-service
+ entryPoints:
+ - websecure
+ middlewares:
+ - badger
+ 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.
+
+
+
+
+
+#### 3. Configure Traefik
+
+
+
+
+
+
+ Please refer to the official Traefik docs for more information on the Traefik configuration beyond this guide.
+
+
+**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 theme={null}
+--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: `/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 `/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)
+
+
+ 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.
+
+
+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.
+
+
+
+
+
+**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:**
+
+
+ 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 theme={null}
+ gerbil:
+ start_port: 51822
+ ```
+
+See [this GitHub issue comment](https://github.com/fosrl/pangolin/issues/227#issuecomment-2781608815) for more details.
+
+
+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 theme={null}
+--net=container:Gerbil
+```
+
+Then, set "Network Type" to "None".
+
+
+
+
+
+#### 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:
+
+
+ You probably won't have the peer connection messages but in general, you should see the WireGuard interface being started.
+
+
+
+
+
+
+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.
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Quick_Install_Guide.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Quick_Install_Guide.md
new file mode 100644
index 00000000..33e63992
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Quick_Install_Guide.md
@@ -0,0 +1,164 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Quick Install Guide
+
+> Deploy your own fully self-hosted instance of Pangolin Community Edition
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+
+
+## 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)
+
+
+ **Recommended**: Ubuntu 20.04+ or Debian 11+ for best compatibility and performance.
+
+
+## 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
+
+
+
+ Connect to your server via SSH and download the installer:
+
+ ```bash theme={null}
+ curl -fsSL https://static.pangolin.net/get-installer.sh | bash
+ ```
+
+ The installer supports both AMD64 (x86\_64) and ARM64 architectures.
+
+
+
+
+ Execute the installer with root privileges:
+
+ ```bash theme={null}
+ sudo ./installer
+ ```
+
+ The installer places all files in the current directory. Move the installer to your desired installation directory before running it.
+
+
+
+
+ The installer will prompt you for essential configuration:
+
+ * **Edition**: Choose Community Edition or [Enterprise Edition](/self-host/enterprise-edition). Review the edition differences before continuing.
+ * **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.
+
+
+
+
+
+ Email functionality is optional and can be added later.
+
+
+ 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)
+
+
+
+
+ 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.
+
+
+
+
+ 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
+
+
+ CrowdSec adds complexity and requires manual configuration for optimal security. Only enable if you're comfortable managing it.
+
+
+
+ CrowdSec can be installed later if needed. The basic installation provides sufficient security for most use cases.
+
+
+
+
+
+## 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
+```
+
+
+
+ Navigate to the URL shown in the installer output:
+
+ ```
+ https:///auth/initial-setup
+ ```
+
+
+ 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.
+
+
+
+
+
+ Complete the initial admin user setup:
+
+ * Enter your admin email address
+ * Set a strong password
+ * Verify your email (if email is configured)
+
+
+ Use a strong, unique password for your admin account. This account has full system access.
+
+
+
+
+
+ After logging in:
+
+ 1. Enter organization name and description
+ 2. Click "Create Organization"
+
+
+ You're now ready to start adding applications and configuring your reverse proxy!
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Supporter_Program.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Supporter_Program.md
new file mode 100644
index 00000000..31ef7728
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Supporter_Program.md
@@ -0,0 +1,155 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Supporter Program
+
+> Support Pangolin development and remove UI elements with a supporter key
+
+
+
+ Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
+
+
+
+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.
+
+
+ **Business & Enterprise Users:** For larger organizations or teams requiring advanced features, consider our self-serve enterprise license and [Enterprise Edition](/self-host/enterprise-edition). [Learn more](https://pangolin.net/pricing?hosting=self-host)
+
+
+## Supporter Tiers
+
+
+
+ **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
+
+
+ Once you add your 6th user, the support button will return. Remove a user or upgrade to Full Supporter to hide it again.
+
+
+
+
+
+ **Perfect for larger teams**
+
+ * **User limit**: Unlimited users
+ * **Support button**: Permanently removed
+ * **Usage**: Unlimited servers and installations
+ * **Best value**: For growing teams
+
+
+ The support button and other marks will never return, regardless of user count.
+
+
+
+
+
+
+
+
+
+## How to Get Your Supporter Key
+
+
+
+ Go to our [GitHub Sponsors page](https://github.com/sponsors/fosrl) and purchase either:
+
+ * **Limited Supporter**: \$25 one-time
+ * **Full Supporter**: \$95 one-time
+
+
+
+
+ After purchase, visit [supporters.fossorial.io](https://supporters.fossorial.io) and:
+
+ 1. Log in with your GitHub account
+ 2. Copy your supporter key
+
+
+
+
+ In your Pangolin dashboard:
+
+ 1. Click the supporter button
+ 2. Enter your supporter key
+ 3. Click "Redeem"
+
+
+
+
+
+
+
+
+## Frequently Asked Questions
+
+
+
+ Github sponsors does not currently support other payment methods. We hope to add more options in the future.
+
+
+
+ **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.
+
+
+
+
+ **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
+
+
+ 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!
+
+
+
+
+
+ **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.
+
+
+
+
+ **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!
+
+
+
+
+ **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.
+
+
+
+
+ **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
+
+
+ Full Supporter keys have no user limits.
+
+
+
+
diff --git a/docs/99_Journal/2026-03-11_Session_Log_Pangolin_Update.md b/docs/99_Journal/2026-03-11_Session_Log_Pangolin_Update.md
new file mode 100644
index 00000000..56e0e707
--- /dev/null
+++ b/docs/99_Journal/2026-03-11_Session_Log_Pangolin_Update.md
@@ -0,0 +1,45 @@
+# Session Log: Pangolin Update & Meldestelle Configuration
+
+**Datum:** 11. März 2026
+**Teilnehmer:** User (Owner), AI Agent (Lead Architect/DevOps)
+**Status:** In Progress
+
+## 1. Pangolin Update (Abgeschlossen)
+
+### Kontext
+
+Das Update von Pangolin auf dem VPS `vzora` stand an, um die neueste Version (1.16.2) zu nutzen. Dies war notwendig, um
+von den neuesten Features und Sicherheitsupdates zu profitieren.
+
+### Durchgeführte Maßnahmen
+
+1. **Dokumentation aktualisiert:**
+ - Die Datei `docs/01_Architecture/Pangolin/Documentation Index Fetch.md` wurde angepasst.
+ - Die Version im Update-Guide wurde exemplarisch auf `1.16.2` gesetzt.
+
+2. **SSH-Intervention auf `vzora`:**
+ - Stop des Stacks: `sudo docker compose down`
+ - Bearbeitung der `docker-compose.yml`:
+ - Update `pangolin` Image auf `fosrl/pangolin:1.16.2`.
+ - (Gerbil war bereits auf 1.3.0, Traefik auf v3.6 laut Logs).
+ - Pull & Neustart: `sudo docker compose pull && sudo docker compose up -d`
+ - Verifikation via Logs: `sudo docker compose logs -f`
+
+### Ergebnisse
+
+* **Erfolgreiche Migration:** Pangolin Datenbank-Migrationen (1.15.4 -> 1.16.0) wurden erfolgreich durchgeführt.
+* **System Health:** Alle Dienste (Pangolin, Gerbil, Traefik) starteten fehlerfrei und sind "Healthy".
+* **Warnung:** SMTP ist nicht konfiguriert (erwartetes Verhalten, da nicht genutzt).
+
+## 2. Meldestelle Endpoint Analyse (In Vorbereitung)
+
+### Ziel
+
+Vorbereitung der Konfiguration von Pangolin (Reverse Proxy/Gateway) für das Projekt "Meldestelle". Dazu müssen alle
+relevanten internen und externen Endpunkte identifiziert werden.
+
+### Nächste Schritte
+
+* Analyse der `docker-compose` Dateien der Meldestelle.
+* Identifikation der Ports und Services (Backend, Frontend, Keycloak, etc.).
+* Erstellung eines Plans für die Pangolin-Konfiguration (Routing, Domains).
diff --git a/docs/ScreenShots/pangolin_github-releasee-1-16-2_2026-03-11_10-35.png b/docs/ScreenShots/pangolin_github-releasee-1-16-2_2026-03-11_10-35.png
new file mode 100644
index 00000000..c93c952d
Binary files /dev/null and b/docs/ScreenShots/pangolin_github-releasee-1-16-2_2026-03-11_10-35.png differ
diff --git a/docs/ScreenShots/pangolin_oeffentl-ressourcen_2026-03-11_10-33.png b/docs/ScreenShots/pangolin_oeffentl-ressourcen_2026-03-11_10-33.png
new file mode 100644
index 00000000..76a025b4
Binary files /dev/null and b/docs/ScreenShots/pangolin_oeffentl-ressourcen_2026-03-11_10-33.png differ
+
+
+
+
+### Setting Up ASN Blocking Rules
+
+1. Navigate to your target resource and select the **Rules** tab
+2. Create a new rule and select **ASN** as the match type
+3. Choose an ASN from the dropdown of common providers, or manually enter a specific ASN number
+4. Choose your rule action:
+ * **Allow**: Bypass authentication for users from specific ASNs
+ * **Deny**: Block all access from specific ASNs
+ * **Pass to Auth**: Let users from specific ASNs proceed to authentication
+
+### Common ASNs
+
+The dropdown includes many commonly-used ASNs such as:
+
+* **Cloud Providers**: Amazon (AS16509), Google Cloud (AS15169), Microsoft Azure (AS8075), DigitalOcean (AS14061)
+* **Major ISPs**: Comcast (AS7922), AT\&T (AS7018), Verizon (AS701), Deutsche Telekom (AS3320)
+* **VPN/Proxy Services**: NordVPN (various), ExpressVPN (various), Mullvad (AS42831)
+* **CDN Providers**: Cloudflare (AS13335), Fastly (AS54113), Akamai (various)
+
+If the ASN you need isn't in the dropdown, you can manually enter the ASN number (e.g., AS12345 or just 12345).
+
+### Common ASN Blocking Patterns
+
+#### Block VPN and Proxy Services
+
+Create deny rules for known VPN and proxy ASNs to prevent anonymous access:
+
+1. Create **Deny** rules for each VPN/proxy provider ASN
+2. Select ASNs from the dropdown or enter them manually
+3. Set appropriate priorities
+
+#### Block Datacenter Traffic
+
+Block access from datacenter and hosting provider ASNs while allowing residential users:
+
+1. Create **Deny** rules for major cloud and hosting provider ASNs
+2. Include providers like AWS, GCP, Azure, DigitalOcean, etc.
+3. This helps ensure only real users from residential ISPs can access your resources
+
+#### Allow Only Specific Networks
+
+Create a default deny rule and explicitly allow only approved ASNs:
+
+1. Create a **Deny** rule matching all traffic with priority 100
+2. Create **Allow** rules for specific approved ASNs with higher priority (e.g., 10, 20, 30)
+
+#### Regional ISP Control
+
+Allow access only from specific country ISPs while blocking others:
+
+1. **Combine with Country Rules**: Use ASN rules to specify which ISPs are allowed
+2. Create **Allow** rules for major residential ISPs in your target countries
+3. Block datacenter and VPN ASNs that might circumvent country restrictions
+
+### Best Practices
+
+
+
+
+## Configuration
+
+1. Go to **Settings** in your organization sidebar
+2. Use the domain picker to select your custom domain
+3. Save your changes
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Device_Approvals.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Device_Approvals.md
new file mode 100644
index 00000000..d1110882
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Access_Control/Device_Approvals.md
@@ -0,0 +1,53 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Device Approvals
+
+> Only allow trusted devices to connect to an organization
+
+
+
+
+All approvals can also be managed from a central page as they stream in to allow admins to approve or deny devices
+quickly.
+
+
+ 
+
+
+## Enabling Device Approvals
+
+Device approvals are enabled on a per-role basis. To enable device approvals for a role, follow these steps:
+
+1. Click on the **Roles** tab.
+2. Select the role you want to enable device approvals for.
+3. Toggle the **Require Device Approval** option to enable it.
+4. Save your changes.
+
+Once enabled, any new user connecting with that role will require approval from an administrator before it can access
+organization resources.
+
+
+
+
+### Setting Up Geo Blocking Rules
+
+1. Navigate to your target resource and select the **Rules** tab
+2. Create a new rule and select **Country** as the match type
+3. Choose your rule action:
+ * **Allow**: Bypass authentication for users from specific countries
+ * **Deny**: Block all access from specific countries
+ * **Pass to Auth**: Let users from specific countries proceed to authentication
+
+### Common Geo Blocking Patterns
+
+#### Allow Only Specific Countries
+
+Create a "Deny" rule that blocks all countries except those you want to allow:
+
+1. Create a **Deny** rule
+2. Select **Country** match type
+3. Choose "ALL" to match all countries
+4. Add priority: 100 (lower priority)
+
+Then create specific allow rules for your approved countries:
+
+1. Create **Allow** rules for each approved country
+2. Set higher priority (e.g., 10, 20, 30) so they process first
+
+#### Block Specific High-Risk Countries
+
+Create targeted deny rules for specific countries while allowing all others:
+
+1. Create **Deny** rules for each country you want to block
+2. Select the specific countries from the dropdown
+3. Set appropriate priorities
+
+#### Regional Access Control
+
+Combine geo blocking with other rule types for sophisticated access control:
+
+1. **Path + Country**: Block admin paths (`/admin/*`) from all countries except your headquarters
+2. **IP + Country**: Allow specific IPs from restricted countries (for VPN users or partners)
+3. **CIDR + Country**: Combine network-based and geography-based restrictions
+
+### Best Practices
+
+
+
+
+### Docker Labels Considerations
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Client_Credentials.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Client_Credentials.md
new file mode 100644
index 00000000..6daed64f
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Client_Credentials.md
@@ -0,0 +1,74 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Client Credentials
+
+> Understanding how client credentials work and how they can be rotated & regenerated
+
+
+
+
+## Pangolin CLI
+
+Refer to the [documentation in the official repository](https://github.com/fosrl/cli/blob/main/docs/pangolin.md) for the
+available commands, default values, and more.
+
+## Olm (Advanced)
+
+
+
+
+## Identity Provider Types
+
+### Organization Identity Providers
+
+Organization identity providers are configured per organization and only apply to that specific organization. Each org
+can have its own identity providers, allowing for authentication methods based on the organization's needs.
+
+
+
+
+## What if Auto Provisioning is Disabled?
+
+If auto provision is disabled, organization admins will need to manually create the user accounts and select the role
+for each user. When creating a user, you can select the identity provider that the user will be associated with. A user
+will not be able to log in using the identity provider if a user is not pre-provisioned in the system.
+
+
+ 
+
+
+## Configuration Options
+
+## Selecting Roles
+
+You can choose between "Select a Role" and "Expression". Selecting a role will apply that role to all auto provisioned
+users. The expression will be evaluated against the token response from the IdP on each login (see examples below). You
+can always manually change the role of the user after they're provisioned.
+
+### Expressions
+
+Use JMESPath to map attributes from the identity provider to roles in Pangolin. See [JMESPath](https://jmespath.org/)
+for more information on how to use JMESPath.
+
+The expression will be matched against each organization. Meaning:
+
+* The result of the expression must return the exact string of the role name as it is defined in the organization.
+* If no matching role is found, the user will not be added to the organization.
+
+### Example: Role Selection
+
+**Expression:**
+
+
+
+
+In the OAuth2/OIDC Configuration, you'll need the following fields:
+
+
+
+
+In the "Google Configuration", you'll need the following fields:
+
+
+
+
+In the OAuth2/OIDC Configuration, you'll need the following fields:
+
+
+
+
+ 
+
+
+For self-hosted Pangolin, access the documentation at `https://api.your-domain.com/v1/docs`.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Logs_&_Analytics/Access_Logs.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Logs_&_Analytics/Access_Logs.md
new file mode 100644
index 00000000..df7002e5
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Logs_&_Analytics/Access_Logs.md
@@ -0,0 +1,66 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Access Logs
+
+> Access logs are a record of each access attempt to a Pangolin resource
+
+
+
+
+
+
+
+
+
+
+## Request Log Fields
+
+Each request log entry contains the following fields:
+
+| Field | Type | Description |
+|----------------------|---------|--------------------------------------------------------------------------------|
+| `timestamp` | number | Unix timestamp (in seconds) when the request was made |
+| `action` | boolean | Whether the request was allowed (`true`) or denied (`false`) |
+| `reason` | number | Numeric code indicating the reason for the decision |
+| `actorType` | string | The type of actor making the request ("user", "apiKey", or null for anonymous) |
+| `actor` | string | The display name of the authenticated actor (username or API key name) |
+| `actorId` | string | The unique identifier for the authenticated actor |
+| `resourceId` | number | The ID of the resource that received the request |
+| `ip` | string | The IP address of the client making the request |
+| `location` | string | The geographic location (country code) based on IP address |
+| `userAgent` | string | The user agent string of the client browser or application |
+| `metadata` | string | Additional contextual information in JSON format |
+| `headers` | string | HTTP request headers in JSON format |
+| `query` | string | URL query parameters in JSON format |
+| `originalRequestURL` | string | The full original URL of the request |
+| `scheme` | string | The protocol scheme (http or https) |
+| `host` | string | The hostname from the request |
+| `path` | string | The URL path of the request |
+| `method` | string | The HTTP method (GET, POST, PUT, DELETE, etc.) |
+| `tls` | boolean | Whether the connection used TLS/SSL |
+
+## Log Retention
+
+Request log retention is controlled by the organization setting. By default, request logs are retained for 7 days.
+
+
+
+
+## Some Benefits
+
+### Automatic Updates and Less Maintenance
+
+The cloud dashboard evolves quickly, so you get new features and bug fixes without having to manually pull new
+containers every time. Because the remote node is just handling the networking you do not need to do database
+migrations, or backups.
+
+### Cloud Failover
+
+If your nodes goes down, your tunnels can temporarily fail over to our cloud points of presence or another node until
+you bring it back online. This ensures continuous availability.
+
+### High Availability (PoPs)
+
+You can attach multiple nodes to your account for redundancy and better performance. For example, deploy nodes across
+different regions or providers for decreased latency.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Aliases.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Aliases.md
new file mode 100644
index 00000000..b62ab4da
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Aliases.md
@@ -0,0 +1,69 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Aliases
+
+> Set a friendly alias hostname that resolves to a host
+
+
+
+
+### Port Restrictions
+
+By default, when access to a Resource is granted, all ports on that Resource are accessible. However, you can restrict
+access to specific ports on a Resource by defining port restrictions. When port restrictions are defined, only the
+specified ports will be accessible to users, roles, or machines that have access to the Resource. To specify specific
+ports, enter either a single port (e.g., `80`), a comma-separated list of ports (e.g., `80,443,8080`), or a port range
+using a hyphen (e.g., `8000-8100`).
+
+### ICMP Access
+
+By default, ICMP (ping) access to Resources is enabled. To disable ICMP access, you can uncheck the "ICMP" option when
+configuring access to a Resource. This will prevent users, roles, or machines with access to the Resource to send ICMP
+echo requests (ping) to the Resource's destination. Currently you can not ping an alias.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Destinations.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Destinations.md
new file mode 100644
index 00000000..a26ed37c
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Private_Resources/Destinations.md
@@ -0,0 +1,63 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Destinations
+
+> Understand connection options to the remote network
+
+
+
+
+## Configuration
+
+Title: The main title text displayed on the maintenance page.
+
+Message: A descriptive message informing users about the maintenance status.
+
+Estimated completion time: Optionally provide an estimated time for when the resource will be back online.
+
+## Enabling Maintenance Page
+
+To enable the maintenance page for a resource, navigate to the general resource settings in the Pangolin dashboard.
+Under the "Maintenance Page" section, you can customize the title, message, and estimated completion time. This can also
+be set using Blueprints.
+
+## When is the Maintenance Page Shown?
+
+There are two modes that control when the page is shown:
+
+#### Forced
+
+In forced mode, the maintenance page is displayed to all users regardless of the health status of the resource targets.
+This is useful for planned maintenance windows.
+
+#### Automatic
+
+In automatic mode, the maintenance page is shown only when all targets associated with the resource are unhealthy or all
+of the sites are offline. This is useful for unplanned outages and can be used to inform the user that the resource is
+temporarily unavailable by customizing the above settings.
+
+## Remote Nodes
+
+Maintenance pages do not work on remote nodes at this time.
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/TCP_&_UDP.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/TCP_&_UDP.md
new file mode 100644
index 00000000..bdd17bb5
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Resources/Public_Resources/TCP_&_UDP.md
@@ -0,0 +1,129 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# TCP & UDP
+
+> Configure raw TCP and UDP traffic through Pangolin tunnels
+
+
+
+
+### Load Balancing with Path-Based Routing
+
+When multiple targets have the same path and match configuration, Pangolin will load balance between them using
+round-robin distribution.
+
+**Example Scenario:**
+
+* Target 1: Path `/api`, Match `prefix`, Address `10.0.1.10:8080`
+* Target 2: Path `/api`, Match `prefix`, Address `10.0.1.11:8080`
+* Target 3: Path `/web`, Match `prefix`, Address `10.0.1.12:80`
+
+In this configuration:
+
+* Requests to `/api/users` will be load balanced between Target 1 and Target 2
+* Requests to `/web/dashboard` will only go to Target 3
+
+## Path Rewriting
+
+Path rewriting allows you to modify the request path before it reaches your backend service. This enables you to expose
+different URL structures to your users while maintaining your existing backend API paths.
+
+
+
+
+### Configuration Requirements
+
+
+
+
+### Portainer and Other UIs
+
+Container management UIs like Portainer typically allow passing commands and environment variables to containers similar
+to Docker Compose. Look for a commands or arguments configuration section and follow the relevant guides.
+
+### Windows Service
+
+On Windows, newt can to be installed and run as a Windows service to remain persistent.
+
+#### Service Management Commands
+
+```
+# Install the service
+newt.exe install
+
+# Start the service
+newt.exe start
+
+# Stop the service
+newt.exe stop
+
+# Check service status
+newt.exe status
+
+# Remove the service
+newt.exe remove
+
+# Show help
+newt.exe service-help
+```
+
+Note running the service requires credentials in `%PROGRAMDATA%\newt\newt-client\config.json`.
+
+#### Service Configuration
+
+When running as a service, newt will read configuration from environment variables or you can modify the service to
+include command-line arguments:
+
+1. Install the service: `newt.exe install`
+2. Set the credentials in `%PROGRAMDATA%\newt\newt-client\config.json`. Hint: if you run newt once with --id and
+ --secret this file will be populated!
+3. Start the service: `newt.exe start`
+
+#### Service Logs
+
+When running as a service, logs are written to:
+
+* Windows Event Log (Application log, source: "newtWireguardService")
+* Log files in: `%PROGRAMDATA%\newt\logs\newt.log`
+
+You can view the Windows Event Log using Event Viewer or PowerShell:
+
+```powershell theme={null}
+Get-EventLog -LogName Application -Source "newtWireguardService" -Newest 10
+```
+
diff --git a/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Kubernetes.md b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Kubernetes.md
new file mode 100644
index 00000000..ef0285a7
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Kubernetes.md
@@ -0,0 +1,113 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Kubernetes
+
+> How to deploy a Newt Site on Kubernetes
+
+
+
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Clustering_for_High_Availability.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Clustering_for_High_Availability.md
new file mode 100644
index 00000000..3f0224aa
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Advanced_Configuration/Clustering_for_High_Availability.md
@@ -0,0 +1,75 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Clustering for High Availability
+
+
+
+
+Give your new key a name. E.g. `Pangolin`.
+
+
+ 
+
+
+After your key got created the webpage will show you your Account ID as well as the API key. Save the key now because it
+can only be seen once. Don't panic if something goes wrong, you can easily create new keys.
+
+
+ 
+
+
+After you clicked on `Return to list` you should see an overview of your keys bundled with some metadata.
+
+## 4. Modification of Pangolin's `docker-compose.yml`
+
+Now login to your Pangolin host and navigate to `/pangolin` in your user directory:
+
+```bash theme={null}
+cd pangolin
+```
+
+Shut down Pangolin with:
+
+```bash theme={null}
+docker compose down
+```
+
+Open `docker-compose.yml` with your favorite text editor.
+E.g. nano:
+
+```bash theme={null}
+nano docker-compose.yml
+```
+
+Append this Docker compose service at the end of your stack and add your Account ID as well as your API key you created
+in the last step:
+
+```yaml theme={null}
+services:
+ (...)
+ geoipupdate:
+ container_name: geoipupdate
+ image: ghcr.io/maxmind/geoipupdate
+ restart: unless-stopped
+ environment:
+ - 'GEOIPUPDATE_ACCOUNT_ID=' # Account ID
+ - 'GEOIPUPDATE_LICENSE_KEY=' # API key
+ - 'GEOIPUPDATE_EDITION_IDS=GeoLite2-Country GeoLite2-ASN' # Which dbs should be downloaded
+ - 'GEOIPUPDATE_FREQUENCY=72' # Update intervall in hours
+ volumes:
+ - './config/GeoLite2:/usr/share/GeoIP'
+```
+
+#### Note
+
+If you use the standard Pangolin deployment you shouldn't need to modify the path.
+This is the bare minimum to run the container. There are other optional environment variables available. Have a look at
+their [docs](https://dev.maxmind.com/geoip/updating-databases/?lang=en)!
+
+Save and close the file, but don't restart the stack yet!
+
+## 5. Modification of Pangolin's config.yml
+
+Navigate to `/config` within the same folder and open it with a text editor.
+
+```bash theme={null}
+cd config
+```
+
+Add these lines to the `server` object
+
+```yaml theme={null}
+server:
+ maxmind_db_path: "./config/GeoLite2/GeoLite2-Country.mmdb"
+ maxmind_asn_path: "./config/GeoLite2/GeoLite2-ASN.mmdb"
+```
+
+These entries tell the Pangolin application where to find the databases.
+
+Save and close the file then navigate to the `pangolin` folder one level higher.
+
+Restart your Pangolin stack with:
+
+```bash theme={null}
+docker compose up -d
+```
+
+Et voilà, you are now able to define country rules and ASN rules for your ressources! 🏁
+
+btw: you can use these exact databases for your Traefik dashboard
+too -> [Community Guide](/self-host/community-guides/traefiklogsdashboard)
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Home_Assistant_Add-on.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Home_Assistant_Add-on.md
new file mode 100644
index 00000000..655d22ff
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Home_Assistant_Add-on.md
@@ -0,0 +1,157 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Home Assistant Add-on
+
+
+
+
+Template Import ID = 17346
+
+[https://grafana.com/grafana/dashboards/17346-traefik-official-standalone-dashboard/](https://grafana.com/grafana/dashboards/17346-traefik-official-standalone-dashboard/)
+
+#### Crowdsec
+
+[https://github.com/crowdsecurity/grafana-dashboards/tree/master](https://github.com/crowdsecurity/grafana-dashboards/tree/master)
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Middleware_Manager.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Middleware_Manager.md
new file mode 100644
index 00000000..bdd5d781
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Community_Guides/Middleware_Manager.md
@@ -0,0 +1,183 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Middleware Manager
+
+
+
+
+**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
+
+
+
+
+#### 3. Configure Traefik
+
+
+ 
+
+
+
+
+
+**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:**
+
+
+
+
+#### 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:
+
+
+
+
+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.
+
diff --git a/docs/01_Architecture/Pangolin/Self-host_Pangolin/Quick_Install_Guide.md b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Quick_Install_Guide.md
new file mode 100644
index 00000000..33e63992
--- /dev/null
+++ b/docs/01_Architecture/Pangolin/Self-host_Pangolin/Quick_Install_Guide.md
@@ -0,0 +1,164 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Quick Install Guide
+
+> Deploy your own fully self-hosted instance of Pangolin Community Edition
+
+
+
+
+## How to Get Your Supporter Key
+
+
+
+
+## Frequently Asked Questions
+
+