docs_tfgrid_economics/ops/server-deployment.md

Server Deployment Guide for TFGrid Economics

Production deployment guide for hosting the TFGrid Economics documentation site at threefold.info/economics.

Repository: https://git.ourworld.tf/tfgrid/tfgrid-economics

Overview

• URL: https://threefold.info/economics/
• Service Manager: zinit
• Web Server: Caddy (reverse proxy)
• Port: 9997
• Branch: main

The repository is pre-configured with baseUrl: '/economics/' in docusaurus.config.js.

Quick Reference

# Update site
cd /root/code/git.ourworld.tf/tfgrid/tfgrid-economics
git pull && zinit restart tfgrid-economics

# View logs
zinit log tfgrid-economics

# Check status
zinit list | grep tfgrid-economics
ss -tuln | grep 9997

Prerequisites

• Linux server with:
  • Git installed
  • Node.js 18+ installed
  • Caddy web server installed
  • zinit service manager installed
  • Root or sudo access
• SSH access to the server (e.g., root@info.ourworld.tf)

Step 1: Clone the Repository

# Create directory structure
mkdir -p /root/code/git.ourworld.tf/tfgrid/
cd /root/code/git.ourworld.tf/tfgrid/

# Clone the repository
git clone https://git.ourworld.tf/tfgrid/tfgrid-economics
cd tfgrid-economics
git checkout main

Step 2: Build the Site

The repository is already configured with the correct base URL (/economics/) in docusaurus.config.js.

Build the static site files:

# Install dependencies
npm install

# Build the production site
npm run build

This creates a build/ directory with static HTML, CSS, and JavaScript files.

Step 3: Create a zinit Service

Create a zinit service to serve the built site:

3.1 Create the Service Script

mkdir -p /etc/zinit/cmds
nano /etc/zinit/cmds/tfgrid-economics.sh

Add the following content:

#!/bin/bash

# Load nvm (Node Version Manager)
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

cd /root/code/git.ourworld.tf/tfgrid/tfgrid-economics

# Pull latest changes
git checkout main
git pull

# Install dependencies and build
npm install
npm run build

# Serve the built site using a simple HTTP server
# npx serve is a lightweight static server
exec npx serve -s build -l 9997

Note: This script loads nvm before running npm commands. If you're not using nvm, replace the nvm lines with:

export PATH="/usr/local/bin:/usr/bin:/bin:$PATH"

Make the script executable:

chmod +x /etc/zinit/cmds/tfgrid-economics.sh

3.2 Create the zinit Service Definition

nano /etc/zinit/tfgrid-economics.yaml

Add the following content:

exec: "/bin/bash -c /etc/zinit/cmds/tfgrid-economics.sh"

Step 4: Configure Caddy

Navigate to your Caddy configuration directory (location may vary based on your setup).

4.1 Find the Existing threefold.info Configuration

First, locate which file contains the threefold.info domain block:

grep -l "threefold.info" *.caddy

In this setup, it's in info.caddy.

4.2 Add Economics Route to Existing Configuration

Edit the file containing the threefold.info block:

# Backup first
cp info.caddy info.caddy.backup

# Edit the file
nano info.caddy

Add the handle_path block at the beginning of the threefold.info block (before root and file_server):

info.ourworld.tf threefold.info info.i.threefold.me {
    # TFGrid Economics - MUST come before file_server
    handle_path /economics* {
        reverse_proxy localhost:9997 {
            header_up Host {host}
            header_up X-Real-IP {remote}
        }
    }
    
    # Default file server for other content
    root * /root/hero/www/info
    encode gzip
    file_server
}

Important Notes:

• The handle_path must come before file_server to take priority
• The handle_path directive strips /economics from the path before forwarding to port 9997
• Don't create a separate file with another threefold.info block - Caddy will try to provision SSL certs for invalid hostnames
• This approach works when threefold.info is already defined in an existing file

Step 5: Start Services with zinit

Monitor and start the service:

# Monitor the zinit service
zinit monitor tfgrid-economics

# Start the service
zinit start tfgrid-economics

# Restart Caddy to load new configuration
zinit restart caddy

Updating the Application

To update the site after making changes:

# Go to the repository directory
cd /root/code/git.ourworld.tf/tfgrid/tfgrid-economics

# Pull the latest changes
git checkout main
git pull

# Rebuild and restart
zinit restart tfgrid-economics

The service script will automatically rebuild the site when restarted.

Monitoring

Check the application status:

# Check if the service is running
zinit list | grep tfgrid-economics

# View application logs
zinit log tfgrid-economics

# Monitor logs in real-time
tail -f /var/log/zinit/tfgrid-economics.log

# Check port is listening
ss -tuln | grep 9997

Verification

After deployment, verify the site is accessible:

# Test locally on the server
curl http://localhost:9997

# Test via Caddy
curl https://threefold.info/economics/

Visit in your browser: https://threefold.info/economics/

Troubleshooting

Application Not Starting

