Merge branch 'main' of https://github.com/fosrl/docs

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:

packages/docusaurus/docs/02-Getting Started/03-quick-install.md

@@ -4,12 +4,12 @@
 
 - A Linux system with root access and a public IP address
   - We recommend Ubuntu or Debian based systems
-- [A domain name pointed to your server's IP address](./04-dns-networking.md)
+- [A domain name pointed to your server's IP address](./02-dns-networking.md)
-- [TCP ports 80, 443, and UDP port 51820 exposed to your Linux instance.](./04-dns-networking.md)
+- [TCP ports 80, 443, and UDP port 51820 exposed to your Linux instance.](./02-dns-networking.md)
 - An email address for Let's Encrypt certificate registration
 - (Optionally) a SMTP server
 
-Note: If you have **Cloudflare** as your DNS provider [turn off the proxy service](./04-dns-networking.md).
+Note: If you have **Cloudflare** as your DNS provider [turn off the proxy service](./02-dns-networking.md).
 
 ## Installation Steps
 
@@ -22,11 +22,11 @@ Installer binaries for Linux can be found in the [Github releases](https://githu
 For example, on `amd64` download the installer with either wget or curl and make it executable:
 
 ```bash
-wget -O installer "https://github.com/fosrl/pangolin/releases/download/1.0.0-beta.6/installer_linux_amd64" && chmod +x ./installer
+wget -O installer "https://github.com/fosrl/pangolin/releases/download/1.0.0-beta.7/installer_linux_amd64" && chmod +x ./installer
 ```
 
 ```bash
-curl -L -o installer "https://github.com/fosrl/pangolin/releases/download/1.0.0-beta.6/installer_linux_amd64" && chmod +x ./installer
+curl -L -o installer "https://github.com/fosrl/pangolin/releases/download/1.0.0-beta.7/installer_linux_amd64" && chmod +x ./installer
 ```
 
 The installer must be run as root. If you're not already root, switch to the root user or use sudo:

packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/01-docker-compose.md

@@ -1,4 +1,4 @@
-# Manual Install
+# Docker Compose
 
 :::warning
 
@@ -12,8 +12,8 @@ This guide will walk you through setting up the Docker Compose stack manually wi
 
 - A Linux system with root access and a public IP address
   - We recommend Ubuntu or Debian based systems
-- [A domain name pointed to your server's IP address](./04-dns-networking.md)
+- [A domain name pointed to your server's IP address](../02-dns-networking.md)
-- [TCP ports 80, 443, and UDP port 51820 exposed to your Linux instance.](./04-dns-networking.md)
+- [TCP ports 80, 443, and UDP port 51820 exposed to your Linux instance.](../02-dns-networking.md)
 - An email address for Let's Encrypt certificate registration
 - (Optionally) a SMTP server
 

packages/docusaurus/docs/02-Getting Started/04-Manual Install Guides/02-unraid.md

@@ -0,0 +1,225 @@
+# 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.
+
+## Video Tutorial
+
+If you prefer a video tutorial for this guide, you can find it [here](https://youtu.be/F3w1Ur175zI).
+
+## 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.
+
+:::note
+
+Pangolin environment variables will take precedence over the values in the `config.yml` file. If you set an environment variable, it will override the value in the `config.yml` file. This is useful for setting secrets and other sensitive information.
+
+:::
+
+<p align="center">
+    ![graphic](./img/pangolin_config.png)
+</p>
+
+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 `<appdata>/config/traefik`. On each container restart, these files will be overwritten by Pangolin. Thus, if you edit the Traefik files manually, you should set this to `false`. It's best to keep this enabled on first start to generate the files for you to edit later.
+
+If you're using a different Traefik config other than the one provided by Pangolin, it is okay to leave this enabled. It will not overwrite your config unless your config is in the `<appdata>/config/traefik` path which it unlikely is.
+
+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 add the matching environment variable or edit the `config.yml` file to match. For example:
+
+If I wanted to change Host Port 1, I would do the following:
+
+- 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
+- Add a new environment variable with key `SERVER_NEXTPORT` and value as the new port you want to use
+
+This does not apply to the WireGuard port.
+
+Any Gerbil Config:
+
+You can leave these here even if you don't plan to use Gerbil.
+
+Gerbil Base Endpoint:
+
+This should match the Dashboard Url field.
+
+#### 3. Save the config and start the Pangolin container.
+
+Upon starting, Pangolin will create the needed files in the appdata path. You can access the dashboard WebUI by the "Host Port 1" port on your Unraid machine.
+
+#### 4. Log in to the dashboard
+
+Log in with the admin email and password you set in the config. Follow the setup steps.
+
+- Create your first Organization
+- Create your first "Local" site for local reverse proxying
+
+### Install and Setup Traefik
+
+Before starting with Traefik, shut down the Pangolin container.
+
+#### 1. Install Traefik via the CA Store
+
+This section will use the Traefik template from the "Fossorial" repository. It still uses the official Traefik container image. If you already have a Traefik installation running, you should manually configure your Traefik config to work with Pangolin. Take a look at the Traefik files in the Docker Compose guide to see what to add to your config. Also, if you'd prefer to use another Traefik template in the Unraid store such as IBRACORP's you still can. You should just make sure to have the needed variables, ports, paths, etc, as described in this guide.
+
+<p align="center">
+    <img src={require("./img/traefik_repo.png").default} alt="Traefik Repo" style={{
+        width: "400px",
+        height: "auto"
+    }}/>
+</p>
+
+#### 2. Configure Traefik
+
+Set the network to the one you created earlier.
+
+<p align="center">
+    ![graphic](./img/traefik_config.png)
+</p>
+
+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: `<appdata>/config/traefik`.
+
+Lets Encrypt Certs:
+
+Traefik will store the certification information here. You can make this path anywhere you want. For simplicity, we're placing it in the same config path at `<appdata>/config/letsencrypt`.
+
+Ports:
+
+You will need to port forward the https and http ports listed in the config on your network's router.
+
+## 2. Add Gerbil for Tunneling (Optional)
+
+:::note
+
+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.
+
+<p align="center">
+    ![graphic](./img/gerbil_config.png)
+</p>
+
+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".
+
+<p align="center">
+    ![graphic](./img/traefik_networking.png)
+</p>
+
+#### 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._
+
+<p align="center">
+    ![graphic](./img/gerbil_logs.png)
+</p>
+
+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.

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.

packages/docusaurus/docs/03-Pangolin/02-Configuration/02-config.md

@@ -7,10 +7,12 @@ Pangolin is configured using a `config.yml` file. The file is expected to be mou
 ### `app`
 
 -   `dashboard_url`: string
+    -   Env: APP_DASHBOARDURL
     -   Example: `https://example.com` or `https://proxy.example.com`
     -   The url where the application is hosted. This is used for many things, including generating links.
     -   You can run Pangolin on a subdomain or root domain. Users will be redirected to this url to complete the auth step.
 -   `base_domain`: string
+    -   Env: APP_BASEDOMAIN
     -   Example: `example.com`
     -   The base domain for the application. This is used for setting cookies and determining the base domain for resources.
 -   `log_level`: string
@@ -25,10 +27,13 @@ Pangolin is configured using a `config.yml` file. The file is expected to be mou
 ### `server`
 
 -   `external_port`: int
+    -   Env: SERVER_EXTERNALPORT
     -   The port the external facing (public) API will listen on.
 -   `internal_port`: int
+    -   Env: SERVER_INTERNALPORT
     -   The port the internal private facing (private) API will listen on.
 -   `next_port`: int
+    -   Env: SERVER_NEXTPORT
     -   The port the frontend server will listen on.
 -   `internal_hostname`: string
     -   Example: `pangolin`
@@ -45,6 +50,23 @@ Pangolin is configured using a `config.yml` file. The file is expected to be mou
 -   `resource_access_token_param`: string
     -   Example: `p_token`
     -   The query parameter used to pass the access token to the resource. Badger extracts this token and sends it to Pangolin to authenticate. This is used in direct share links that do not require a browser redirect.
+-   `cors`: object (optional)
+    -   Configuration for Cross-Origin Resource Sharing (CORS).
+    -   `origins`: array of strings (optional)
+        -   Example: `["https://proxy.example.com"]`
+        -   List of allowed origins for cross-origin requests.
+    -   `methods`: array of strings (optional)
+        -   Example: `["GET", "POST", "PUT", "DELETE", "PATCH"]`
+        -   HTTP methods allowed for CORS requests.
+    -   `allowed_headers`: array of strings (optional)
+        -   Example: `["X-CSRF-Token", "Content-Type"]`
+        -   HTTP headers allowed in CORS requests.
+    -   `credentials`: boolean (optional)
+        -   Whether to allow credentials.
+        -   Default: true
+-   `trust_proxy`: boolean (optional)
+    -   Whether to trust the proxy headers (e.g., `X-Forwarded-For`) for determining the client IP address.
+    -   Default: `true`
 
 ### `traefik`
 
@@ -63,8 +85,10 @@ Pangolin is configured using a `config.yml` file. The file is expected to be mou
 
 ### `gerbil`
     - `start_port`: int
+      - Env: GERBIL_STARTPORT
       - This is the starting port for WireGuard tunnels that new Gerbil exit nodes will use and increment as they register with Pangolin. Advised to choose a base of a range with no conflicts.
     - `base_endpoint`: string
+      - Env: GERBIL_BASEENDPOINT
       - This is the domain name automatically included in Newt and WireGuard config for tunnel connections.
     - `use_subdomain`: boolean
       - If set to true, new Gerbil exit nodes will be assigned a unique subdomain off of the base domain. Advised to keep this to false.
@@ -105,8 +129,10 @@ Pangolin is configured using a `config.yml` file. The file is expected to be mou
 -   `server_admin`: object
     -   The server admin who can always create new organizations. This user will always be created on startup.
     -   `email`: string
+        -   Env: USERS_SERVERADMIN_EMAIL
         -   The email address of the server admin.
     -   `password`: string
+        -   Env: USERS_SERVERADMIN_PASSWORD
         -   The password of the server admin.
         -   This password will always overwrite the password in the database on startup. This is useful for resetting the password.
         -   The password must meet the following requirements:
@@ -121,11 +147,11 @@ Pangolin is configured using a `config.yml` file. The file is expected to be mou
 -   `require_email_verification`: boolean
     -   Whether to require email verification for new users. If set to `true`, new users will need to verify their email address before they can log in.
     -   Only turn this on if you have email configured.
--   `signup_without_invite`: boolean
+-   `disable_signup_without_invite`: boolean
-    -   Whether to allow users to sign up without an invite. If set to `false`, the "Sign Up" button will be removed from the login form.
+    -   Whether to allow users to sign up without an explicit invite. If set to `true`, the "Sign Up" button will be removed from the login form.
     -   Users will still be able to sign up if they have a valid invite.
 -   `disable_user_create_org`: boolean
-    -   Whether to allow users to create new organizations. If set to `false`, users will not be able to create new organizations.
+    -   Whether to allow users to create new organizations. If set to `true`, users will not be able to create new organizations.
     -   The server admin can always create new organizations.
 
 ## Example Configuration File

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"
+    CLOUDFLARE_DNS_API_TOKEN: "your-cloudflare-api-token"
-    CF_API_KEY: "854060790571461693d6214d0b0cb1e6"
   # 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

packages/docusaurus/docs/03-Pangolin/03-without-tunneling.md

@@ -45,4 +45,8 @@ services:
     volumes:
       - ./config/traefik:/etc/traefik:ro # Volume to store the Traefik configuration
       - ./config/letsencrypt:/letsencrypt # Volume to store the Let's Encrypt certificates
-```
+```
+
+After first starting the app, make sure to fill out all of your information, like `dashboard_url`, `base_domain`, etc the `config.yml` that was generated for you in the volume.
+
+See all configuration options [here](https://docs.fossorial.io/Pangolin/Configuration/config).

packages/docusaurus/docs/06-Newt/02-install.md

@@ -83,7 +83,18 @@ services:
         - --endpoint https://example.com
 ```
 
-#### Unraid, Portainer, and other UIs
+### Unraid
+
+Newt is available in the Unraid Community Applications store. You can install it by searching for Newt in the store and following the prompts. Enter in the ID, secret, and endpoint from Pangolin in the template fields.
+
+<p align="center">
+    <img src={require("./img/unraid_store.png").default} alt="Newt on CA" style={{
+        width: "400px",
+        height: "auto"
+    }}/>
+</p>
+
+### Portainer, and other UIs
 
 These container management UIs typically allow for passing commands and environment vars to the container similar to Docker compose. Look for a commands or arguments box and follow relevant guides.