blog/DEPLOYMENT.md

Deployment Guide for LXC Container

This guide explains how to deploy this Hugo website to an LXC container running Ubuntu (or similar). The site runs as a live Hugo server with a reverse proxy forwarding requests.

Prerequisites

• LXC container with Arch Linux (or adjust package manager commands for your distribution)
• SSH access to the container
• Git installed on container
• Domain name dustin.coffee pointing to container's IP address (or adjust baseURL in hugo.toml)

Step 1: Install Hugo Extended on LXC

Important: This theme requires Hugo extended version ≥ 0.123.0. Ubuntu's default apt repository provides an outdated version (v0.123.7). You must install a newer extended version.

Option A: Using installation script (Recommended)

Copy the install-hugo.sh script to your container and run it:

# On your container, as root or with sudo:
chmod +x install-hugo.sh
./install-hugo.sh

Option B: Manual installation for Ubuntu/Debian

# Remove old Hugo if installed
sudo apt remove -y hugo

# Add Hugo APT repository
ARCH=$(dpkg --print-architecture)
echo "deb [arch=${ARCH} signed-by=/etc/apt/keyrings/hugo.gpg] https://hugo-apt.8hob.io latest main" | sudo tee /etc/apt/sources.list.d/hugo.list
sudo chmod 644 /etc/apt/sources.list.d/hugo.list

# Add signing key
sudo mkdir -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/hugo.gpg https://hugo-apt.8hob.io/signing-key
sudo chmod 644 /etc/apt/keyrings/hugo.gpg

# Pin repository priority
echo 'Package: hugo
Pin: origin "hugo-apt.8hob.io"
Pin-Priority: 520' | sudo tee /etc/apt/preferences.d/hugo
sudo chmod 644 /etc/apt/preferences.d/hugo

# Install Hugo Extended
sudo apt update
sudo apt install -y hugo

# Install git (required for Hugo modules)
sudo apt install -y git

Verify installation

Check that you have the extended version:

hugo version
hugo env | grep HUGO_EXTENDED
# Should show: HUGO_EXTENDED=true

If hugo version shows v0.123.7 or earlier, the installation failed. Try Option B or install the binary manually from Hugo releases.

Step 2: Clone Repository

Clone your git repository to a directory, e.g., /srv/www/dustin.coffee:

sudo mkdir -p /srv/www
sudo chown $USER:$USER /srv/www
cd /srv/www
git clone <your-git-repo-url> dustin.coffee
cd dustin.coffee

# Initialize theme submodule (required for hello-friend-ng theme)
git submodule update --init --recursive

Step 3: Run Hugo Server (Reverse Proxy Setup)

Since you're using a reverse proxy pointing to the LXC container, run Hugo as a live server:

cd /srv/www/dustin.coffee
hugo server --bind 0.0.0.0 --port 1313 --baseURL=https://dustin.coffee --appendPort=false --disableLiveReload

Important flags:

• --bind 0.0.0.0 – Listen on all network interfaces
• --port 1313 – Port for the reverse proxy to forward to (adjust if different)
• --baseURL=https://dustin.coffee – Your public domain (must match reverse proxy)
• --appendPort=false – Don't include port 1313 in generated URLs (critical for correct links)
• --disableLiveReload – Disable live reload in production

Systemd Service (Recommended for production)

Create /etc/systemd/system/hugo-dustin.service:

[Unit]
Description=Hugo Server for dustin.coffee
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/srv/www/dustin.coffee
ExecStart=/usr/bin/hugo server --bind 0.0.0.0 --port 1313 --baseURL=https://dustin.coffee --appendPort=false --disableLiveReload
Restart=on-failure

[Install]
WantedBy=multi-user.target

Adjust paths:

• Replace /usr/bin/hugo with hugo if installed via apt repository
• Set User/Group to your LXC user if not www-data
• Update WorkingDirectory to your site path

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable hugo-dustin
sudo systemctl start hugo-dustin

Check status: sudo systemctl status hugo-dustin

Step 4: Reverse Proxy Configuration

SSL/TLS encryption should be configured at your reverse proxy level (not Hugo).

Hugo itself runs on HTTP (port 1313). Your reverse proxy should:

• Terminate SSL at the proxy (HTTPS on port 443)
• Forward HTTP requests to Hugo on port 1313
• Set appropriate X-Forwarded-* headers if needed

If using Caddy, Traefik, or another reverse proxy: Consult your proxy's documentation for SSL configuration. Most modern proxies automatically handle SSL with Let's Encrypt.

Important: Ensure your reverse proxy forwards requests to http://<lxc-internal-ip>:1313 (or localhost:1313 if proxy runs on same container). The domain dustin.coffee must resolve to your reverse proxy's public IP.

Step 5: Automation Script

Create a deployment script deploy.sh in the repository root:

#!/bin/bash
# deploy.sh - update site and restart Hugo server

set -e

cd /srv/www/dustin.coffee

echo "Pulling latest changes from git..."
git pull

echo "Updating theme submodule..."
git submodule update --init --recursive

echo "Restarting Hugo server..."
sudo systemctl restart hugo-dustin

echo "Deployment completed at $(date)"

Make it executable:

chmod +x deploy.sh

Now after SSH-ing into the container, you can run ./deploy.sh to update the site.

Notes

• Update the baseURL in hugo.toml if your domain changes.
• The site uses the hello-friend-ng theme as a git submodule.
• Blog posts are stored in content/posts/ as markdown files.
• To add new blog posts, create markdown files in content/posts/ on your development machine, push to git, then run the deploy script on the container.

Troubleshooting

• If Hugo server fails to start, check logs: sudo journalctl -u hugo-dustin -f
• If Hugo fails to build, check Hugo version matches the one used in development.
• If blog post URLs are incorrect, verify permalinks configuration in hugo.toml.
• If reverse proxy shows 404, ensure Hugo server is running on port 1313 and reverse proxy forwards to correct port.

Updating

To update the site after making changes on your development machine:

1. Push changes to your git server
2. SSH into LXC container
3. Navigate to site directory: cd /srv/www/dustin.coffee
4. Run ./deploy.sh