self-host a Hugo web app
29 MARCH 2020
Last updated
29 MARCH 2020
Last updated
After hosting with Netlify for a few years, I decided to head back to self hosting. There are a few reasons for that, but the main reasoning was that I had more control over how things worked.
In this post, I'll show you my workflow for deploying my Hugo generated site (www.jaredwolff.com).
Instead of using what most people would go for, I'll be doing all of this using a FreeBSD Jails-based server. Plus I'll show you some tricks I've learned over the years on bulk image resizing and more.
Let's get to it.
If you want to host your own service, you'll need a server. That's where a VPS provider like Digital Ocean or Vultr comes in. I've been a fan and have used Digital Ocean for a while now.
To set up a new server here are some steps:
Login to Digital Ocean. If you don’t have Digital Ocean and would like to support this blog click here to create an account.
Go to Account Settings
-> Security
and make sure you have an SSH key setup.
Create a new FreeBSD droplet. Make sure you use the UFS version
Make sure you select the $5 a month plan. For simple installs, this is more than enough!
SSH in once you’re done: ssh root@<yourserverip>
Up until recently, everything was running on a Docker based platform using Exoframe. It was easy and almost brainless.
The downside was that Docker takes up wayyyy too many resources. Plus managing files within a Docker container is as much or more work than hosting it natively. Oh, and have you checked how much space Docker has been using on your machine lately? On my development machine its was about 19GB of space. 😬
So what's the alternative?
FreeBSD Jails using Bastille.
I've been playing with Bastille for a few months now. The more I use it, the more it makes 100% sense.
Bastille allows you to create (now) portable lightweight FreeBSD based jails. These jails are "containers" that have virtually no overhead. There's no daemon (the operating system is the "daemon"!). Plus, jails are secure compared to the can of worms that Docker is. Yes, you may have to compile and port some utilities. Most though are already supported in FreeBSD's package manager pkg
.
In this section you'll learn how to get a jail running with caddy
so you can securely host your site.
Let's keep the momentum going!
Once you get the IP address for your server, you should login:
You should get a MOTD message and an sh
prompt. Woo!
Let's install a few important bits using pkg
(FreeBSD's package manager):
We'll be using restic
for backups, rsync
for transferring files and bastille
for jail setup.
You also have to set up some static routes in your pf.conf
. Here's an example of mine:
This is a standard pf.conf
file for bastille
. Make sure you edit caddy_addr
to the IP you chose.
Now let's start the firewall. You will get kicked out of your ssh
session:
Then let's get some bastille
configuration out of the way:
This will set up your networking, and fetch the latest default base jail you'll use later.
Next, let's set up the jail:
Then install caddy
When installing ca_root_nss
, pkg
will have to initialize. Accept the prompts. Once you're done here we'll move on to the next step!
Once installation is complete, we should also configure caddy
to start on boot. The easiest way to do that is use this rc.d
script:
Remove the caddy
executable if you haven't already. Then create a new file with vi
. This will be your rc.d
script!
Then paste the contents of the above script in there, save and exit.
Make sure the file is executable by using chmod
and copy to the Caddy container.
Finally, we'll need a Caddyfile. Here's an example of one:
log
refers to this site specific access log.
root
refers to where the root public
folder is on your machine. In my case it's the common /var/www/<name of site>
. Set your paths and remember them. We'll need them later!
To have Caddy generate certs for this subdomain, you'll have to set the tls option. An email is all that's needed.
For more on the Caddyfile structure check out the documentation.
Make a file called caddyfile.conf
and copy it to /usr/local/etc/
in your Caddy container:
You should now redirect your DNS to the server IP. That way Caddy can generate/fetch the correct certificates. Then you can start Caddy with:
You can check the log at /usr/home/caddy/caddy.log
to make sure that your domain provisioned correctly.
Side note: Getting setup with SSL certs is tough at first, especially if you're migrating from another server. Your site will have to go down for a little bit while you switch your DNS settings and start caddy
.
(That's if you're using standard caddy
1.0. You can also use the DNS provider plugins here which make things a little easier.)
Now that we have caddy
up and running it's time to copy our hugo
generated assets over using rsync
. We're off to the next step!
I spend a ton of time writing C code, and that means I spend tons of time using Makefiles. For many, make
(or gmake
for GNU make) is the bane of their existence.
For building and deploying, make
makes it easy to create reusable recipes. That way you know you can deploy with confidence every time.
My Makefile borrows from the one that Victoria Drake had posted not too long ago. I changed it up a bit to match my needs.
Let's take a tour and see what's inside:
The first section contains all the variables that I use to tell the functions later on what to do. It also has a reference to the .POSIX
target. This means that the Makefile will be as portable between different versions of make
.
Then, I popped in some logic to determine whether I'm deploying to stage or production:
By default, recipes below will use the development workflow. To use the production workflow, you can invoke make
like this:
This does add some extra friction to the deploy process. It's a good step though. That way you're sure the deploy is going to the right place!
Using the TARGET
variable above, I then define the path to my server assets. I'm using Bastille to organize my jails, so the path is extra long. (yea, lengthly long) This allows us to use rsync
to deploy the files with ease.
Now here come the fun bits. To do a full bulk resize, I'm using the wildcard
functionality of the Makefile.
In this case it will create a huge space delimited list of every image that is within my content directory. The biggest drawback of this method is that it's not space tolerant. An easy fix to this is to make sure that all my photos do not have spaces.
Here's a quick and dirty bash command. You can use to rename files that have spaces and replace them with '_' characters:
Next, we rename these entries so the prefix is now the target directory. This will be useful when we want to resize:
Now check out the optimize
recipe:
It first calls the build
recipe and then also the $(OPTIMIZED_IMAGES)
recipe. The later will optimize the image using the convert
command from Imagemagick. In this case I'm only resizing files that are larger than 730px wide. Change yours accordingly so you can reap the benefits of an optimized site.
After resizing, the recipe uses rsync
to copy the files from the OPTIMIZED_DIR
to DEST_DIR.
If we take a look at the build
recipe, I first building the assets. Then, I copy the photos from the content
dir to optimized
dir. The nice thing is that rsync
will only move files that have changed. Thus it doesn't have to copy the files over and over and over again every time you build.
Finally, the deploy
recipe.
You can see again that I'm using rsync to sync the contents of public/
to the server. Make sure you set the USER
, SERVER
and DEPLOY_DIR
. In my case DEPLOY_DIR
comes out to /usr/local/bastille/jails/caddy/root/var/www/www.jaredwolff.com
When you do finally get a successful deploy you can double check everything is in the correct place. Then once everything looks good you can start up your caddy server using:
deploy
will also do something extra handy here. It will deploy my restic
backup script and run it. I'll talk about this more in the backup section.
All in all, here's the full Makefile:
There are a few other handy nuggets in there you may want to use. clean
, serve
and ssh
have been very helpful when testing and connecting.
In the end you'll have a two step deploy process. The first generates your site with optimized images. The second is deploying to a server for static hosting.
After discovering Restic I've been sold on how handy it has been for all my incremental backup needs. In the case of my server, I'm using to back up the root folder of my site. That way, if I need to roll back, I can do so with a few short steps.
Here's how you can set up a local restic
repo.
Initializing the repo is simple. The most important part is making sure you don't lose/forget your password!
Set the RESTIC_PASSWORD
environment variable to avoid entering your password. To make it permanent you'll have to place export RESTIC_PASSWORD="Your password here!"
within the .profile
file in /root/
.
Invoking restic
over SSH is tough. So our next best bet?
Transfer a (very brief) shell script to the server and run it after a deploy. Here's the contents of what I'm using today:
Side note: As I sit here and look at this script, for security reasons you can replace "Your password here!" with $2 which is the second argument to the script. That way you don't need to commit/push the password stored in a static file!
This first sets your backup password. Then it runs restic
using the first command line argument as the path. So, to run a backup with this script, it would look something like this:
Note: you do need to initialize your restic
backup before you start backing up. It will barf at you otherwise!
In my case I'm placing the incremental backups on a different folder of my machine. That way they're easily accessible and fast.
To view your backups you can run the following command:
You can use this list to determine if you need to roll back a deploy.
Restoring from a backup, especially in a live environment, needs to be quick. After viewing your backups you can restore a specific backup by using its ID.
This will restore the files back to the backup made on 2020-03-10 00:30:58. Awesome. Plus it won't overwrite every single file. It will only apply the differences from the current state and the stored state.
We've covered a ton of ground in this post. You've learned how to:
Deploy your own server using Vultr
Use Bastille to create Container-like Jails
Set up Caddy to serve static file assets with TLS
Deploy the files using a fairly simple Makefile and rsync
Back up after every deploy using restic
In the end we have a robust, secure and simple platform for hosting static files and services.
Stay tuned as there are more posts like this coming your way soon! In the meantime check out my other posts.
Thanks for reading and see you next time! 👍
You can find other articles like this at www.jaredwolff.com.
Reference: https://www.freecodecamp.org/news/my-latest-self-hosted-hugo-workflow/
Make sure your SSH key is selected
Finally click that green Create Droplet button!