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

packages/docusaurus/docs/01-overview.md

@@ -1,8 +1,12 @@
 # Overview
 
+The Fossorial system - with Pangolin at its core - is a self-hosted tunneled reverse proxy with identity and access management, designed to securely expose private resources through encrypted [WireGuard](https://www.WireGuard.com/) tunnels running in user space. Think self hosted Cloudflare tunnels.
+
+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!
+
 ## Components Overview
 
-Pangolin’s architecture consists of the following components, each designed to handle a specific aspect of the system:
+Fossorial has a couple major components:
 
 ### [**Pangolin**](https://github.com/fosrl/pangolin) (Management Application & Central Server)
    The central hub for managing the application. Pangolin includes:

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

@@ -11,14 +11,22 @@
 
 ### 1. Downloading and Running the Installer
 
-Download the installer with either wget or curl:
+Installer binaries for Linux can be found in the [Github releases](https://github.com/fosrl/pangolin/releases) for ARM and AMD64 (x86_64).
+
+For example, on `amd64` download the installer with either wget or curl:
 
 ```bash
-wget -O installer "https://github.com/fosrl/pangolin/releases/download/v1.0.0-beta.1/installer"
+wget -O installer "https://github.com/fosrl/pangolin/releases/download/v1.0.0-beta.1/installer_linux_amd64"
 ```
 
 ```bash
-curl -L -o installer "https://github.com/fosrl/pangolin/releases/download/v1.0.0-beta.1/installer"
+curl -L -o installer "https://github.com/fosrl/pangolin/releases/download/v1.0.0-beta.1/installer_linux_amd64"
+```
+
+Make it executable:
+
+```bash
+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/02-quick-setup.md

@@ -11,31 +11,38 @@
 
 An org is a way to collect sites, users, and resources.
 
-When you log into the app for the first time you will be prompted to create an org.
+When you log into the app for the first time you will be prompted to create an org. Simply choose a name and an ID. Note that the ID can not be changed later!
 
 ### 2. Create a site
 
 A site is a remote location that you want to proxy through the tunnel and system. For example your home server, or a IOT device. A site will terminate one tunnel.
 
-1. Head to the **Sites** tab and select the `Add Site` button
+1. Head to the **Sites** tab and select the `Add Site` button (or use the tab in the setup workflow)
 2. Give your site a name like "Home Lab"
 3. Choose your connection method. You can either use the Newt client (recommended) or a standard WireGuard tunnel. 
 4. Copy the Newt command or the WireGuard config, confirm you have copied it, and press `Create Site`
 
 ### 3. Connect a Tunnel
 
-#### Newt
+#### Newt (recommended)
+
 Assuming you chose Newt above, install and configure it to connect to Gerbil and Pangolin
 
-There are 2 ways to setup Newt: with the CLI application or the Docker container. See ..... for all options. 
+There are 2 ways to setup Newt: with the CLI application or the Docker container. See [Newt install](/newt/install) for all options. 
 
-On Linux, you can wget the newt binary and run the command copied during the create site step
+On Linux, you can wget the newt binary and run the command copied during the create site step. Make sure to replace amd64 with your architecture!
 
 ```bash
-wget -O installer "https://github.com/fosrl/newt/releases/download/v1.0.0-beta.1/newt"
+wget -O newt "https://github.com/fosrl/newt/releases/download/1.0.0-beta.1/newt_linux_amd64"
 ```
 
-Then run newt
+Make it executable: 
+
+```bash
+chmod +x ./newt
+```
+
+Then run Newt
 
 ```bash
 ./newt --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://example.com
@@ -51,7 +58,7 @@ For example on a Linux client, you can write your copied config to a wg0.conf fi
 
 ### 4. Create a Resource
 
-1. Head to the **Resources** tab and select the `Add Resource` button
+1. Head to the **Resources** tab and select the `Add Resource` button (or use the tab in the setup workflow)
 2. Give your resource a name like "Bitwarden"
 3. Choose a subdomain for this resource. The subdomain must be ***globally unique** across all orgs and sites
 4. Choose the site that this resource is at. The resource target must be accessible behind the tunnel attached to this site.
@@ -102,4 +109,4 @@ For advanced auth control with users, roles, passwords, pins, or email whitelist
 5. Choose how long this invite will be valid for and choose `Create Invitation`
 6. If you chose not to send the email or it is not setup, then be sure to copy the invite and send it to the user
 
-The new user will be prompted to setup a password and verify their email (if SMTP is supported). They will show up in your table once they confirm their account.
+The new user will be prompted to setup a password and verify their email (if SMTP is supported). They will show up in your table once they confirm their account.

packages/docusaurus/docs/03-Pangolin/02-Configuration/_category_.json

@@ -1,7 +0,0 @@
-{
-  "label": "Configuration",
-  "position": 2,
-  "link": {
-    "type": "generated-index"
-  }
-}

packages/docusaurus/docs/06-Newt/01-overview.md

@@ -41,6 +41,18 @@ Example:
 --endpoint https://example.com
 ```
 
+```yaml
+services:
+  newt:
+    image: fosrl/newt
+    container_name: newt
+    restart: unless-stopped
+    command:
+        - --id 31frd0uzbjvp721
+        - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
+        - --endpoint https://example.com
+```
+
 ## Build
 
 ### Container 

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

@@ -0,0 +1,88 @@
+# Install
+
+Newt can be used as either a static binary executable or a Docker container.
+
+### Configuration
+
+Configuration is passed in as CLI args in both the binary and the Docker container. In order to run Newt and have it connect to something you **must first create a site and copy the newt config** in Pangolin.
+
+### Binary
+
+Binaries for Linux, MacOS, and Windows can be found in the [Github releases](https://github.com/fosrl/newt/releases) for ARM and AMD64 (x86_64) versions of Newt. It should be as simple as downloading for your respective platform, making sure it is executable, and running it with the correct [CLI args](/newt/overview#cli-args).
+
+On Linux for example:
+
+Download Newt with either wget or curl or from your browser:
+
+```bash
+wget -O newt "https://github.com/fosrl/newt/releases/download/1.0.0-beta.1/newt_linux_amd64"
+```
+
+```bash
+curl -L -o newt "https://github.com/fosrl/newt/releases/download/1.0.0-beta.1/newt_linux_amd64"
+```
+
+Make it executable:
+
+```bash
+chmod +x ./newt
+```
+
+And run it:
+
+```bash
+./newt \
+--id 31frd0uzbjvp721 \
+--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
+--endpoint https://example.com
+```
+
+To install permanently to your PATH (may need to run as root):
+
+```bash
+mv ./newt /usr/local/bin
+```
+
+### Docker
+
+You can find the built docker container [on Docker hub](https://hub.docker.com/r/fosrl/newt).
+
+To pull it: 
+
+```bash
+docker pull fosrl/newt:latest
+```
+
+Then to run it from the command line with args from Pangolin:
+
+```bash
+docker run -it fosrl/newt --id 31frd0uzbjvp721 \
+--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
+--endpoint https://example.com
+```
+
+You can also run it with Docker compose. For example, a service in your `docker-compose.yml` might look like:
+
+```yaml
+services:
+  newt:
+    image: fosrl/newt
+    container_name: newt
+    restart: unless-stopped
+    command:
+        - --id 31frd0uzbjvp721
+        - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
+        - --endpoint https://example.com
+```
+
+And you could start it by simply running:
+
+```bash
+docker compose up -d
+```
+
+#### Unraid, Portainer, and other UIs
+
+These container management UIs typically allow for passing commands to the container similar to Docker compose. Look for a commands or arguments box and follow relevant guides. 
+
+We intent to crate more extensive documentation on this in the future. If you would like to contribute, please do!

packages/docusaurus/docs/06-Newt/03-security.md

@@ -0,0 +1,15 @@
+# Security Overview
+
+There are two components of Newt auth to discuss: the WireGuard portion and the websocket command and control portion.
+
+### WireGuard
+
+Newt generates a WireGuard public / private key pair every time it starts up and uses this new pair when registering wih Pangolin and Gerbil. The private key is not stored on the system and never leaves the current process (never sent to the cloud). The public key is transmitted over the websocket on startup and is stored in the Newt table for the Newt ID and sent to Gerbil to create a new peer. In Newt, only the internal IP of the Gerbil WireGuard server is added to allowed IPs effectively locking out packets that do not come from Gerbil itself. In Gerbil, only the internal IP of the remote Newt instance is installed in the allowed IPs effectively locking out packets that do not come from that Newt proxy itself.
+
+### HTTP and Websocket
+
+Newt is started with a Newt ID and a secret. Pangolin uses the ID to identify the client and link it with a site and other metadata. The secret is cryptographically generated when the site is created and stored hashed in the database.
+
+All command and control is done over the Websocket, so Newt first must connect to that. In order to connect, Newt must present a valid token which is obtained by making an HTTP API request to `/api/v1/auth/newt/get-token` with the Newt ID and secret. Pangolin will hash this secret and attempt to look it up in the table. Assuming it finds a match it will cryptographically generate and store a token in the sessions table and return it to the client. Using this token, Newt can connect to the websocket which first looks it up in the sessions table to determine if it exists and is still valid. If so it allows the websocket connection. 
+
+Having connected, Newt will transmit its newly minted public key to Pangolin and will receive shortly after a "WireGuard" init message with the public key of the peer, allowedIps, and initial targets to proxy. 

packages/docusaurus/docs/07-roadmap.md

@@ -66,3 +66,7 @@ Are you experienced with authentication procedures and best practices? We would
 - [ ] SSH resource support to connect to non-HTTP based endpoints
 - [ ] Additional proxy features like headers to use Pangolin auth on downstream resources
 - [ ] A CICD deployment workflow to Docker and Github
+
+### SAAS
+
+We intend at some point to provide Pangolin in a hosted offering with a healthy free tier and pricing competitive to generally available cloud VPS services. This way users who would like to use Pangolin - but don't want to manage their own VPS - can do so and help to fund future development.