diff --git a/packages/docusaurus/docs/01-overview.md b/packages/docusaurus/docs/01-overview.md index 2bff5d8..f65c75b 100644 --- a/packages/docusaurus/docs/01-overview.md +++ b/packages/docusaurus/docs/01-overview.md @@ -4,6 +4,10 @@ The Fossorial system - with Pangolin at its core - is a self-hosted tunneled rev Pangolin uses Traefik under the hood to do the actual HTTP proxying. A plugin, Badger, provides a way to authenticate every request with Pangolin. A second service, Gerbil, provides a WireGuard management server that Pangolin can use to create peers for connectivity. And finally, there is Newt, a CLI tool and Docker container that connects back to Newt and Gerbil with WireGuard fully in user space and proxies your local resources. This means that you do not need to run a privileged process or container in order to expose your services! +## Videos + +- ["Pangolin: Your Own Self-Hosted Cloudflare Tunnel Alternative" by DB Tech](https://youtu.be/a-a-Xk1hXBQ?si=wbppkYJ3Skt3efXp) + ## Components Overview Fossorial has a couple major components: diff --git a/packages/docusaurus/docs/02-Getting Started/05-choosing-a-vps.md b/packages/docusaurus/docs/02-Getting Started/01-choosing-a-vps.md similarity index 100% rename from packages/docusaurus/docs/02-Getting Started/05-choosing-a-vps.md rename to packages/docusaurus/docs/02-Getting Started/01-choosing-a-vps.md diff --git a/packages/docusaurus/docs/02-Getting Started/04-dns-networking.md b/packages/docusaurus/docs/02-Getting Started/02-dns-networking.md similarity index 100% rename from packages/docusaurus/docs/02-Getting Started/04-dns-networking.md rename to packages/docusaurus/docs/02-Getting Started/02-dns-networking.md diff --git a/packages/docusaurus/docs/02-Getting Started/01-quick-install.md b/packages/docusaurus/docs/02-Getting Started/03-quick-install.md similarity index 100% rename from packages/docusaurus/docs/02-Getting Started/01-quick-install.md rename to packages/docusaurus/docs/02-Getting Started/03-quick-install.md diff --git a/packages/docusaurus/docs/02-Getting Started/02-manual-install.md b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/01-docker-compose.md similarity index 99% rename from packages/docusaurus/docs/02-Getting Started/02-manual-install.md rename to packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/01-docker-compose.md index a8f6492..f639a34 100644 --- a/packages/docusaurus/docs/02-Getting Started/02-manual-install.md +++ b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/01-docker-compose.md @@ -1,4 +1,4 @@ -# Manual Install +# Docker Compose :::warning diff --git a/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/02-unraid.md b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/02-unraid.md new file mode 100644 index 0000000..08d9d59 --- /dev/null +++ b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/02-unraid.md @@ -0,0 +1,215 @@ +# Unraid + +:::warning + +Installing Pangolin, Gerbil, and Traefik on Unraid assumes you are able to port forward on the network running these servers. If you're behind CGNAT, install Pangolin a VPS and install Newt on your Unraid server to bypass the port forwarding restriction. + +**If you just want to install Newt on Unraid, and have no interest in running Pangolin and its components, there is a Newt container available in the Community Apps store.** + +::: + +:::note + +You can use an existing Traefik installation should you have one, but it will require more manual/custom configuration. This guide will focus on setting up Traefik from scratch to work with our system, but you're free to modify the Traefik configuration as much as you'd like. + +If you're installing from scratch, we provide a custom Traefik template with some defaults already set. Our template still uses the official Traefik images. However, you're able to use any Traefik template you would like, such as the popular one by IBRACORP. + +::: + +The first part of this tutorial will explain 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](https://docs.fossorial.io/Getting%20Started/dns-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 +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. Install Pangolin via the CA Store + +#### 2. Configure Pangolin + +Set the network to the one you created earlier. + +
+  +
+ +Some important considerations: + +Server Admin Email: + +The server admin email is mainly used to set up the first "Server Admin" account which you will use to log in for the first time. If you allow Pangolin to generate the Traefik config for you, this will also be used as the Let's Encrypt admin email for certs. If you wish to use a different email for Let's Encrypt, you would need to manually edit the Traefik config file after it's been created. For the vast majority of people, it is perfectly fine to use the same email for both. + +Generate Traefik Config: + +This is primarily here for your convenience. Setting this to `true` will have Pangolin generate the Traefik files for you and insert the needed info based on the other Pangolin config settings. Traefik files will be placed in `
+
+
+  +
+ +Please refer to the official Traefik docs for more information on the Traefik configuration beyond this guide. + +The only important considerations here: + +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: `+  +
+ +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: + +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 which will close the ports on the Traeffik 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 `--net=container:Gerbil` to the "Extra Parameters" section. 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. 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 successfull. Remember to also monitor the logs on the client and server. diff --git a/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/gerbIl_logs.png b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/gerbIl_logs.png new file mode 100644 index 0000000..59e7626 Binary files /dev/null and b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/gerbIl_logs.png differ diff --git a/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/gerbil_config.png b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/gerbil_config.png new file mode 100644 index 0000000..c4221a2 Binary files /dev/null and b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/gerbil_config.png differ diff --git a/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/pangolin_config.png b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/pangolin_config.png new file mode 100644 index 0000000..9a3f836 Binary files /dev/null and b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/pangolin_config.png differ diff --git a/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/traefik_config.png b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/traefik_config.png new file mode 100644 index 0000000..62988c7 Binary files /dev/null and b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/traefik_config.png differ diff --git a/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/traefik_networking.png b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/traefik_networking.png new file mode 100644 index 0000000..232a095 Binary files /dev/null and b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/traefik_networking.png differ diff --git a/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/traefik_repo.png b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/traefik_repo.png new file mode 100644 index 0000000..cb8cdf9 Binary files /dev/null and b/packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/img/traefik_repo.png differ diff --git a/packages/docusaurus/docs/02-Getting Started/03-quick-setup.md b/packages/docusaurus/docs/02-Getting Started/05-quick-setup.md similarity index 100% rename from packages/docusaurus/docs/02-Getting Started/03-quick-setup.md rename to packages/docusaurus/docs/02-Getting Started/05-quick-setup.md diff --git a/packages/docusaurus/docs/02-Getting Started/06-how-to-update.md b/packages/docusaurus/docs/02-Getting Started/06-how-to-update.md new file mode 100644 index 0000000..8956773 --- /dev/null +++ b/packages/docusaurus/docs/02-Getting Started/06-how-to-update.md @@ -0,0 +1,33 @@ +# Updating Versions + +Keeping the stack updated is easy because the stack is a collection of Docker images. To update the stack, you can simply pull the latest images from Docker Hub and restart the stack. + +Some basic commands to get you started: + +1. Stop the stack + +```bash +sudo docker compose down +``` + +2. Pull the latest images + +```bash +sudo docker compose pull +``` + +3. Start the stack + +```bash +sudo docker compose up -d +``` + +4. Check the logs + +```bash +sudo docker compose logs -f +``` + +We include a migration scripts to automatically update the database and/or configuration files when necessary. These scripts are run when the container starts, so you don't need to worry about running them manually. + +It's always a good idea to check the release notes for each new version in case there are any breaking changes or new features you need to be aware of. You can find the release notes for each project on their respective GitHub repositories. diff --git a/packages/docusaurus/docs/03-Pangolin/02-Configuration/03-wildcard-certs.md b/packages/docusaurus/docs/03-Pangolin/02-Configuration/03-wildcard-certs.md index 8ea0f19..32073e1 100644 --- a/packages/docusaurus/docs/03-Pangolin/02-Configuration/03-wildcard-certs.md +++ b/packages/docusaurus/docs/03-Pangolin/02-Configuration/03-wildcard-certs.md @@ -122,14 +122,19 @@ traefik: # highlight-start # Add the environment variables for your DNS provider. environment: - CF_API_EMAIL: "admin@example.com" - CF_API_KEY: "854060790571461693d6214d0b0cb1e6" + CLOUDFLARE_DNS_API_TOKEN: "your-cloudflare-api-token" # highlight-end volumes: - ./config/traefik:/etc/traefik:ro - ./config/letsencrypt:/letsencrypt ``` +:::note + +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