Skip to content

Deployment Workflows

Reference for our standard deployment patterns

VPS Projects

Standard Flow

# Initial setup
git clone {{repo_url}}
cd {{project_dir}}

# Deploy script handles:
# - Backup
# - Build
# - Git checks
# - Staging deploy
# - Production deploy
./deploy.sh --auto

Configuration Template

# deploy-config.yml
production:
  server: root@{{server_ip}}
  path: /var/www/{{domain}}/
  backup: /var/www/backups/{{project}}/

staging:
  server: root@{{server_ip}}
  path: /var/www/staging.{{domain}}/

Common Patterns

  • Automatic backup before deploy
  • Staging verification step
  • Production confirmation
  • Rollback capability

Shared Hosting

DirectAdmin Flow

# Uses DirectAdmin API for deployment
./da-deploy.sh --site={{domain}} --type={{template}}

Configuration

# da-config.yml
api:
  host: {{da_host}}
  key: {{da_key}}
  user: {{da_user}}

templates:
  wordpress: wp-standard
  static: html-basic

Limitations

  • Limited SSH access
  • API-based deployment
  • Template-driven setup

Custom Components

BTCPay Server

# Initial setup
./btcpay-setup.sh --domain={{domain}} --lightning

# Updates
./btcpay-update.sh --version={{version}}

Monitoring Setup

# Standard monitoring
./monitor-setup.sh --site={{domain}} --type=standard

# With extra checks
./monitor-setup.sh --site={{domain}} --type=enhanced

Development Flow

Local Setup

# Standard environment
./dev-setup.sh --project={{name}}

# With specific features
./dev-setup.sh --project={{name}} --features="ssl,db"

Testing

# Run standard tests
./test.sh

# With specific focus
./test.sh --type={{test_type}}

Reference Commands

Backup Management

# Create backup
./backup.sh --site={{domain}}

# List backups
./backup.sh --list

# Restore specific backup
./backup.sh --restore={{timestamp}}

SSL Management

# New certificate
./ssl-setup.sh --domain={{domain}}

# Renewal
./ssl-renew.sh --all

Database Operations

# Backup DB
./db-backup.sh --site={{domain}}

# Migration
./db-migrate.sh --from={{old}} --to={{new}}

Note: Replace all {{variables}} with actual values. Environment variables are loaded from .env files.

Deployment Workflow

This document describes the enhanced deployment process for the SatoshiHost documentation system.

🚀 Overview

Our deployment system combines build validation, automated git operations, and live deployment into a single, safe command.

✅ Enhanced Deploy Script Features

What It Does:

  1. Build Validation - Builds MkDocs first, stops if build fails
  2. Git Status Check - Detects and shows all changes
  3. Interactive Commit - Asks for commit message or auto-generates one
  4. Automated Git Operations - Commits documentation changes safely
  5. Backup Creation - Creates timestamped backup before deployment
  6. Staging Deployment - Deploys to staging environment first
  7. Production Confirmation - Requires explicit approval for production
  8. Automated Testing - Validates deployments with HTTP checks
  9. Automatic Rollback - Restores from backup if deployment fails

🛡️ Professional Safeguards

Enterprise-Grade Protection:

Our deployment system implements industry-standard safeguards commonly found in Fortune 500 environments:

Backup System

  • ✅ Automated backups created before every deployment
  • ✅ Timestamped archives with retention management (keeps last 5)
  • ✅ One-command rollback capability
  • ✅ Server-side backup storage for disaster recovery

Staging Environment

  • ✅ staging.satoshihost.dev - Identical production environment
  • ✅ Required testing before production deployment
  • ✅ Manual approval for production promotion
  • ✅ HTTP health checks validate deployment success

Deployment Validation

  • ✅ Build testing prevents broken deployments
  • ✅ Connectivity testing ensures server accessibility
  • ✅ Automatic rollback on failure detection
  • ✅ Status reporting for transparency

Why These Safeguards Matter:

Professional Credibility: - Shows we follow industry best practices - Demonstrates serious approach to quality - Builds confidence with potential developers/clients - Prevents "amateur hour" deployment disasters

Risk Mitigation: - Site downtime minimized through staging tests - Data loss prevented with automated backups - Bad deployments caught before affecting users - Quick recovery when issues do occur

Workflow with Safeguards:

1. Build & Test Locally ✅
2. Git Commit & Backup ✅
3. Deploy to Staging ✅
4. Test Staging Environment ✅
5. Manual Approval Required ⚠️
6. Deploy to Production ✅
7. Validate Production ✅
8. Auto-Rollback if Failed ✅

