Initial commit: TFGrid Economics documentation site

- Based on working minting_plan repository
- Configured for threefold.info/economics deployment
- Added ops documentation for server deployment
- Updated baseUrl and URL configuration

ops/server-deployment.md

@@ -0,0 +1,421 @@
+# 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