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

Renaming to remote-nodes

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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