Check for errors in the application logs:

zinit log tfgrid-economics

npm/npx Command Not Found

If zinit can't find npm, you need to add Node.js to the PATH in the script.

First, find where Node.js is installed:

which node
which npm
which npx

Common locations:

• /usr/local/bin/ (standard install)
• /usr/bin/ (system package manager)
• ~/.nvm/ (nvm installation)

Then update /etc/zinit/cmds/tfgrid-economics.sh with the correct PATH:

# For standard installation
export PATH="/usr/local/bin:/usr/bin:/bin:$PATH"

# For nvm installation
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Build Failures

Check if Node.js and dependencies are properly installed:

cd /root/code/git.ourworld.tf/tfgrid/tfgrid-economics
node --version  # Should be 18+
npm install
npm run build

Connection Refused

Make sure the application is running and listening on the correct port:

ss -tuln | grep 9997

Port Already in Use

If port 9997 is already in use, choose a different port:

1. Update the port in /etc/zinit/cmds/tfgrid-economics.sh
2. Update the port in the Caddy configuration
3. Restart both services

zinit restart tfgrid-economics
zinit restart caddy

Caddy Not Serving the Site

Verify Caddy configuration:

# Test Caddy configuration
caddy validate --config Caddyfile

# Check Caddy logs
zinit log caddy

# Restart Caddy
zinit restart caddy

Caddy SSL Certificate Errors for "handle_path"

If you see errors like Cannot issue for "handle_path": Domain name contains an invalid character, you've likely created a separate .caddy file with a domain block that should be merged into an existing file instead.

Problem: Creating a standalone file like:

threefold.info {
    handle_path /economics* {
        ...
    }
}

When threefold.info is already defined elsewhere, this causes Caddy to try provisioning certs incorrectly.

Solution: Add the handle_path block to the existing file that contains the threefold.info domain block.

Git Authentication Issues

If the repository requires authentication:

# Configure git credentials
git config --global credential.helper store

# Or use SSH instead of HTTPS
cd /root/code/git.ourworld.tf/tfgrid/
rm -rf tfgrid-economics
git clone git@git.ourworld.tf:tfgrid/tfgrid-economics.git
cd tfgrid-economics
git checkout main

Alternative: Direct Caddy File Server

Instead of using npx serve with zinit, you can configure Caddy to serve the static files directly.

Edit the file containing threefold.info (e.g., info.caddy):

info.ourworld.tf threefold.info info.i.threefold.me {
    # TFGrid Economics - Direct file serving
    handle_path /economics* {
        root * /root/code/git.ourworld.tf/tfgrid/tfgrid-economics/build
        try_files {path} {path}/ /index.html
        encode gzip
        file_server
    }
    
    # Default file server for other content
    root * /root/hero/www/info
    encode gzip
    file_server
}

Benefits:

• Simpler setup (no need for npx serve)
• Caddy handles compression and caching efficiently
• One less service to manage

With this approach, you don't need the zinit service - just rebuild when you update:

cd /root/code/git.ourworld.tf/tfgrid/tfgrid-economics
git checkout main
git pull
npm install
npm run build
# Caddy automatically serves the updated build/ directory

Optional update script (/usr/local/bin/update-tfgrid-economics.sh):

#!/bin/bash
cd /root/code/git.ourworld.tf/tfgrid/tfgrid-economics
git checkout main
git pull
npm install
npm run build
echo "TFGrid Economics updated successfully"

Security Considerations

File Permissions

Ensure proper file permissions:

# Set ownership
chown -R root:root /root/code/git.ourworld.tf/tfgrid/tfgrid-economics

# Set directory permissions
find /root/code/git.ourworld.tf/tfgrid/tfgrid-economics -type d -exec chmod 755 {} \;

# Set file permissions
find /root/code/git.ourworld.tf/tfgrid/tfgrid-economics -type f -exec chmod 644 {} \;

# Make zinit script executable
chmod +x /etc/zinit/cmds/tfgrid-economics.sh

HTTPS/SSL

Caddy automatically provisions SSL certificates via Let's Encrypt for your domain. Ensure:

• Your domain resolves to the server
• Ports 80 and 443 are open
• Caddy can write to its data directory

Firewall

Ensure required ports are open:

# Check firewall status
ufw status

# Open ports if needed
ufw allow 80/tcp
ufw allow 443/tcp

Service Management Summary

Commands for daily operations:

# Start service
zinit start tfgrid-economics

# Stop service
zinit stop tfgrid-economics

# Restart service (rebuilds site)
zinit restart tfgrid-economics

# Check status
zinit list | grep tfgrid-economics

# View logs
zinit log tfgrid-economics

# Monitor in real-time
zinit monitor tfgrid-economics

Links

• Repository: https://git.ourworld.tf/tfgrid/tfgrid-economics
• Live Site: https://threefold.info/economics/
• Server: info.ourworld.tf

Related Documentation

• For local development setup, see README.md in the repository
• For content updates and editing, see the repository documentation