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

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

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

```bash
nano Caddyfile
```

Add this line:
```
import economics.caddy
```

### 4.2 Create Economics Caddy Config

Create the dedicated configuration file:

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

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

### 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 /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:

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

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