From d7fb72aac1915e6738cde8483dfdff9ab482e4b2 Mon Sep 17 00:00:00 2001 From: Owen Schwartz Date: Thu, 2 Jan 2025 21:23:14 -0500 Subject: [PATCH] Start writing setup docs --- packages/docusaurus/docs/01-overview.md | 4 +- .../docs/02-Getting Started/02-quick-setup.md | 67 ++++++++++++++++++- 2 files changed, 68 insertions(+), 3 deletions(-) diff --git a/packages/docusaurus/docs/01-overview.md b/packages/docusaurus/docs/01-overview.md index 0973749..0dc77fb 100644 --- a/packages/docusaurus/docs/01-overview.md +++ b/packages/docusaurus/docs/01-overview.md @@ -29,8 +29,8 @@ Pangolin’s architecture consists of the following components, each designed to ### [**Newt**](https://github.com/fosrl/newt) (Minimal User Space WireGuard Client) A lightweight client designed to run on the private network. Newt: - - Connects to the Pangolin server via WebSocket for managing endpoints. - - Facilitates networking through its connection to Gerbil over the encrypted tunnel. + - Connects to the Pangolin server via WebSocket and Gerbil via fully user space Wireguard + - Facilitates networking through its connection to Gerbil and creating TCP proxies ## System Diagram diff --git a/packages/docusaurus/docs/02-Getting Started/02-quick-setup.md b/packages/docusaurus/docs/02-Getting Started/02-quick-setup.md index 6995052..bb7013f 100644 --- a/packages/docusaurus/docs/02-Getting Started/02-quick-setup.md +++ b/packages/docusaurus/docs/02-Getting Started/02-quick-setup.md @@ -2,4 +2,69 @@ ## Prerequisites -- Followed the setup steps and have a Pangolin server running with Gerbil, Traefik and Badger. \ No newline at end of file +- Followed the setup steps and have a Pangolin server running with Gerbil, Traefik and Badger. +- Logged into the Pangolin management interface + +## First Setup Steps + +### 1. Create a Org + +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. + +### 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 +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 +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. + +On Linux, you can wget the newt binary and run the command copied during the create site step + +```bash +wget -O installer "https://github.com/fosrl/pangolin/releases/download/v1.0.0-beta.1/installer" +``` + +Then run newt + +```bash +./newt --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://example.com +``` + +#### Wireguard + +With Wireguard you will be responsible for ensuring your targets are reachable with the /29 subnet provided or proxied/NATed from the Wireguard host. + +You are provided a /29 subnet in the 10.0.0.0/16 range that Gerbil uses per site. + +For example on a Linux client, you can write your copied config to a wg0.conf file and run `wg-quick up ./wg0.conf` + +### 4. Create a Resource + +1. Head to the **Resources** tab and select the `Add Resource` button +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. +5. Press `Create Resource` + +### 5. Add Targets and Authentication + +1. You should now be on the **Connectivity** page under your new resource +2. If you would like to secure this site with https, leave the `Enable SSL` toggle enabled +3. Add a target + +Note: After you create your resource if you are using https certificates with LetsEncrypt (default) then you must wait some time after a target is created for your certificate to be granted and loaded by Traefik. This should take no more than a few minutes. + +### 6. Invite Users (optional) + +1. Head to the **Users and Roles** \ No newline at end of file