🚀 Deployment Guide: Hugo + Nostr Site

Overview

This guide covers deploying your Hugo site that fetches content from Nostr relays using nak. The system runs on a cron job that automatically updates content every 30 minutes. Architecture

Nostr Relays → nak → JSON files → Hugo → Static HTML → Web Server

📦 Prerequisites

1. Install Hugo

Hugo is Static Site Generator. It should be available in your packet manager.

2. Intall nak

Download nak binary from https://github.com/fiatjaf/nak/releases/latest and put it in your path (the dirty way). Note that the example bellow downloads a version that migh be outdated at the time you are reading this.

Example for Linux AMD64

wget https://github.com/fiatjaf/nak/releases/download/v0.20.2/nak-v0.20.2-linux-amd64
chmod +x nak-linux-amd64
sudo mv nak-linux-amd64 /usr/local/bin/nak
nak --version  # Verify installation

3. Install jq (for JSON processing)

This should be present in your system already, but who knows... It is definitely available from your packet manager.

🗂️ Directory Structure

/var/www/your-site/
├── .git/                    # Git repository
├── hugo.toml              # Hugo configuration
├── data/                    # JSON data from Nostr
│   ├── longform/
│   ├── music/
│   ├── pictures/
│   ├── videos/
│   └── profile/
├── fetch-and-convert.sh     # Data fetching script
├── deploy.sh               # Deployment script
├── themes/
│   └── one-pager/
└── public/                  # Built site (rsynced to webroot)

📝 Deployment Scripts

First make a copy of the default files:

cp example.fetch-and-convert.sh fetch-and-convert.sh
cp example.deploy.sh deploy.sh
cp example.hugo.toml hugo.toml

1. fetch-and-convert.sh

This script fetches data from Nostr and converts it to JSON for Hugo.

You need to cusomize the top of the file yourself:

#!/bin/bash
# fetch-and-convert.sh

# Configuration
PUBKEY="your_pubkey_here" <---- enter your pubkey
RELAY="wss://relay.damus.io" <---- enter your principal relay
DATA_DIR="data" <--- leave as is, useful if you are using a different SSG

...

2. deploy.sh

This script handles the full deployment process. You can do this more elegantly, but yeah... this is what i got. Same here, customize the top of the file to match your setup

#!/bin/sh

# Configuration
SITE_DIR="/path/to/your-cloned-git"
WEBROOT="/probably/var/www/html"
LOG_FILE="$HOME/nostr-site-deploy.log"

...

3. Make scripts executable

chmod +x fetch-and-convert.sh
chmod +x deploy.sh

⏰ Cron Job Setup

Add to crontab (runs every 30 minutes)

Edit crontab

crontab -e

Add this line:

*/30 * * * * /path/to/your-cloned-git/deploy.sh

Alternative: Different intervals

# Every 15 minutes
*/15 * * * * /path/to/your-cloned-git/deploy.sh

# Every hour
0 * * * * /path/to/your-cloned-git/deploy.sh

# Twice a day (at 6am and 6pm)
0 6,18 * * * /path/to/your-cloned-git/deploy.sh

# Every 5 minutes (for testing)
*/5 * * * * /path/to/your-cloned-git/deploy.sh

🔧 Configuration

Hugo Configuration (hugo.toml) has some fallback values you might want to edit. These will take effect if something goes wrong with nostr data at fetch time.

baseURL = "https://your-domain.com"
locale = "en-us"
title = "Your Site"
theme = "one-pager"
disableKinds = ["sitemap", "taxonomy", "term"]

[params]
  sitename = "Your Site"
  description = "Your site description"
  headerImage = "/path/to/fallback/headerimage.jpg"
[permalinks]
  page = "/:contentbasename/"

📊 Monitoring & Debugging

Verify the site was updated

# Check the build time in the footer
curl -s https://your-domain.com | grep "Last updated"

View the status of the cron job

# Check if cron is running
systemctl status cron
# or
systemctl status crond

# View cron logs
grep CRON /var/log/syslog

🛠️ Manual Deployment

To manually trigger a deployment:

cd /path/to/your-cloned-git
./deploy.sh

To test fetching data without full deployment:

cd /path/to/your-cloned-git
./fetch-and-convert.sh
hugo server 
# Visit http://localhost:1313 to preview

🔍 Troubleshooting

Common Issues

1. Hugo build fails

# Check the error
hugo --verbose

# Clear cache
hugo --cleanDestinationDir

# Check your data files
ls -la data/*/*.json

2. nak fetch fails

# Test nak manually
nak req -k 0 -p YOUR_PUBKEY wss://relay.damus.io | head -5

# Check relay connectivity
nc -zv relay.damus.io 443

# Try a different relay
nak req -k 0 -p YOUR_PUBKEY wss://nos.lol

3. Rsync permissions issues

# Check permissions
ls -la /var/www/html

# Fix ownership
sudo chown -R www-data:www-data /var/www/html

4. Cron job not running

# Check cron syntax
crontab -l

# Check the cron log
grep CRON /var/log/syslog

# Test the script manually
/path/to/your/clonedgit/deploy.sh

5. Empty data files

# Check if data was fetched
cat data/profile/profile.json | jq '.[0]'

# Check file size
ls -lh data/*/*.json

📈 Performance Tips

• Use --minify in Hugo build (already in deploy.sh)

• Enable gzip compression in your web server

• Enable browser caching for CSS/JS (configured in Nginx/Apache)

• Use --gc in Hugo to garbage collect unused resources

• Consider using rsync --delete to remove old files

🔐 Security Tips

Regularly update Hugo and nak:

# Check for updates
hugo version
nak --version