feat: docs site (#286)

* feat: docs site * docs: copy * chore(docs): update cli post * revert * chore: go.mod
antoniomika · Jan 29, 2024 · 0c4f193 · 0c4f193
1 parent 6892112
commit 0c4f193
Show file tree

Hide file tree

Showing 33 changed files with 3,738 additions and 424 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,27 @@
+name: docs
+on:
+  push:
+    branches:
+      - main
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set outputs
+        id: vars
+        run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+      - uses: actions/setup-go@v4
+        with:
+          go-version: '1.21'
+      - name: build docs site
+        run: make ssg
+      - name: publish to pgs
+        uses: picosh/pgs-action@v3
+        with:
+          user: hey
+          key: ${{ secrets.PRIVATE_KEY }}
+          src: './public/'
+          project: "sish-${{ steps.vars.outputs.sha_short }}"
+          promote: "sish-prod"
+          retain: "sish-"
diff --git a/.gitignore b/.gitignore
@@ -2,3 +2,5 @@ deploy/
 dist/
 sish
 __debug_bin
+docs/public/*
+!docs/public/.gitkeep
diff --git a/Makefile b/Makefile
@@ -0,0 +1,21 @@
+clean:
+	rm -rf ./docs/public/*
+	echo "" > ./docs/public/.gitkeep
+.PHONY: clean
+
+ssg:
+	go run ./docs/cmd
+	cp ./docs/static/* ./docs/public
+.PHONY: ssg
+
+docs: ssg
+	rsync -vr ./docs/public/ [email protected]:/sish-local
+.PHONY: docs
+
+docs-prod: ssg
+	rsync -vr ./docs/public/ [email protected]:/sish-prod
+.PHONY: docs-prod
+
+dev:
+	go run main.go --http-address localhost:3000 --domain testing.ssi.sh
+.PHONY: dev
diff --git a/README.md b/README.md
diff --git a/deploy/gcloud.md b/deploy/gcloud.md
@@ -1,20 +1,23 @@
 # sish installation
 
-sish is an open source serveo/ngrok alternative that can be used to open a tunnel
-to localhost that is accessible to the open internet using only SSH. sish implements
-an SSH server that can handle multiplexing of HTTP(S), TCP, and TCP Aliasing
+sish is an open source serveo/ngrok alternative that can be used to open a
+tunnel to localhost that is accessible to the open internet using only SSH. sish
+implements an SSH server that can handle multiplexing of HTTP(S), TCP, and TCP
+Aliasing
 ([more about this can be found in the README](https://github.com/antoniomika/sish/blob/main/README.md))
 
 This tutorial will teach you how to:
 
-* Setup an instance in Google Cloud using the [free tier](https://cloud.google.com/free)
-* Add and modify authentication for users
-* Access sish from a remote computer
+- Setup an instance in Google Cloud using the
+  [free tier](https://cloud.google.com/free)
+- Add and modify authentication for users
+- Access sish from a remote computer
 
 ## Project selection
 
-You first need to select a project to host the resources created in this tutorial.
-I'd suggest creating a new project at this time where your sish instance will live.
+You first need to select a project to host the resources created in this
+tutorial. I'd suggest creating a new project at this time where your sish
+instance will live.
 <walkthrough-project-setup></walkthrough-project-setup>
 
 ## Access Google Cloud Shell
@@ -23,14 +26,18 @@ I'd suggest creating a new project at this time where your sish instance will li
 
 ## Create the instance running the container
 
-Here is a command to create the instance running the sish container. This will start the container
-on a hardened [Container Optimized OS](https://cloud.google.com/container-optimized-os/docs) and start
-the service. This is just a starting command that runs sish on port `2222`, `80`, and `443`. If you
-accept the [Let's Encrypt TOS](https://letsencrypt.org/repository/), you can enable automatic SSL cert loading.
-This command does *NOT* include authentication and it is up to you to properly tune these parameters based on
-the documentation [here](https://github.com/antoniomika/sish#cli-flags). Make sure to update `YOURDOMAIN`
-to the actual domain you own. You will also need to setup the DNS records as described below. Also feel free
-to change the `--zone` used for these commands.
+Here is a command to create the instance running the sish container. This will
+start the container on a hardened
+[Container Optimized OS](https://cloud.google.com/container-optimized-os/docs)
+and start the service. This is just a starting command that runs sish on port
+`2222`, `80`, and `443`. If you accept the
+[Let's Encrypt TOS](https://letsencrypt.org/repository/), you can enable
+automatic SSL cert loading. This command does _NOT_ include authentication and
+it is up to you to properly tune these parameters based on the documentation
+[here](https://github.com/antoniomika/sish#cli-flags). Make sure to update
+`YOURDOMAIN` to the actual domain you own. You will also need to setup the DNS
+records as described below. Also feel free to change the `--zone` used for these
+commands.
 
 ```bash
 gcloud compute instances create-with-container sish \
@@ -82,17 +89,18 @@ gcloud compute firewall-rules create allow-all-tcp-sish \
 
 Get the external IP address of your machine and create two DNS records
 
-* An `A` record for YOURDOMAIN pointing it to the output below
-* An `A` record for *.YOURDOMAIN pointing it to the output below
+- An `A` record for YOURDOMAIN pointing it to the output below
+- An `A` record for *.YOURDOMAIN pointing it to the output below
 
 ```bash
 gcloud compute instances describe sish \
     --zone="us-central1-a" \
     --format='get(networkInterfaces[0].accessConfigs[0].natIP)'
 ```
 
-To confirm that the DNS records were created appropriately, you can run:  
-`dig @1.1.1.1 abcxyz.YOURDOMAIN` and `dig @1.1.1.1 YOURDOMAIN`. Both should get an answer with `status: NOERROR`. 
+To confirm that the DNS records were created appropriately, you can run:\
+`dig @1.1.1.1 abcxyz.YOURDOMAIN` and `dig @1.1.1.1 YOURDOMAIN`. Both should get
+an answer with `status: NOERROR`.
 
 ## Using sish
 

diff --git a/docs/cmd/ssg.go b/docs/cmd/ssg.go
@@ -0,0 +1,94 @@
+package main
+
+import (
+	"github.com/picosh/pdocs"
+)
+
+func main() {
+	pager := pdocs.Pager("./docs/posts")
+	sitemap := []*pdocs.Sitemap{
+		{Text: "Home", Href: "/", Page: pager("home.md")},
+		{Text: "Sitemap", Href: "/sitemap", Page: pager("sitemap.md")},
+		{
+			Text: "Getting Started",
+			Href: "/getting-started",
+			Page: pager("getting-started.md"),
+			Tag:  "Help",
+			Children: []*pdocs.Sitemap{
+				{Text: "Managed"},
+				{Text: "DNS"},
+				{Text: "Docker Compose"},
+				{Text: "Docker"},
+				{Text: "Google Cloud Platform"},
+				{Text: "Authentication"},
+			},
+		},
+		{
+			Text: "How it Works",
+			Href: "/how-it-works",
+			Page: pager("how-it-works.md"),
+			Tag:  "Help",
+			Children: []*pdocs.Sitemap{
+				{Text: "Port Forward"},
+				{Text: "Traditional VPN"},
+				{Text: "sish Public"},
+				{Text: "sish Private"},
+				{Text: "Additional Details"},
+			},
+		},
+		{
+			Text: "Forwarding Types",
+			Href: "/forwarding-types",
+			Page: pager("forwarding-types.md"),
+			Tag:  "Help",
+			Children: []*pdocs.Sitemap{
+				{Text: "HTTP"},
+				{Text: "TCP"},
+				{Text: "TCP Alias"},
+				{Text: "SNI"},
+			},
+		},
+		{
+			Text: "Cheatsheet",
+			Href: "/cheatsheet",
+			Page: pager("cheatsheet.md"),
+			Tag:  "Help",
+			Children: []*pdocs.Sitemap{
+				{Text: "Remote forward SSH tunnels"},
+				{Text: "Local forward SSH tunnels"},
+				{Text: "HTTPS public access"},
+				{Text: "HTTPS private access"},
+				{Text: "Websocket"},
+				{Text: "TCP public access"},
+				{Text: "TCP private access"},
+			},
+		},
+		{Text: "CLI", Href: "/cli", Page: pager("cli.md"), Tag: "CLI"},
+		{
+			Text: "Advanced",
+			Href: "/advanced",
+			Page: pager("advanced.md"),
+			Children: []*pdocs.Sitemap{
+				{Text: "Choose your own subdomain"},
+				{Text: "Websocket Support"},
+				{Text: "Allowlist IPs"},
+				{Text: "Custom Domains"},
+				{Text: "Load Balancing"},
+			},
+			Tag: "Help",
+		},
+		{Text: "FAQ", Href: "/faq", Page: pager("faq.md"), Tag: "Help"},
+	}
+
+	config := &pdocs.DocConfig{
+		Sitemap:  sitemap,
+		Out:      "./docs/public",
+		Tmpl:     "./docs/tmpl",
+		PageTmpl: "post.page.tmpl",
+	}
+
+	err := config.GenSite()
+	if err != nil {
+		panic(err)
+	}
+}
diff --git a/docs/posts/advanced.md b/docs/posts/advanced.md
@@ -0,0 +1,81 @@
+---
+title: Advanced
+description: How to customize sish
+keywords: [sish, advanced, custom, domains, load, balancing, allowlist, ip]
+---
+
+# Choose your own subdomain
+
+You can choose your own subdomain instead of relying on a randomly assigned one
+by setting the `--bind-random-subdomains` option to `false` and then selecting a
+subdomain by prepending it to the remote port specifier:
+
+`ssh -p 2222 -R foo:80:localhost:8080 tuns.sh`
+
+If the selected subdomain is not taken, it will be assigned to your connection.
+
+# Websocket Support
+
+The service supports multiplexing connections over HTTP/HTTPS with WebSocket
+support. Just assign a remote port as port `80` to proxy HTTP traffic and `443`
+to proxy HTTPS traffic. If you use any other remote port, the server will listen
+to the port for TCP connections, but only if that port is available.
+
+# Allowlist IPs
+
+Whitelisting IP ranges or countries is also possible. Whole CIDR ranges can be
+specified with the `--whitelisted-ips` option that accepts a comma-separated
+string like "192.30.252.0/22,185.199.108.0/22". If you want to whitelist a
+single IP, use the `/32` range.
+
+To whitelist countries, use `--whitelisted-countries` with a comma-separated
+string of countries in ISO format (for example, "pt" for Portugal). You'll also
+need to set `--geodb` to `true`.
+
+# Custom domains
+
+sish supports allowing users to bring custom domains to the service, but SSH key
+auth is required to be enabled. To use this feature, you must setup TXT and
+CNAME/A records for the domain/subdomain you would like to use for your
+forwarded connection. The CNAME/A record must point to the domain or IP that is
+hosting sish. The TXT record must be be a `key=val` string that looks like:
+
+```text
+sish=SSHKEYFINGERPRINT
+```
+
+Where `SSHKEYFINGERPRINT` is the fingerprint of the key used for logging into
+the server. You can set multiple TXT records and sish will check all of them to
+ensure at least one is a match. You can retrieve your key fingerprint by
+running:
+
+```bash
+ssh-keygen -lf ~/.ssh/id_rsa | awk '{print $2}'
+```
+
+If you trust the users connecting to sish and would like to allow any domain to
+be used with sish (bypassing verification), there are a few added flags to aid
+in this. This is especially useful when adding multiple wildcard certificates to
+sish in order to not need to automatically provision Let's Encrypt certs. To
+disable verfication, set `--bind-any-host=true`, which will allow and
+subdomain/domain combination to be used. To only allow subdomains of a certain
+subset of domains, you can set `--bind-hosts` to a comma separated list of
+domains that are allowed to be bound.
+
+To add certficates for sish to use, configure the
+`--https-certificate-directory` flag to point to a dir that is accessible by
+sish. In the directory, sish will look for a combination of files that look like
+`name.crt` and `name.key`. `name` can be arbitrary in either case, it just needs
+to be unique to the cert and key pair to allow them to be loaded into sish.
+
+# Load balancing
+
+sish can load balance any type of forwarded connection, but this needs to be
+enabled when starting sish using the `--http-load-balancer`,
+`--tcp-load-balancer`, and `--alias-load-balancer` flags. Let's say you have a
+few edge nodes (raspberry pis) that are running a service internally but you
+want to be able to balance load across these devices from the outside world. By
+enabling load balancing in sish, this happens automatically when a device with
+the same forwarded TCP port, alias, or HTTP subdomain connects to sish.
+Connections will then be evenly distributed to whatever nodes are connected to
+sish that match the forwarded connection.