Safety Features:

  • ✅ Fail-fast: Script stops immediately if MkDocs build fails
  • ✅ Clean commits: Only commits documentation files (docs/, mkdocs.yml, *.md)
  • ✅ Visual feedback: Shows exactly what files have changed
  • ✅ Interactive control: You choose the commit message

🛠️ Usage

Basic Deployment:

./deploy.sh

What You'll See:

=== Enhanced Deploy Script ===
Building MkDocs site...
✅ Build successful!

=== Git Status Check ===
📝 Changes detected:
 M docs/some-file.md
 M mkdocs.yml
?? docs/new-file.md

Enter commit message (or press Enter for auto-message):

Commit Message Options:

Option 1: Custom Message 

Enter commit message: Add developer workflow documentation
✅ Committed: Add developer workflow documentation

Option 2: Auto-Generated 

Enter commit message: [press Enter]
Using auto-message: Auto-deploy: 2025-06-08 22:45
✅ Committed: Auto-deploy: 2025-06-08 22:45

🏗️ Workflow Benefits

Clean Development Environment

  • AI-managed changes: All modifications made through proper development tools
  • No dirty working directory: Changes are intentional and deployment-ready
  • Professional git history: Every deployment properly documented

Safe Deployment Process

  • Build validation first: Won't deploy broken documentation
  • Automated backup: Every change committed to git before deployment
  • Single command: Everything automated but still under your control

The "AI + Human" Approach

  • AI handles production: Clean, professional development environment
  • Human provides direction: Strategic decisions and commit messages
  • Separate experimentation: Use other systems for learning/testing

🔧 Technical Details

Files Included in Commits:

  • docs/ - All documentation content
  • mkdocs.yml - Navigation and configuration
  • *.md - Root-level markdown files

Deployment Target:

  • Live Site: https://satoshihost.dev
  • Server: 89.116.173.103
  • Path: /var/www/docs.directsponsor.org/

Build Process:

  1. Activate Python virtual environment
  2. Run mkdocs build with validation
  3. Copy favicon and manifest files
  4. Update HTML with comprehensive favicon links
  5. Deploy via rsync to live server

📋 Best Practices

Before Deployment:

  • Review changes shown in git status
  • Write descriptive commit messages for significant changes
  • Use auto-messages for minor updates

Commit Message Guidelines:

  • Major features: "Add developer opportunity showcase"
  • Content updates: "Update ROFLFaucet documentation"
  • Minor fixes: "Fix typos and formatting" or use auto-message
  • Configuration: "Update navigation structure"

SSH Deployment Scripts - Critical Best Practices:

⚠️ ALWAYS Include These in SSH-based Deployment Scripts:

#!/bin/bash
set -e  # Exit on any error
set -x  # Show all commands (for debugging)

# MANDATORY: Short connection timeouts
ssh -o ConnectTimeout=10 -o BatchMode=yes server "command"

# MANDATORY: Test connectivity first
echo "Testing SSH connection..."
ssh -o ConnectTimeout=5 server "echo 'Connection OK'" || {
    echo "❌ ERROR: Cannot connect to server"
    echo "Check: Server status, SSH service, network connectivity"
    exit 1
}

Why These Matter:

  • ConnectTimeout=10: Prevents scripts hanging indefinitely on connection issues
  • BatchMode=yes: Prevents password prompts that hang scripts
  • set -x: Shows exactly what commands are running (essential for debugging)
  • Connection test first: Fails fast with clear error message
  • Error handling: Provides actionable diagnostic information

Common SSH Deployment Failures:

  1. Server down/rebooted → Connection timeout
  2. SSH service stopped → Connection refused
  3. Network issues → Connection timeout
  4. SSH key problems → Authentication failure
  5. Firewall changes → Connection timeout

Script Hanging Symptoms:

  • ✅ Good: Quick error message with specific timeout
  • ❌ Bad: Script sits silently with no feedback
  • ❌ Bad: Waiting 2+ minutes for default SSH timeout

Deployment Script Template:

#!/bin/bash
set -e
set -x

SERVER="your-server"
TIMEOUT=10

echo "=== Deployment Starting ==="
echo "Target: $SERVER"

# Test connection with short timeout
echo "Testing connectivity..."
ssh -o ConnectTimeout=$TIMEOUT -o BatchMode=yes $SERVER "echo 'SSH OK'" || {
    echo "❌ Cannot connect to $SERVER"
    echo "Possible causes:"
    echo "  - Server is down (try reboot)"
    echo "  - SSH service stopped"
    echo "  - Network/firewall issues"
    echo "  - SSH key authentication failure"
    exit 1
}

