How to Deploy a Hugo Static Site

Clever Cloud launched a french speaking podcast about two weeks ago. We decided to use the Hugo static site generator to make it available online. This post explains how we deployed it.

There are many technical solutions out there to host your podcast, like Ausha or Anchor. They will allow you to configure everything needed and upload your material so you get a proper RSS feed in the end. Because Podcast subscribtions are basically RSS feed subscribtions. And these services can also go the extra mile and automatically distribute your podcast to other sites. This is actually the main reason why we use Ausha. It’s way easier.

That being said we still want to have a dedicated page on our existing website and host the RSS and media files ourselves. And it turns out there is a great Hugo theme for podcast hosting.

If you are not familiar with Hugo it’s one of the most popular static site generator. It’s fast, mature, loaded with cool features and still in active development. Community is super helpful and you will find many different themes for different purposes like blog, documentation, FAQ or even podcast.

To follow along you need to install git, hugo and clever-tools. Let’s see how this works.

Create a new Hugo website

Creating a new Hugo website is pretty straightforward. Create a folder to contain your site and inside it run hugo new site. Then you can add the theme you want as a submodule, copy the theme sample configuration and you should be ready to start working on your site. Here’s what I did:

mkdir mysite
cd mysite
hugo new site .
git init
git submodule add https://github.com/mattstratton/castanet themes/castanet
cp themes/castanet/exampleSite/config.toml config.toml 
git add .
git commit -m'init'

From here you can run hugo server and your site will be available at localhost:1313, with automatic reloading and file modification watching. This command will fail because it cannot find the theme. No worries, it’s because we copied the config file from the theme directory, and its theme folder location is hardcoded. We don’t need it anymore. So go ahead and edit config.toml. Start by removing or commenting themesdir on line 6. Then add your own configuration and create new content. I have set the baseUrl to clever-cloud.com/fr/podcast.

Notice that this is not a traditional baseUrl as it’s assuming something else is already running on clever-cloud.com. And this is fine, Clever Cloud knows how to manage this. From here you can add some content and finish your own configuration. Then it’s time to deploy on Clever Cloud.

Deploy to Clever Cloud

At the root of your website create a file called hugo.sh with the following content:

wget https://github.com/gohugoio/hugo/releases/download/v$HUGO_VERSION/hugo_extended_"$HUGO_VERSION"_Linux-64bit.tar.gz
tar xvf hugo_extended_"$HUGO_VERSION"_Linux-64bit.tar.gz
chmod +x ./hugo
./hugo --gc --minify --destination public/fr/podcast

Don’t forget to make it executable with chmod +x hugo.sh, add and commit it. This script will be executed by Clever Cloud thanks to our deployment hooks. It downloads Hugo with the version you specified in the environment variables then run the build of the website. The build destination is specified manually as public/fr/podcast, the default would be public. This is because we need to serve the content on clever-cloud.com/fr/podcast and not just clever-cloud.com.

Now let’s use clever-tools to create, configure and deploy the application. In the terminal run the following:

clever create --type static-apache mysite
clever domain add clever-cloud.com/fr/podcast
clever config set force-https enabled
clever env set CC_PRE_BUILD_HOOK "./hugo.sh"
clever env set CC_WEBROOT "/public"
clever env set HUGO_ENV "production"
clever env set HUGO_VERSION "0.68.3"
clever deploy

This will create the application on Clever Cloud, add the custom domain clever-cloud.com/fr/podcast, and yes this works even though we already have an application serving clever-cloud.com. The new domain will take precedence. Then we enforce HTTPS redirection and set a bunch of environment variable for our configuration. Last command deploys the website to Clever Cloud. From here you should see logs popping up.

And this is it. You have deployed a static website in production that will be updated automatically each time you push new content, on top of an existing website. Please let us know if you have any questions about static site deployment.