feat: port user_sites

content/en/guides/usersites.md

@@ -1,3 +1,212 @@
 ---
 title: "How to host websites on ~vern"
----
+---
+
+This guide will show you how to host websites on ~vern. By default, any user can host a website.
+~vern hosts normal HTTP webpages which are accessible on the clearnet, the Tor network and the I2P network. ~vern also hosts Gopher holes and Gemini capsules, which are seperate from HTTP webpages.
+
+Please try the the fixes in the troubleshooting section before you [ask the administrators](/staff/#admins) for help.
+
+## Static sites
+
+Static files are the easiest to host, since there is no software needed at runtime beyond the web server (Which is automatically running at all times)
+
+When you add files at `~/public_html`, it will appear at `<USERNAME>.vern.cc`. Simple, right?
+
+Though you need to be careful about file permissions, the Nginx webserver that ~vern uses should be able to read your `public_html` directory, if you are experiencing issues with static web hosting then file permissions are the most probable cause. Simply run `chmod +x ~/public_html/ -R` to fix this issue.
+
+Oh and the default webserver supports [server-side includes](https://en.wikipedia.org/wiki/Server_Side_Includes)
+
+## CGI
+
+CGI are static files that are executed when they get a request, these are slightly more complicated than 
+
+CGI can be served by making a file with the `.cgi`, `.py`, `.sh`, `.pl`, `.lua`, or `.php` extensions. Any files in `/cgi-bin` will be executed, too.
+`.php` files will be executed with, well, PHP. While `.cgi` files will be executed with sh. You can change that by adding a shebang like this:
+
+```
+#!/usr/bin/env lua
+
+print([[Content-type: text/plain
+
+Hello
+]])
+```
+
+This will result in `Hello` at `<USERNAME>.vern.cc/hello.cgi`, assuming the CGI file is at `hello.cgi`.
+
+Binaries work shebang-less, of course.
+
+*Note: any binary referenced must be installed for the php user which runs php and cgi scripts. If the packages referenced are installed globally, you should be fine but if they are not, you would have to use a `nix-shell shebang`. Instructions on that can be found in the [nixos wiki](https://nixos.wiki/wiki/Nix-shell_shebang).*
+
+## Webserver via UNIX sockets
+
+This is a very minimal example of a webserver done via a UNIX Socket, made with Caddy:
+```
+{
+        admin off
+}
+
+http://
+bind unix/.webserver.sock
+
+respond "Hello ~vern!"
+```
+
+**Note:** The `admin off` is for others to be not able to change your config, and also that the `2019` port won't conflict with others.
+
+Save that into your home directory, run `caddy run` and at `https://a-<username>.vern.cc`, the webserver should appear. (No, the URL is not mispelled.)
+
+### Multiple sites
+
+Now that you've got a webserver running on `a`, time to utilize all the other letters!
+```
+{
+        admin off
+}
+
+http://a-<USERNAME>.vern.cc {
+        bind unix/.webserver.sock
+        respond "Hello"
+}
+
+http://b-<USERNAME>.vern.cc {
+        bind unix/.webserver.sock
+        respond "Hello 2"
+} 
+```
+Now if you go to `https://b-<username>.vern.cc`, Hello 2 should appear!
+
+## Reverse-proxying a non-UNIX service
+
+**Note:** You should read the documentation of the program that you are using instead of doing this method in order to not waste ports or (slightly) speed, if possible.
+
+*Note to warning above: If you want to use sub-hosts and the program supports UNIX sockets, you can still do routing with Caddy since it supports reverse-proxying to a UNIX socket. Do not use a port if you have the option to not.*
+
+Using a Caddyfile like this should work:
+```
+{
+        admin off
+}
+
+http://a-<USERNAME>.vern.cc {
+        bind unix/.webserver.sock
+        reverse_proxy :9000
+}
+```
+
+Easy, right?
+
+### Advanced Example
+
+This example includes some advanced features from Caddy but also make it easier to add multiple sites:
+```
+{
+  admin off
+  auto_https off
+  order respond before reverse_proxy
+  default_bind unix//home/{$USER}/.webserver.sock
+}
+
+(host) {
+  @{args.0} host {args.0}-{$USER}.vern.cc
+}
+
+http://
+
+import host ping
+import host web
+import host reverse
+
+handle @ping {
+  respond "PONG!"
+}
+
+handle @web {
+  root * /home/{$USER}/public_html
+  file_server
+}
+
+handle @reverse {
+  reverse_proxy * :9000
+}
+
+respond "Nothing here!"
+```
+
+If you are confused, the following is an explanation.
+The first part of the file is the global config.
+```
+{
+  admin off
+  auto_https off
+  order respond before reverse_proxy
+  default_bind unix//home/{$USER}/.webserver.sock
+}
+```
+The `default_bind` is really handy, so we don't have to specify for every route the socket to bind to. `{$USER}` comes from the environment variable `$USER` and will be your username.
+Additionally, to the global config you could add your email with `email <your@email.com>`
+
+Next we give the snippet feature a look:
+```
+(host) {
+  @{args.0} host {args.0}-{$USER}.vern.cc
+}
+```
+With that, it is a lot easier to add a new site.
+To add a new site we can do: `import host hello`, this adds now a matcher definition and looks like this:
+```
+@hello host hello-<USERNAME>.vern.cc
+```
+Snippets are similar to functions, if you look closer you can see how the matcher definition got created:
+```
+@{args.0} host {args.0}-{$USER}.vern.cc
+```
+The `{args.0}` part got replaced with `hello` and `{$USER}` is just the environment variable for your username, like what was mentioned above.
+
+Now with the matcher we can handle the site like this:
+```
+handle @hello {
+  responed "Hello, World!"
+}
+```
+and `hello-<USERNAME>.vern.cc` will now respond with `Hello, World!`.
+
+In the handler you can define every aspect of how you want to handle the site.
+You can do a simple response like:
+```
+handle @ping {
+  respond "PONG!"
+}
+```
+
+Hosting a static website: (in this example hosting `<USERNAME>.vern.cc` also on `web-<USERNAME>.vern.cc`)
+```
+handle @web {
+  root * /home/{$USER}/public_html
+  file_server
+}
+```
+
+Or you can make a reverse proxy:
+```
+handle @reverse {
+  reverse_proxy * :9000
+}
+```
+
+For more information, see [this page from the Caddy Docs](https://caddyserver.com/docs/caddyfile/patterns).
+
+## Gemini capsules
+
+Gemini is a simple protocol for delivering websites and webpages. It is way simpler than HTTP while still being powerful enough for an average website.
+
+If you are a ~vern user then you won't have to do anything to get Gemini hosting to work. Check out the troubleshooting section if you are experiencing issues.
+
+Gemini does not use HTML files for webpages, Gemini uses its own document format called Gemtext, you can read more about Gemtext [here](https://gemini.circumlunar.space/docs/gemtext.gmi)
+
+Once you write your gemtext file, you can simply copy it to the `~/public_gemini` folder and it should be available at `<USERNAME>.vern.cc`
+
+Gemini does support cgi files, and all the supported variables [can be found here](https://gp.vern.cc/gemini/80h.dev/projects/gemserv)
+
+**Note:** Most browsers do not support Gemini natively, you will need to use a special browser that has support for Gemini documents. You can find one in [this list](https://gemini.circumlunar.space/software/index.html#Clients) from the official Gemini website. You can also use a gemini-proxy like [gp.vern.cc](https://gp.vern.cc) along with [Geminize Addon](https://gitlab.com/nocylah/geminize) to redirect you to gp.vern.cc when needed.