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

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:

cd /root/code/github/despiegk/env_web/ourworld/ovh1_web_current/caddy/

4.1 Add Import to Main Caddyfile

Edit the main Caddyfile and add the import statement:

nano Caddyfile

Add this line:

import economics.caddy

4.2 Create Economics Caddy Config

Create the dedicated configuration file:

nano economics.caddy

Add the following content:

# TFGrid Economics
threefold.info {
    handle_path /economics* {
        reverse_proxy localhost:9997 {
            header_up Host {host}
            header_up X-Real-IP {remote}
            header_up X-Forwarded-Proto {scheme}
        }
    }
}

Notes:

• The handle_path directive strips /economics from the path before forwarding to port 9997
• If you already have other services using threefold.info, add the handle_path block to the existing configuration
• Multiple handle_path blocks can coexist in the same domain config

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

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 /root/code/github/despiegk/env_web/ourworld/ovh1_web_current/caddy/Caddyfile

# Check Caddy logs
zinit log caddy

# Restart Caddy
zinit restart caddy

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, you can configure Caddy to serve the static files directly.

Edit economics.caddy:

threefold.info {
    handle_path /economics* {
        root * /root/code/git.ourworld.tf/tfgrid/tfgrid-economics/build
        file_server
        try_files {path} {path}/ /index.html
        encode gzip
    }
}

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