Installing hugo, HAProxy and setting up SSL via Let's Encrypt

Published 01-08-2017 06:00:08

This article serves as a very brief introduction on how to install and setup hugo, and serve this out of a root domain via HTTPS on FreeBSD using HAProxy and Let’s Encrypt.

Hugo

Introduction

Hugo is a very simple platform for rendering webpages from markdown. While it contains an inbuilt web server for serving clients, it does not yet (As of v0.18.1) support SSL.

Installation

Installation is quite easy

  1. Install the latest release from https://github.com/spf13/hugo/releases
  2. Ensure binary goes into /usr/local/sbin or similar (ie: in $PATH)

Configuration

Hugo does not need elevated privs. To create a new root in ~/blog/<my_domain>:

$ mkdir ~/blog
$ cd ~/blog
$ hugo new site <my_domain>

You’ll now see hugo has created it’s document root in ~/blog/<my_domain>. Next, adding a new post:

$ cd ~/blog/\<my_domain>
$ hugo new post/first.md

Hugo will create a new, mostly empty post in ~/blog/<my_domain>/content/post/first.md.

Lastly, starting hugo’s HTTP server:

 $ hugo  serve   --baseURL "https://<my_domain>" --appendPort=false

Once you are happy with this, you can add this to an @reboot crontab, since there are no init scripts as present. If you use pygments server side code highlighting, you’re going to need to set a PATH which contains both the hugo binary, and the pygments binary. Here is the script I use to launch hugo:

Installed in ~/bin/hugo.sh. Then

$ chmod +x /usr/home/<username>/bin/hugo.sh
$ crontab -e
@reboot /usr/home/<username>/bin/hugo.sh 

Note: Hugo generates links based on the baseURL specified above. However since it default binds to :1313, hugo decides to generate perma links in the form https://<my_domain>:1313/path/to/post. This is not ideal, so we need to specify –appendPort=false so links are not broken by proxying the content.

At this point, it’s good to read the configuration guide, and also to shop around for themes.

Lets Encrypt

Introduction

Let’s Encrypt is a free CA which you can use to get signed SSL certs for your domain(s). Setup on FreeBSD is pretty straight forward, with one or two tricks. We are going to use certbot to handle certificate generation.

  1. If not done already, install root CA certs

    $ cd /usr/ports/security/ca_root_nss/
    $ make install
    
  2. Follow certbot install instructions

  3. Setup a temp /.well-known/ dir to communicate with Lets Encrypt

    $ mkdir ~/blog/<my_domain>/static/.well-known
    $ certbot certonly --webroot -w ~/blog/\<my_domain>/static/ -d <my_domain>
    $ rm -Rf ~/blog/<my_domain>/static/.well-known
    

The setup is interactive, so please follow through. Once completed, you should have a full cert chain in /usr/local/etc/letsencrypt/live/<my_domain>/

HAProxy

Introduction

HAProxy is the tool we are going to use to serve hugo content over HTTPS. HAProxy setup requires one or two tricks. Mostly, we need to take Let’s Encrypt cert chain and prep is for HAProxy.

Installation

  1. Install from ports

    $ /usr/ports/net/haproxy
    $ make install
    
  2. Prep PEM cert for HAProxy

    $ mkdir -p /etc/haproxy/certs/
    # DOMAIN='<my_domain>' sh -c 'cat /usr/local/etc/letsencrypt/live/$DOMAIN/fullchain.pem /usr/local/etc/letsencrypt/live/$DOMAIN/privkey.pem > /etc/haproxy/certs/$DOMAIN.pem'
    

Configuration

  1. Config. Here is an example configuarion here, and should reside in /usr/local/etc/haproxy.conf
  1. Enable HAProxy in /etc/rc.conf by setting haproxy_enable=“YES”

    $ echo -e "#Enable HAProxy" >> /etc/rc.conf
    $ echo 'haproxy_enable="YES"' >> /etc/rc.conf
    
  2. Start HAProxy

    $ /usr/local/etc/rc.d/haproxy start
    
  3. Test!