fosrl/docs
1
0
Fork 0
mirror of https://github.com/fosrl/docs.git synced 2025-05-12 21:30:43 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

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

Browse source
This commit is contained in:
Milo Schwartz 2025-01-02 22:28:52 -05:00
commit f1a602efc3
No known key found for this signature in database
2 changed files with 103 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
packages/docusaurus/docs/01-overview.md
View file

@ -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

102
packages/docusaurus/docs/02-Getting Started/02-quick-setup.md
View file

@ -2,4 +2,104 @@
## Prerequisites
- Followed the setup steps and have a Pangolin server running with Gerbil, Traefik and Badger.
- 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/newt/releases/download/v1.0.0-beta.1/newt"
```
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
#### Target
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 for this resource. If your resource is accessible on your internal network at `http://192.168.1.24:8080` for example, then choose the following
Method: HTTP
IP Address: 192.168.1.24
Port: 8080
4. Press `Add Target` and you will see the target added to the list and enabled.
5. Press `Save Changes`
6. Try to access your resource by clicking the url at the top
:::tip
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. For instant access, consider setting up wildcard certificates.
:::
#### Authentication
1. Choose the **Authentication** page under the resource
By default the resource is protected with your same Pangolin account. When opening the resource it just loads because you are already logged in. If you were not, you would first be redirected to Pangolin to login before being sent back to the resource.
If you would like to disable Pangolin auth, you can disable the `Use Platform SSO` toggle.
:::warning
It is not recommended to expose a resource without some form of authentication. Only do this if you need to for the functionality of the resource or you trust the built-in auth.
:::
For advanced auth control with users, roles, passwords, pins, or email whitelists, see .....
### 6. Invite Users (optional)
1. Head to the **Users and Roles** tab
2. Press `Invite User`
3. Enter an email for the new user. If you have setup SMTP during the setup you can choose to send an email invite to the new user
4. Select the role for the new user. All users must have a role. The admin role gives the user access to all resources and to create new resources and sites. The member role only provides access to resources explicitly attached to the role (none by default). For more information, see .....
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.