super_ball_thrower/plans/deployment_plan.md

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:

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

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

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

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

   # Create and run setup_server.sh on the server
   sshlt
   # Run the setup commands from Step 3 above
   

2. Deploy the application:

   # From your local project directory
   chmod +x deploy_lt.sh
   ./deploy_lt.sh
   

Subsequent Deployments

After making code changes:

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Backup config from server
scp sshlt:/usr/local/bin/super_ball_thrower/config.json ./config.backup.json

Restore Configuration

# 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