306 lines
6.8 KiB
Markdown
306 lines
6.8 KiB
Markdown
# 🚀 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
|
|
├── 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:
|
|
|
|
```
|
|
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.
|
|
|
|
```
|
|
#!/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
|
|
|
|
```
|
|
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 -D
|
|
# 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
|
|
/var/www/your-site/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
|
|
|
|
Restrict access to the site directory:
|
|
```
|
|
chmod 750 /var/www/your-site
|
|
chmod 750 /var/www/your-site/deploy.sh
|
|
```
|
|
Regularly update Hugo and nak:
|
|
```
|
|
# Check for updates
|
|
hugo version
|
|
nak --version
|
|
```
|
|
✅ Quick Start Checklist
|
|
|