Hugo dev installation

Hugo dev installation

Created: 2025-03-13
Last update: 2025-03-14

Introduction #

The purpose of this document is to provide a simple development environment for starting Hugo projects, based on Debian 12 with Nginx web server. In this setup, Hugo is used to create static pages. Nginx web server is used to serve static pages via https.

Hugo has good documentation and instructions on how to set it up. However, because it’s somewhat OS-agnostic, those instructions may be incomplete and lack some details. Also manual suggests to use built-in http server for development purposes. I consider this approach to be more error-prone since it’s using a different component for testing and production. Since I’m using Nginx web server for hosting, I’d like to use it in my development environment. It both allows me to test in production-like envoronment and it’s easier to deploy into production.

This document is inspired by Hugo’s official manual.

Prerequisites #

A clean Debian 12 instance (VM, container) installed preferably from official Debian netinst image (amd64) or Debian cloud image (amd64).

Install and configure Hugo #

Install Hugo #

  1. Install prerequisite packages
apt update
apt install -y vim git
  1. Install snap package manager. We will need it. Do not install Hugo via apt from official Debian repository, as it’s outdated.
apt install snapd
reboot
  1. Install Hugo from snap
snap install hugo
  1. Confirm Hugo version >= v0.128.0
hugo version

Create basic site #

In this part I will separate workspace for Hugo from space used by Nginx. In a more ‘production like environment’ Hugo should be installed on separate VM/container from Nginx. For dev purposes it’s in the same instance. The Hugo project will be stored in /home/hugo. Nginx will use /var/www/mysite as its root path. Published page will be copied manually.

  1. Create working directory.
mkdir /home/hugo
  1. Create site and download site theme.
hugo new site mysite
cd mysite
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo "theme = 'ananke'" >> hugo.toml
  1. Check if it works (here I run Hugo on VM with 192.168.1.24 IP address on Proxmox hosted VM and I’m trying to access it from my laptop).
hugo server --bind=192.168.1.84 --baseURL=http://192.168.1.84 --port=1313
  1. Add page.
hugo new content content/posts/first-page.md
vim content/posts/first-page.md
  1. Check if you can see the new page in browser. New page probably has the draft flag set, so add -D to render draft too (or remove draft flag from page).
hugo server --bind=192.168.1.84 --baseURL=http://192.168.1.84 --port=1313 -D

Prepare configuration #

  1. Open configuration file.
vim hugo.toml
  1. Add url, laguage, page name etc.
  2. It’s worth to look in theme’s manual to figure out what is expected to be set in config file.

Publish site #

This step creates static files, but does not deploy them.

  1. Execute publish command (sic! it will not include pages marked as drafts)
hugo
  1. All files will now be in public directory now.
ls /home/hugo/quickstart/public

Set up nginx #

In this step we will create a basic nginx https setup with snakeoil ssl cert. Make sure to use production ready certificate and configuration for production purposes.

  1. Make sure you have snakeoil certs.
apt install ssl-cert
cat /etc/ssl/certs/ssl-cert-snakeoil.pem
  1. Edit site’s config.
vim /etc/nginx/sites-available/default

server {
    listen 80;
    server_name yourdomain.com;

    # Redirect all HTTP traffic to HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name yourdomain.com;

    # Use Snakeoil self-signed certificates
    ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
    ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    root /var/www/mysite;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}
  1. Test for syntax error.
nginx -t
  1. Restart nginx.
systemctl restart nginx

Deploy site #

  1. Just copy static files to /var/www/mysite
cp -r /home/hugo/quickstart/public/* /var/www/mysite

How to use #

It’s not convenient to work that way. However it’s simple and allows to understand well what’s going out and how to separate tools.

Simple development cycle may look like this: #

  1. Edit content or sync it from external repo
  2. Publish with hugo command
  3. Deploy by replacing /var/www/mysite

Deploy example #

  1. Publish
cd /home/hugo/quickstart
hugo
  1. Copy to new location
cp -r /home/hugo/quickstart/public /var/www/mysite-new
  1. Deploy
cd /var/www
mv mysite mysite"$(date +"%Y%m%d_%H%M%S")"
mv mysite-new mysite

Deploy one-liner # 

hugo; cp -r /home/hugo/quickstart/public /var/www/mysite-new; (cd /var/www; mv mysite mysite"$(date +"%Y%m%d_%H%M%S")"; mv mysite-new mysite)