Generally functional. Added upload script

2025-12-17 09:43:21 -04:00
parent c76f10491a
commit 59b09e7ac9
19 changed files with 2994 additions and 0 deletions
--- a/plans/deployment_plan.md
+++ b/plans/deployment_plan.md
@@ -0,0 +1,371 @@
+# Superball Thrower Deployment Plan
+
+## Overview
+
+This document provides a complete deployment plan for the Superball Thrower C implementation on your server (accessible via `sshlt`).
+
+## Deployment Architecture
+
+- **Binary Location**: `/usr/local/bin/super_ball_thrower/superball_thrower`
+- **Config Location**: `/usr/local/bin/super_ball_thrower/config.json`
+- **Service User**: `superball-thrower`
+- **Service Name**: `superball-thrower.service`
+- **Log Location**: `/var/log/superball-thrower/`
+
+## One-Time Server Setup
+
+### Step 1: Create setup_server.sh
+
+Create this file on your local machine:
+
+```bash
+#!/bin/bash
+# One-time server setup script for Superball Thrower
+# Run this on the server as root or with sudo
+
+set -e
+
+echo "=== Superball Thrower Server Setup ==="
+
+# Create user if it doesn't exist
+if ! id -u superball-thrower >/dev/null 2>&1; then
+    echo "Creating user superball-thrower..."
+    useradd -r -s /bin/bash -d /usr/local/bin/super_ball_thrower superball-thrower
+else
+    echo "User superball-thrower already exists"
+fi
+
+# Create directory structure
+echo "Creating directory structure..."
+mkdir -p /usr/local/bin/super_ball_thrower
+mkdir -p /var/log/superball-thrower
+
+# Set ownership
+echo "Setting ownership..."
+chown -R superball-thrower:superball-thrower /usr/local/bin/super_ball_thrower
+chown -R superball-thrower:superball-thrower /var/log/superball-thrower
+
+# Set permissions
+echo "Setting permissions..."
+chmod 755 /usr/local/bin/super_ball_thrower
+chmod 755 /var/log/superball-thrower
+
+echo ""
+echo "=== Setup Complete ==="
+echo ""
+echo "Next steps:"
+echo "1. Copy your config.json to /usr/local/bin/super_ball_thrower/"
+echo "2. Install the systemd service file"
+echo "3. Run the deploy_lt.sh script to build and deploy the binary"
+```
+
+### Step 2: Create superball-thrower.service
+
+Create this systemd service file:
+
+```ini
+[Unit]
+Description=Superball Thrower Daemon (C Implementation)
+Documentation=https://git.laantungir.net/laantungir/super_ball_thrower
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=superball-thrower
+Group=superball-thrower
+WorkingDirectory=/usr/local/bin/super_ball_thrower
+ExecStart=/usr/local/bin/super_ball_thrower/superball_thrower /usr/local/bin/super_ball_thrower/config.json
+Restart=always
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=superball-thrower
+
+# Security settings
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/log/superball-thrower /usr/local/bin/super_ball_thrower
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictRealtime=true
+RestrictSUIDSGID=true
+LockPersonality=true
+RestrictNamespaces=true
+SystemCallFilter=@system-service
+SystemCallErrorNumber=EPERM
+
+# Resource limits
+LimitNOFILE=65536
+LimitNPROC=4096
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### Step 3: Run Setup Commands
+
+Execute these commands on the server:
+
+```bash
+# SSH into the server
+sshlt
+
+# Copy the setup script to the server (or create it there)
+# Then run it:
+sudo bash setup_server.sh
+
+# Install the systemd service file
+sudo cp superball-thrower.service /etc/systemd/system/
+sudo chmod 644 /etc/systemd/system/superball-thrower.service
+sudo systemctl daemon-reload
+sudo systemctl enable superball-thrower
+
+# Copy your config.json to the deployment directory
+sudo cp config.json /usr/local/bin/super_ball_thrower/
+sudo chown superball-thrower:superball-thrower /usr/local/bin/super_ball_thrower/config.json
+sudo chmod 600 /usr/local/bin/super_ball_thrower/config.json
+```
+
+## Deployment Script
+
+### deploy_lt.sh
+
+Create this script in your project root:
+
+```bash
+#!/bin/bash
+# Deployment script for Superball Thrower to lt server
+# This script builds the binary locally and deploys it to the server
+
+set -e
+
+echo "=== Superball Thrower Deployment Script ==="
+
+# Configuration
+SERVER="sshlt"
+DEPLOY_DIR="/usr/local/bin/super_ball_thrower"
+BINARY_NAME="superball_thrower"
+SERVICE_NAME="superball-thrower"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Step 1: Clean previous build
+echo -e "${YELLOW}[1/6] Cleaning previous build...${NC}"
+make clean || true
+
+# Step 2: Build the project
+echo -e "${YELLOW}[2/6] Building superball_thrower...${NC}"
+make
+
+# Check if build was successful
+if [ ! -f "$BINARY_NAME" ]; then
+    echo -e "${RED}Error: Build failed - binary not found${NC}"
+    exit 1
+fi
+
+echo -e "${GREEN}Build successful!${NC}"
+
+# Step 3: Stop the service on the server
+echo -e "${YELLOW}[3/6] Stopping service on server...${NC}"
+ssh $SERVER "sudo systemctl stop $SERVICE_NAME" || echo "Service not running or doesn't exist yet"
+
+# Step 4: Deploy binary to server
+echo -e "${YELLOW}[4/6] Deploying binary to server...${NC}"
+scp $BINARY_NAME $SERVER:/tmp/$BINARY_NAME
+
+# Step 5: Move binary to final location with proper permissions
+echo -e "${YELLOW}[5/6] Installing binary...${NC}"
+ssh $SERVER "sudo mv /tmp/$BINARY_NAME $DEPLOY_DIR/$BINARY_NAME && \
+             sudo chown superball-thrower:superball-thrower $DEPLOY_DIR/$BINARY_NAME && \
+             sudo chmod 755 $DEPLOY_DIR/$BINARY_NAME"
+
+# Step 6: Restart the service
+echo -e "${YELLOW}[6/6] Starting service...${NC}"
+ssh $SERVER "sudo systemctl start $SERVICE_NAME"
+
+# Wait a moment for service to start
+sleep 2
+
+# Check service status
+echo ""
+echo -e "${YELLOW}Service Status:${NC}"
+ssh $SERVER "sudo systemctl status $SERVICE_NAME --no-pager" || true
+
+echo ""
+echo -e "${GREEN}=== Deployment Complete ===${NC}"
+echo ""
+echo "Useful commands:"
+echo "  View logs:    ssh $SERVER 'sudo journalctl -u $SERVICE_NAME -f'"
+echo "  Check status: ssh $SERVER 'sudo systemctl status $SERVICE_NAME'"
+echo "  Restart:      ssh $SERVER 'sudo systemctl restart $SERVICE_NAME'"
+echo "  Stop:         ssh $SERVER 'sudo systemctl stop $SERVICE_NAME'"
+```
+
+## Deployment Workflow
+
+### Initial Deployment
+
+1. **Prepare the server** (one-time):
+   ```bash
+   # Create and run setup_server.sh on the server
+   sshlt
+   # Run the setup commands from Step 3 above
+   ```
+
+2. **Deploy the application**:
+   ```bash
+   # From your local project directory
+   chmod +x deploy_lt.sh
+   ./deploy_lt.sh
+   ```
+
+### Subsequent Deployments
+
+After making code changes:
+
+```bash
+# Just run the deployment script
+./deploy_lt.sh
+```
+
+The script will:
+- Build the binary locally
+- Stop the service
+- Deploy the new binary
+- Restart the service
+- Show the service status
+
+## Monitoring and Maintenance
+
+### View Logs
+
+```bash
+# Real-time logs
+ssh sshlt 'sudo journalctl -u superball-thrower -f'
+
+# Last 100 lines
+ssh sshlt 'sudo journalctl -u superball-thrower -n 100'
+
+# Logs since boot
+ssh sshlt 'sudo journalctl -u superball-thrower -b'
+```
+
+### Service Management
+
+```bash
+# Check status
+ssh sshlt 'sudo systemctl status superball-thrower'
+
+# Restart service
+ssh sshlt 'sudo systemctl restart superball-thrower'
+
+# Stop service
+ssh sshlt 'sudo systemctl stop superball-thrower'
+
+# Start service
+ssh sshlt 'sudo systemctl start superball-thrower'
+
+# Disable service (prevent auto-start)
+ssh sshlt 'sudo systemctl disable superball-thrower'
+
+# Enable service (auto-start on boot)
+ssh sshlt 'sudo systemctl enable superball-thrower'
+```
+
+### Update Configuration
+
+```bash
+# Edit config on server
+ssh sshlt 'sudo nano /usr/local/bin/super_ball_thrower/config.json'
+
+# Or copy from local
+scp config.json sshlt:/tmp/config.json
+ssh sshlt 'sudo mv /tmp/config.json /usr/local/bin/super_ball_thrower/config.json && \
+           sudo chown superball-thrower:superball-thrower /usr/local/bin/super_ball_thrower/config.json && \
+           sudo chmod 600 /usr/local/bin/super_ball_thrower/config.json'
+
+# Restart to apply changes
+ssh sshlt 'sudo systemctl restart superball-thrower'
+```
+
+## Troubleshooting
+
+### Service Won't Start
+
+```bash
+# Check detailed status
+ssh sshlt 'sudo systemctl status superball-thrower -l'
+
+# Check recent logs
+ssh sshlt 'sudo journalctl -u superball-thrower -n 50'
+
+# Test binary manually
+ssh sshlt 'sudo -u superball-thrower /usr/local/bin/super_ball_thrower/superball_thrower /usr/local/bin/super_ball_thrower/config.json'
+```
+
+### Permission Issues
+
+```bash
+# Fix ownership
+ssh sshlt 'sudo chown -R superball-thrower:superball-thrower /usr/local/bin/super_ball_thrower'
+
+# Fix permissions
+ssh sshlt 'sudo chmod 755 /usr/local/bin/super_ball_thrower && \
+           sudo chmod 755 /usr/local/bin/super_ball_thrower/superball_thrower && \
+           sudo chmod 600 /usr/local/bin/super_ball_thrower/config.json'
+```
+
+### Build Issues
+
+```bash
+# Clean and rebuild
+make distclean
+make
+
+# Check dependencies
+cd nostr_core_lib && ./build.sh --nips=1,6,44
+```
+
+## Security Considerations
+
+1. **Config File**: Contains private key - ensure it's only readable by superball-thrower user (chmod 600)
+2. **Service User**: Runs as non-root user with restricted permissions
+3. **Systemd Hardening**: Service file includes security restrictions
+4. **Log Access**: Only root and superball-thrower can read logs
+
+## Backup and Recovery
+
+### Backup Configuration
+
+```bash
+# Backup config from server
+scp sshlt:/usr/local/bin/super_ball_thrower/config.json ./config.backup.json
+```
+
+### Restore Configuration
+
+```bash
+# Restore config to server
+scp ./config.backup.json sshlt:/tmp/config.json
+ssh sshlt 'sudo mv /tmp/config.json /usr/local/bin/super_ball_thrower/config.json && \
+           sudo chown superball-thrower:superball-thrower /usr/local/bin/super_ball_thrower/config.json && \
+           sudo chmod 600 /usr/local/bin/super_ball_thrower/config.json && \
+           sudo systemctl restart superball-thrower'
+```
+
+## Next Steps
+
+After reviewing this plan:
+
+1. Switch to Code mode to create the actual script files
+2. Run the one-time setup on the server
+3. Test the deployment script
+4. Monitor the service to ensure it's running correctly