Creating a static website with Hugo and Nginx

Hugo static site with Nginx on Debian 10

Purpose

Alright, so I was asked to make a resume and keep it current but the problem I was having is that I have 4 or 5 resumes that are stored in different formats as well as going back several years. So I decided to make a master resume that not only appeases the masses, but also keeps track of some of the cool things I have tried to do, the things I have learned, and examples to prove it… all the while using markdown files that do not seem to age. Special thanks to Jon Polom for teaching me the basics on markdown. I contacted another guru of the interwebs, Andrew Dunn, about how to make a site using primarily markdown and his response verbatim, “Hugo”. So here we are.

Setup

  • First things first, I need somehwere to host this site from
    • I originally wanted to host this on a Dell D30 that I am working with but using zfs as a file system kind of scared me off due to permissions and the elaborate stuff that goes with it
    • I’ll be honest, my Manjaro PC was my initial build and setup. The setup was so fast smooth and simple that I really did not want to stray away from it but I also did not want to use my daily driver as work horse because I am selfish that way
    • Winner: Digital Ocean droplet it was. I was kind of bummed that they didn’t have an arch or manjaro image already available so Debian 10 was the next best thing…probably for the best

Install Brew

  • With Debian up and running we need to install hugo but it is not the same as Manjaro by any means. Manjaro was as easy as sudo pacman -S hugo and done. Debian requires brew, which I have never worked with before so that was kind of strange to start with.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  • and you will see this:
==> This script will install:
/home/linuxbrew/.linuxbrew/bin/brew
/home/linuxbrew/.linuxbrew/share/doc/homebrew
/home/linuxbrew/.linuxbrew/share/man/man1/brew.1
/home/linuxbrew/.linuxbrew/share/zsh/site-functions/_brew
/home/linuxbrew/.linuxbrew/etc/bash_completion.d/brew
/home/linuxbrew/.linuxbrew/Homebrew
==> The following new directories will be created:
/home/linuxbrew/.linuxbrew/var
/home/linuxbrew/.linuxbrew/share/zsh
/home/linuxbrew/.linuxbrew/share/zsh/site-functions
/home/linuxbrew/.linuxbrew/var/homebrew
/home/linuxbrew/.linuxbrew/var/homebrew/linked
/home/linuxbrew/.linuxbrew/Cellar
/home/linuxbrew/.linuxbrew/Caskroom
/home/linuxbrew/.linuxbrew/Frameworks

Press RETURN to continue or any other key to abort
  • press Enter, then type in your sudo password *. it takes a bit to finish doing it’s thing but the very end yields the following
==> Next steps:
- Add Homebrew to your PATH in /home/andrewdelorey/.profile:
    echo 'eval $(/home/linuxbrew/.linuxbrew/bin/brew shellenv)' >> /home/andrewdelorey/.profile
    eval $(/home/linuxbrew/.linuxbrew/bin/brew shellenv)
- Run `brew help` to get started
- Further documentation: 
    https://docs.brew.sh
- Install the Homebrew dependencies if you have sudo access:
    sudo apt-get install build-essential
    See https://docs.brew.sh/linux for more information
- We recommend that you install GCC:
    brew install gcc
  • To which we follow blindly and do as the text says:
echo 'eval $(/home/linuxbrew/.linuxbrew/bin/brew shellenv)' >> /home/andrewdelorey/.profile

sudo apt-get install build-essential

brew install gcc

Install Hugo

  • Lets install Hugo

    • brew install hugo
    • yup…that was it.

  • Now we need to create the site but , apparently location is everything. According to the online peeps, creating a site in your home directory is not a good idea and you run into permission problems. Not sure if that is true, but I had a lot of issues on my Debian install when I created the site in my home folder.

  • so change the directory you are in to

cd /var/www/
  • then create your site. Mine is called AndrewResume.
hugo new site AndrewResume

  • This will create a folder with a bunch of stuff in it that is needed to run the site. The site won’t run right yet because it requires a theme to organize the data in a structure.

    • Change your directory to the themes folder and go to https://themes.gohugo.io/ and select a theme that appeals to you.
    • Follow the instructions provided by the theme author to copy the information to your theme folder.
    • I choose the Hugo Initio theme and went to the git repository to copy the exampleSite folder. This was what I based my entire structure on since most of the attributes I wanted were already there. I copied the configs and folders to thier respected locations expecting to see exactly what i saw in the demo
    • While in the AndrewResume folder, start the server ** Note**, You have to be in the correct directory or hugo will not work:
hugo server -D
  • Go to localhost:1313 in your browser