# Proceed with deployment commands...
echo "✅ Connection verified, proceeding..."

Emergency Procedures:

  • Build fails: Script stops automatically, fix errors before retry
  • Deployment fails: Check server connectivity and permissions
  • SSH hangs: Check SSH service status, try server reboot
  • Git issues: Script handles most scenarios, manual intervention rarely needed

🚨 Deployment Recovery Procedures

Interrupted Long-Running Builds

Scenario: Compilation or build process interrupted (server reboot, network failure, etc.)

Symptoms: - Server takes unusually long to boot (filesystem cleanup) - Partial build artifacts left in directories - SSH connectivity issues after reboot

Recovery Steps: 

# 1. Test connectivity with timeout
ssh -o ConnectTimeout=10 server "echo 'Server responsive'"

# 2. Clean up interrupted build
ssh server "cd /path/to/project && rm -rf build-dir && git clean -fd"

# 3. Restart deployment from clean state
./deploy.sh --clean-start

Multi-Phase Deployment Strategy

Best Practice: Break complex deployments into resumable phases

# Phase 1: Environment setup (fast, rarely fails)
./deploy-phase1.sh  # Dependencies, users, directories

# Phase 2: Build/compilation (slow, may fail)
./deploy-phase2.sh  # Download, compile, install

# Phase 3: Configuration (fast, service setup)
./deploy-phase3.sh  # Config files, service start

Benefits: - ✅ Can resume from any phase - ✅ Faster recovery from failures - ✅ Clear progress indicators - ✅ Easier troubleshooting

Server Reclamation Procedures

For non-paying customers or server reallocation:

1. Server Audit Script

#!/bin/bash
# Create comprehensive server inventory
echo "=== Server Inventory Report ===" > server_inventory.txt
echo "Date: $(date)" >> server_inventory.txt
echo "Server: $(hostname)" >> server_inventory.txt
echo "" >> server_inventory.txt

# System info
echo "=== System Information ===" >> server_inventory.txt
uname -a >> server_inventory.txt
cat /etc/os-release >> server_inventory.txt
echo "" >> server_inventory.txt

# Running services
echo "=== Running Services ===" >> server_inventory.txt
systemctl list-units --type=service --state=running >> server_inventory.txt
echo "" >> server_inventory.txt

# Directory structure
echo "=== Directory Structure ===" >> server_inventory.txt
find /home /var/www /opt -maxdepth 3 -type d 2>/dev/null >> server_inventory.txt
echo "" >> server_inventory.txt

# Databases
echo "=== Database Information ===" >> server_inventory.txt
systemctl is-active mysql mariadb postgresql 2>/dev/null >> server_inventory.txt
ls -la /var/lib/mysql/ /var/lib/postgresql/ 2>/dev/null >> server_inventory.txt
echo "" >> server_inventory.txt

# Web content
echo "=== Web Content ===" >> server_inventory.txt
ls -la /var/www/ 2>/dev/null >> server_inventory.txt
echo "" >> server_inventory.txt

# Custom applications
echo "=== Custom Applications ===" >> server_inventory.txt
find /opt /usr/local -name "*" -type f -executable 2>/dev/null >> server_inventory.txt

2. Professional Documentation Process

# Generate inventory
./audit-server.sh

# Create backup if valuable data found
tar -czf server_backup_$(date +%Y%m%d).tar.gz /home /var/www /opt

# Send inventory to customer
mail -s "Server Contents Inventory" customer@email.com < server_inventory.txt

OS Selection Guidelines

For Blockchain/Compilation Projects

  • ✅ Ubuntu 22.04 LTS: Best balance of stability + modern build tools
  • ✅ Debian 12: Ultra-stable for production
  • ❌ Rocky/RHEL: Can be finicky with bleeding-edge development tools

For Web Applications

  • ✅ Ubuntu 22.04 LTS: Excellent package availability
  • ✅ Rocky Linux: Great for enterprise environments
  • ✅ Debian: Minimal, stable, reliable

For High-Security Applications

  • ✅ Rocky Linux: Enterprise-focused security
  • ✅ Debian: Minimal attack surface
  • ❌ Ubuntu: More packages = larger attack surface

🎯 Why This Works

Traditional Development vs Our Approach:

Traditional: - Manual build testing - Separate git operations - Deployment as afterthought - Risk of forgetting commits

Our Enhanced Workflow: - Automated validation - Build tested before any operations - Integrated git management - Never forget to commit - Single command deployment - Consistent, reliable process - Professional standards - Every change properly documented

This deployment workflow supports our philosophy of AI-managed production environments with human oversight and strategic direction.