basic caddy uses

2024 Aug 31

i'm writing this because the caddy docs are garbage and overcomplicate things to the point where it is frustrating as hell to try to do something. i already have quick notes/references to everything below but i figure some explanation would help.

this guide assumes you are using caddy bare metal with system-d but i'm sure the caddy-file parts are applicable to docker or other deployments.

reverse proxy

it is SHIT EASY to reverse proxy with caddy but their docs don't really make that clear unfortunately. it literally takes like, 2-3 lines tops. 2 lines not counting the end bracket. it's that easy.

literally all you have to do is the following code, replacing the 192 address with your internal server's IPv4 address, and the corresponding port for the service you're proxy, and replace 'example.com' with the right domain/sub-domain that you want to proxy to:

https://example.com {
        reverse_proxy 192.168.1.123:8080
}

THAT'S IT. THAT'S ALL YOU HAVE TO DO. of course reload caddy after doing this:

sudo systemctl reload caddy

make sure you reload caddy every time you make an edit to the caddy-file. this is important! otherwise your changes won't take effect.

reverse proxy with basic auth

let's say you want to password protect a certain page, or the whole site, with basic auth. this is the easiest way of going about doing that straight through caddy, even if not as secure as other authentication options.

for the following caddy-file snippet, the whole site will be password protected. if you want to protect only a certain page, replace the /* wildcard with /page and replace 'page' with whatever page it is you want to protect. additionally, replace 'username' with the username of your choice for the authentication credentials.

https://example.com {
        reverse_proxy 192.168.1.123:8080
        basicauth /* {
                username basicauth_hash
        }

}

again, reverse proxy things from above apply.

basicauth_hash is actually a placeholder - to use basic auth with caddy, you have to hash the password first with htpassword (to get a bcrypt hash), then paste that hash into the caddy-file. you can do this with the below command; just replace 'user' with the desired username that'll also go in the caddyfile, and 'password_to_be_hashed' with the password of your choice and input it. be aware that bash has trouble with special characters and you may have to escape them.

htpasswd -nbBC 10 username password_to_be_hashed

after you run that and copy the output, paste the hash into the caddy-file, replacing 'basicauth_hash'.

static site

to deploy a static site with caddy, the site files must be hosted on the same machine that caddy is deployed on. it might be possible doing it from a remote location but i wouldn't know. just throw your files in /var/www/ instead of home directory because home directory permissions fuck with caddy.

for the snippet below, simply replace /path/to/directory with the /var/www/ path to your site. make sure it includes at least an index.html file that caddy can read so it can serve it.

https://example.com {
        root * "/path/to/dir"
        file_server
}

also make sure you replace 'example.com' with the domain/sub-domain of your choice - caddy automatically deals with the certifications and site serving, so you don't have to worry about anything else. just reload your file and navigate to your domain and it should be up!

static file browse directory

if you want your viewers to browse an open directory of files, such as text files or documentation or anything that may be useful, caddy makes this SHIT easy. i personally use file browse as an image gallery kinda thing but we'll get to that later. all you have to do to get a basic directory going is similar to what you did above; just specify a root directory where your files are, organized into folders and such or nothing at all, up to you how messy you want it to be (be aware there is no search function as this is just a basic list of files), then specify 'browse' as below:

https://example.com {
    root * "/path/to/dir"
    file_server browse
}

that's literally it! how cool is that! now here's how i force it to stay on the 'grid' view, so it functions as a very simplistic image gallery. it's some fuck-y code i stole from a kind genius person on the caddy forums, no clue where i got it since it was so long ago, but one day i'll find it again and properly credit. what this code does is appends the 'grid' view URL code to every page that is clicked and loaded on the site, so you essentially can't force it to use list, but if you're doing an image gallery kinda thing (one use case: displaying dreamwidth icons), it's very useful:

https://example.com {
    root * "/path/to/dir"
    file_server browse

    @directories `path('*/') && {query} == ''`
        redir @directories ?layout=grid
}

you don't have to touch any of the @directories and below code. just modify the above placeholders, reload caddy, and you're good.

that's it

if i discover any more handy tricks with caddy i'll make another post! i hope this is helpful to anyone who comes by it!

home
me