localhost:1313
  • The site should look the same as the demo. Now since I originally did this on a Manjaro pc at my house, it was really easy to modify and see the changes on the fly. The Digital Ocean droplet was not so easy since there was no way for me to see the localhost on a remote machine in the cloud. This is where things get a little sticky and I ran into a bunch of issues because of my ignorance of how things work.

Configure Firewall

I use ufw as my firewall so I am going to go over the install and configuration just to be safe:

  • Install ufw
sudo apt install ufw

Since my setup is remote, I will do my configuration before starting the service.

  • Allow ssh:
sudo ufw allow ssh
  • Allow Nginx
sudo ufw allow 'Nginx Full'
  • Enable firewall
sudo enable ufw

Install Nginx

  • Install nginx
sudo apt install nginx
  • Copy the default nginx file while renaming it to your site. I named mine hugo
cd /etc/nginx/sites-available/
cp default hugo
nano hugo
  • The sile should look like this:
server {
       listen 80;
       listen [::]:80;

       server_name mysite.com www.mysite.com;

       root /home/username/mysite/public/; #Absolute path to where your hugo site is
       index index.html; # Hugo generates HTML

       location / {
               try_files $uri $uri/ =404;
       }
}
  • Because I originally did not look up a tutorial on how to configure nginx, I originally tried to use the proxy_pass parameter with localhost:1313 but some attributes did not work so well. I was having troubles with the source path or baseURL on the webpage stating localhost:1313 instead of the actual website andrew.deloco.us. The site would load but none of the images were coming through, the nginx hugo config looked something like this:

Bad Nginx config

server {
       listen 80;
       listen [::]:80;

        server_name andrew.deloco.us;
        
        location / {
            
            proxy_pass http://localhost:1313;
            
       }
}
  • Which looking at the souce code of the web page, in google, it produced the issue below on line 4

Bad source path example

1     <header id="header">
2  <div id="head" class="parallax" data-parallax-speed="2" style="background-3image:url('http://localhost:1313/images/MainBackDrop2.jpg');">
3    <h1 id="logo" class="text-center">
4      <img class='img-circle' src="http:localhost:1313/images/AndrewCenterPhoto.jpg" alt=""> ##localhost:1313 should be andrew.deloco.us 
5      <span class="title">Andrew DeLorey</span>
6     <span class="tagline">Machinist By Trade<br>
7        <a href="mailto:andrew.delorey@deloco.us">andrew.delorey@deloco.us</a>
8      </span>
9  </h1>
</div>
  • Luckily a smart friend sent me their elaborate configuration which only made things worse before it got better. Apparently proxy_pass was not the solution, the site needed a path to the hugo public folder, (which i will explain in a bit) and index index.html below the stated path. I accidently put it above the root path and it did not like that.

Working config example:

server {
       listen 80;
       listen [::]:80;

	   server_name andrew.deloco.us;
       root /var/www/AndrewResume/public;
	   index index.html

}
  • Remove the default file and enable the config by creating a symbolic link to the sites-available folder
sudo rm /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/hugo /etc/nginx/sites-enabled/hugo
  • Enable and start Nginx
sudo systemctl enable nginx
sudo systemctl start nginx

  • Now this got me in the ballpark but with all the other issues I was working with, I still wasn’t out of the woods. I was under the impression that if you type hugo server -D in the AndrewResume folder, that life was all peachy and things would work right… not for this theme. The configuration file had to be changed to match some of the parameters of the site, AND apparently this version needs you to create a public folder and direct hugo to it. So.. we change it:

  • in the AndrewResume folder type

nano config.toml

The top of the configuration file looks like this

1 BaseURL = "localhost:1313/"
2 languageCode = "en"
3 title = "Andrew DeLorey"
4 theme = "hugo-initio"
5 publishDir = ""

  • Note: I added the line numbers, (ex: 1,2,3,4, etc) for ease of explaining what I did wrong, these numbers do not exist in the actual config file

  • I had to change the configuration to look like this, where line one was changed to “http://andrew.deloco.us/" and line 5 was changed to “public”

1 BaseURL = "http://andrew.deloco.us/"
2 languageCode = "en"
3 title = "Andrew DeLorey"
4 theme = "hugo-initio"
5 publishDir = "public"
  • Next up, I created the public folder, as defined above, in the AndrewResume folder:
mkdir public
  • then created the files by typing:
hugo
  • The software automatically created the webpages and dropped them in the public folder that nginx is pointed to.

Then BAM, the website andrew.deloco.us worked and I congradulated myself, yelled a bit about how great I was then pulled back the excitement and started adding content.