Guide

Learning Hugo

First I need to install Hugo, and learn how to use some basic commands in order to:

• Create a new Hugo project
• Setting up a theme with git submodules
• Adding some content and run a Hugo server to serve the content locally

Deployment

• The first thing that I need to set up a new VPS (Virtual Private Server) on DigitalOcean, this is nothing but a VM machine run on Linux where my server is hosted and serve the static website

• During creation, I set up an SSH key that I can use later to connect to the remote Linux machine, this consists of

  • Generating an SSH key-pair (public/private/passphrase) in my machine with ssh-gen
  • Copying the public key and configure it so the server can use it for authentication
  • Connecting to the VM through opening a session in my local with this command: ssh <user_name>@<public_v4_ip>

Note: ssh (SSH client) is a program for logging into a remote machine and for executing commands on a remote machine. It is intended to provide secure encrypted communications between two untrusted hosts over an insecure network. X11 connections, arbitrary TCP ports and Unix-domain sockets can also be forwarded over the secure channel.

CI/CD Pipeline with GitLab

The goal is to automatically build and deploy the site to the VPS every time a commit is pushed to main.

The pipeline has two stages defined in .gitlab-ci.yml:

• build — uses the hugomods/hugo:exts Docker image to run hugo build --cleanDestinationDir, which regenerates the entire public/ folder from scratch. The theme is pulled via GIT_SUBMODULE_STRATEGY: recursive since it lives in a git submodule.

• deploy — uses rsync to sync the public/ folder to /var/www/public/ on the VPS over SSH. The --delete flag ensures files removed from the build are also removed from the server.

The deploy only runs on main. Feature branches only run the build stage, which is enough to validate that Hugo compiles successfully.

SSH Authentication

The pipeline authenticates to the VPS using a dedicated SSH key pair:

• The private key is stored as a GitLab CI/CD variable (SSH_PRIVATE_KEY)
• The public key is added to ~/.ssh/authorized_keys on the VPS

In the pipeline, the key is loaded into an SSH agent before running rsync:

eval $(ssh-agent -s)
echo "$SSH_PRIVATE_KEY" | ssh-add -
rsync -avz --delete -e "ssh -o StrictHostKeyChecking=no" public/ user@vps:/var/www/public/

Nginx

Nginx is installed on the VPS and configured to serve static files from /var/www/public/:

server {
    listen 80;
    server_name _;

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

    location / {
        try_files $uri $uri/ =404;
    }
}

This config is set up once manually — the pipeline only manages the file content, not the server configuration.