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:

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