Toggle menu
Toggle personal menu
Not logged in
Your IP address will be publicly visible if you make any edits.

Caddy: Difference between revisions

From Nest Guides
Samuel (talk | contribs)
Add section about reverse proxies
Samuel (talk | contribs)
Fix default Caddyfile, add note about deleting default directives, point to subdomains/custom domains page
Line 3: Line 3:
By default, you have a Caddy configuration file (<code>Caddyfile</code>) in your home directory, and a directory called <code>pub</code> inside your home directory as well that contains an <code>index.html</code> file. The Caddyfile contains a minimal setup for serving files from the <code>pub</code> directory. Your Caddy server is always running, so you don't need to worry about starting it up.  
By default, you have a Caddy configuration file (<code>Caddyfile</code>) in your home directory, and a directory called <code>pub</code> inside your home directory as well that contains an <code>index.html</code> file. The Caddyfile contains a minimal setup for serving files from the <code>pub</code> 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''' <code>systemctl --user reload caddy</code> '''to load your new configuration into Caddy.'''  
'''However, if you make any changes to your Caddyfile, don't forget to run''' <code>systemctl --user reload caddy</code> '''to load your new configuration into Caddy.'''
 
This guide will lead you through editing the Caddyfile for your default Nest subdomain, <code><username>.hackclub.app</code>. If you'd like to learn how to manage custom subdomains or domains, see [[Subdomains and Custom Domains]].


== Caddyfile ==
== Caddyfile ==
Let's take a look at the default <code>Caddyfile</code> to understand how Caddy works:
Let's take a look at the default <code>Caddyfile</code> to understand how Caddy works:
  {
  {
   admin off
   admin unix//home/<username>/caddy-admin.sock
  }
  }
  http://<username>.hackclub.app {
  http://<username>.hackclub.app {
  bind unix/.webserver.sock|777
    bind unix/.webserver.sock|777
  root * /home/<username>/pub
    root * /home/<username>/pub
  file_server
    file_server {
        hide .git .env
    }
  }
  }
The first 3 lines, containing the <code>admin off</code> line, are part of the ''global configuration'' of Caddy. <code>admin off</code> just tells Caddy to disable the admin API, which is a cool feature that allows you to dynamically access and modify configuration, but that we won't be using.
The first 3 lines, containing the <code>admin off</code> line, are part of the ''global configuration'' of Caddy. <code>admin off</code> just tells Caddy to disable the admin API, which is a cool feature that allows you to dynamically access and modify configuration, but that we won't be using.


What comes next is the configuration for our subdomain, <code><username>.hackclub.app</code> (<code><username></code> will be replaced with your Nest username). You might notice that it specifies <code>http</code> instead of <code>https</code>. This is because there's actually another "root" Caddy server that in turn proxies the request to your Caddy server, and it needs your server to use <code>http</code>. 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 <code>ls</code>!
What comes next is the configuration for our subdomain, <code><username>.hackclub.app</code> (<code><username></code> will be replaced with your Nest username). You might notice that it specifies <code>http</code> instead of <code>https</code>. 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 <code>http</code>. 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 <code>ls -a</code>!


Next up is the line that starts with <code>root</code>. This line just tells Caddy what directory your website/files are in. Finally, the <code>file_server</code> line tells Caddy to just statically serve files directly from that directory!
Next up is the line that starts with <code>root</code>. This line just tells Caddy what directory your website/files are in. Finally, the <code>file_server</code> line tells Caddy to just statically serve files directly from that directory!
Line 27: Line 30:
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
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
  <code>reverse_proxy :<port></code>
  <code>reverse_proxy :<port></code>
to the bottom of your subdomain's configuration, and replace <code><port></code> with the port on which the other web server is running. Once you reload Caddy, you should that all requests are forwarded to that server! See [https://caddyserver.com/docs/quick-starts/reverse-proxy Caddy's docs on reverse proxies] to learn more.
to the bottom of your subdomain's configuration, replace <code><port></code> with the port on which the other web server is running, and delete the default <code>file_server</code> directive. Once you reload Caddy, you should that all requests are forwarded to that server! See [https://caddyserver.com/docs/quick-starts/reverse-proxy Caddy's docs on reverse proxies] to learn more.

Revision as of 21:56, 23 August 2024

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 off line, are part of the global configuration of Caddy. admin off just tells Caddy to disable the admin API, which is a cool feature that allows you to dynamically access and modify configuration, but that we won't be using.

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!

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.