From f3b2a130fe407e5565e2d90a90fd16ae67ac16b0 Mon Sep 17 00:00:00 2001
From: Peter-Jan Brone <peter-jan@settlemint.com>
Date: Tue, 22 Sep 2020 12:23:53 +0200
Subject: [PATCH] Wildcard Subdomains Documentation (#416)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add documentation on subdomains

* Update copy

* Fix typo

* Link Karol his repo

* Update copy

* Update setup-scripts/README.md

Co-authored-by: Karol Wypchło <kwypchlo@gmail.com>

Co-authored-by: Karol Wypchło <kwypchlo@gmail.com>
---
 setup-scripts/README.md | 64 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/setup-scripts/README.md b/setup-scripts/README.md
index e1a743a0..ce02358b 100644
--- a/setup-scripts/README.md
+++ b/setup-scripts/README.md
@@ -88,6 +88,70 @@ At this point we have almost everything running, we just need to set up your wal
 1. `docker-compose up -d` to restart the services so they pick up new env variables
 1. `docker exec caddy caddy reload --config /etc/caddy/Caddyfile` to reload Caddyfile configuration
 
+## Subdomains
+
+It might prove useful for certain skapps to be accessible through a custom
+subdomain. So instead of being accessed through `https://portal/[skylink]`, it
+would be accessible through `https://[skylink_base32].portal`. We call this
+subdomains and it is made possible by encoding Skylinks using a base32 encoding.
+We have to use a base32 encoding scheme because subdomains have to be all lower
+case and the base64 encoded Skylink is case sensitive and thus might contain
+uppercase characters.
+
+You can convert Skylinks using this [converter
+skapp](https://siasky.net/hns/convert-skylink/), to
+see how the encoding and decoding works, please follow the link to the repo in
+the application itself. 
+
+To configure this on your portal, you have to make sure to configure the following:
+
+### Wildcard SSL Certificate
+
+We need to ensure SSL encryption for skapps that are accessed through their
+subdomain, therefore we need to have a wildcard certificate. This is very easily
+achieved using Caddy.
+
+```
+(siasky.net) {
+    siasky.net, *.siasky.net {
+        tls {
+```
+
+(see `../docker/caddy/Caddyfile`)
+
+### Nginx configuration
+
+In Nginx two things need to happen:
+
+- parse the subdomain from the url
+- proxy_pass the request to the appropriate location
+
+Siad is able to make the conversion and treat this as a regular Skylink.
+
+```
+  # parse subdomain (a base32 encoded Skylink) into custom variable
+  server_name "~^([a-z0-9]{55})\..*$";
+  set $subdomain $1;
+
+  ...
+
+  location / {
+    ...
+    error_page 418 = @subdomain;
+    recursive_error_pages on;
+    if ($subdomain  != "") {
+      return 418;
+    }
+    ...
+  }
+  ...
+  location @subdomain {
+    ...
+  }
+```
+
+(see `../docker/nginx/nginx.conf`)
+
 ## Useful Commands
 
 - Starting the whole stack