Caddy

Caddy is a webserver - that is, it's a program that'll serve your website (and any other web resource, such as an API) for all to see! It's also the default and recommended webserver to use on Nest.

By default, you have a Caddy configuration file (Caddyfile) in your home directory, and a directory called pub inside your home directory as well that contains an index.html file. The Caddyfile contains a minimal setup for serving files from the pub directory. Your Caddy server is always running, so you don't need to worry about starting it up.

However, if you make any changes to your Caddyfile, don't forget to run systemctl --user reload caddy to load your new configuration into Caddy.

This guide will lead you through editing the Caddyfile for your default Nest subdomain, <username>.hackclub.app. If you'd like to learn how to manage custom subdomains or domains, see Subdomains and Custom Domains.

Caddyfile

Let's take a look at the default Caddyfile to understand how Caddy works:

{
  admin unix//home/<username>/caddy-admin.sock
}
http://<username>.hackclub.app {
    bind unix/.webserver.sock|777
    root * /home/<username>/pub
    file_server {
        hide .git .env
    }
}

The first 3 lines, containing the admin line, are part of the global configuration of Caddy. admin unix//home/<username>/caddy-admin.sock tells Caddy to make the admin API accessible through a unix socket in your home directory - this way, only you can access it and modify your configuration.

What comes next is the configuration for our subdomain, <username>.hackclub.app (<username> will be replaced with your Nest username). You might notice that it specifies http instead of https. This is because there's actually another "main" Caddy server that in turn proxies the request to your Caddy server, and it needs your server to use http. It proxies that request through your webserver's socket, which is specified on the next line. You can even see this socket in your home directory if you run ls -a!

Next up is the line that starts with root. This line just tells Caddy what directory your website/files are in. Finally, the file_server line tells Caddy to just statically serve files directly from that directory (with the hide directive inside making sure you don't accidentally leak any secrets)!

Caddy is very powerful and has a ton of more features, but this is enough for you to get a simple website running. You can explore all of Caddy's features in their docs at https://caddyserver.com/docs/.

Reverse Proxy

A reverse proxy is a server that forwards client requests to web servers. This is useful if you have something like an API server or a Docker container already on another port, and need to access it from the internet. With Caddy, this is simple. Just add

reverse_proxy :<port>

to the bottom of your subdomain's configuration, replace <port> with the port on which the other web server is running, and delete the default file_server directive. Once you reload Caddy, you should that all requests are forwarded to that server! See Caddy's docs on reverse proxies to learn more.

Error Pages

If no application is listening to the port specified in the reverse proxy, or if nothing has been added to the Caddyfile, you'll receive an error when trying to access the website:

If you want to change the email that shows up, create a .error-page-email file, like so:

echo "orpheus@hackclub.com" > ~/.error-page-email