# 🚀 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
```bash
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
├── config.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

### 1. fetch-and-convert.sh (Already exists)

First make a copy of the default files:

```bash
cp exemple.fetch-and-convert.sh fetch-and-convert.sh
cp exemple.deploy.sh deploy.sh
```

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

You need to cusomize this to yourself:

```bash
#!/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

# Clean up old JSON files (optional)
# rm -f data/*/*.json

# Define kind mappings
declare -A KINDS
KINDS[0]="profile/profile"
KINDS[30023]="longform/blog"
KINDS[36787]="music/tracks"
KINDS[20]="pictures/photos"
KINDS[22]="videos/videos"

# Fetch each kind
for kind in "${!KINDS[@]}"; do
    output="${KINDS[$kind]}"
    echo "Fetching kind $kind..."

    # Create directory if it doesn't exist
    mkdir -p "$DATA_DIR/$(dirname "$output")"

    # Fetch and convert to JSON
    nak req -k "$kind" -p "$PUBKEY" "$RELAY" | jq -s '.' > "$DATA_DIR/$output.json"

    echo "Saved to $DATA_DIR/$output.json"
done

echo "All data fetched and converted!"
```

### 2. deploy.sh

This script handles the full deployment process. You can do this more elegantly, but yeah... this is what i got.

```bash
#!/bin/sh

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

date '+%Y-%m-%d %H:%M:%S' > $LOG_FILE

cd $SITE_DIR
/usr/bin/git pull >> $LOG_FILE
/usr/bin/bash fetch-and-convert.sh >> $LOG_FILE
/snap/bin/hugo --cleanDestinationDir >> $LOG_FILE

# Optional and potentially dangerous: the generator will creates a random file name (fingerprint) for css and js to be picked up when you do changes to it. If you don't remove them, over time your directory will bloat. A new file is only created if there are changes.
# This can be dangerous because if you set the webroot wrong, you're going to nuke stuff you wasn't supposed to.
#/usr/bin/rm $WEBROOT/css/*
#/usr/bin/rm $WEBROOT/js/*

/usr/bin/rsync -av $SITE_DIR $WEBROOT/ >> $LOG_FILE

```

### 3. Make scripts executable

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

## ⏰ Cron Job Setup

Add to crontab (runs every 30 minutes)

# Edit crontab
```bash
crontab -e
```

# Add this line:
```bash
*/30 * * * * /path/to/your-cloned-git/deploy.sh
```

Alternative: Different intervals

```bash
# 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.

```toml
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

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

View the status of the cron job
```bash
# 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:

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

To test fetching data without full deployment:
```bash
cd /path/to/your-cloned-git
./fetch-and-convert.sh
hugo server -D
# Visit http://localhost:1313 to preview
```

## 🔍 Troubleshooting
Common Issues

### 1. Hugo build fails
```bash
# Check the error
hugo --verbose

# Clear cache
hugo --cleanDestinationDir

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

### 2. nak fetch fails

```bash
# 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
```bash
# Check permissions
ls -la /var/www/html

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

### 4. Cron job not running
```bash
# Check cron syntax
crontab -l

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

# Test the script manually
/var/www/your-site/deploy.sh
```

### 5. Empty data files
```bash
# 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

Restrict access to the site directory:
```bash
chmod 750 /var/www/your-site
chmod 750 /var/www/your-site/deploy.sh
```
Regularly update Hugo and nak:
```bash
# Check for updates
hugo version
nak --version
```