Deploying a Hugo site with Dokku

This website was built with Hugo and is hosted on a cheap single-core VPS. The server also hosts a few other sites at any given time that will have built using whatever stack interests me at the time. This use-case makes Dokku (which is a self-hosted alternative to Heroku, with all the magic you’d expect) the perfect deployment setup for me.

It is fairly trivial to configure a webserver to serve a static site, but Dokku has accustomed me to never thinking about server configurations, and I am not willing to put in the hour or so that it would take for me to do that. Also, I have a pretty good workflow for all of my projects with Dokku at the terminus, and I am reluctant to change that.


This assumes that you have already installed and configured Dokku on your server, and have created a Hugo site following the quickstart guide. You will also need to have initialized a git repo in your project’s root folder and added the dokku remote. Consult the Dokku documentation for how to do this.

Step 1: Generate the site

Once you have something you are ready to publish, generate the site using the hugo command from your project’s root directory. By default, Hugo will put the built files into .../<your_site>/public/.

Step 2: Add the Nginx buildpack and flag project as static

In my experience, Nginx is the easiest server to use with Dokku. The Dokku (or Heroku) way to do this is by using a buildpack. In your project root, create a file called .buildpacks and paste the following into it:

Save the file and close.

Now create a file called .static in the same location. This does not need any contents, it is just there to let Dokku know that we will be deploying a static site.

Step 3: Configure Dokku

SSH into your server, and create a new app. Add domains to the app and (optionally) get SSL certificates in case you want your site to be available over https.

$ dokku apps:create <your_site> # Create app
$ dokku domains:add <your_site> # Add domains
$ dokku letsencrypt <your_site> # Add SSL certs

Next, since the files we want to serve are not actually in our project’s root but in the .../public/ directory, we need to configure Nginx to serve the site from that directory. Luckily, Dokku provides a convenient way to do this without ever opening up an nginx.conf file. While still in your server, configure the NGINX_ROOT environment variable for your app:

$ dokku config:set <your_site> NGINX_ROOT=/public

Step 3b(ish)

For reasons I can’t explain, the Hugo baseURL parameter does not seem to have any effect when deploying on Dokku. If you run into this problem, try updating your config.toml:

baseURL = ""
relativeURLs = "True"

Step 4: Deploy!

Assuming you had everything set up correctly before following any of the instructions in this guide, you should be able to deploy your site from your local machine with:

$ git push dokku master # Replace branch names with whatever you are calling them

Your site should now be online.

Published At