wiki/content/en/guides/usersites.md

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

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.

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.

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

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

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 from the official Gemini website. You can also use a gemini-proxy like gp.vern.cc along with Geminize Addon to redirect you to gp.vern.cc when needed.