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

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

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

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

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

Add the following content:

```bash
#!/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:
```bash
export PATH="/usr/local/bin:/usr/bin:/bin:$PATH"
```

Make the script executable:

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

### 3.2 Create the zinit Service Definition

```bash
nano /etc/zinit/tfgrid-economics.yaml
```

Add the following content:

```yaml
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:

```bash
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:

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

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

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

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

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

```bash
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:

```bash
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:

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

```bash
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:

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

```bash
zinit restart tfgrid-economics
zinit restart caddy
```

### Caddy Not Serving the Site

Verify Caddy configuration:

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

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

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

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

```bash
# Check firewall status
ufw status

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

## Service Management Summary

**Commands for daily operations:**

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