Droplet Tools

Central repository for shared deployment scripts and workflows across all Adaptive Edge projects.

Purpose

This repository contains reusable scripts and documentation that ensure consistent deployment practices across all projects running on the Adaptive Edge droplet.

Key principle: Production is always the source of truth.

What's Included

1. CLAUDE_CODE_INSTRUCTIONS.md

Generic instructions that Claude Code (or any AI assistant) should follow when working on projects deployed to the droplet.

Covers:

• Production-first workflow
• Pre-deployment checks
• Apache configuration management
• Emergency recovery procedures
• Git workflow for hotfixes

2. scripts/check-production-before-deploy.sh

Reusable script that checks production server for uncommitted changes before deployment.

Features:

• Works with any project (configurable via environment variables)
• Blocks deployment if production has uncommitted changes
• Provides clear instructions for resolving conflicts
• Can be integrated into GitHub Actions or run manually

How to Use in Your Projects

Quick Setup

Add this to any project to get the production safeguards:

cd your-project

# Add as a git submodule
git submodule add https://github.com/natcrypto/droplet-tools.git .droplet-tools

# Symlink the instructions to your project root
ln -s .droplet-tools/CLAUDE_CODE_INSTRUCTIONS.md CLAUDE_CODE_INSTRUCTIONS.md

# Symlink scripts
mkdir -p scripts
ln -s ../.droplet-tools/scripts/check-production-before-deploy.sh scripts/check-production-before-deploy.sh

# Commit the submodule
git add .gitmodules .droplet-tools CLAUDE_CODE_INSTRUCTIONS.md scripts/
git commit -m "Add droplet-tools for production safeguards"
git push

Alternative: Direct Download

If you prefer not to use submodules:

cd your-project

# Download the files
curl -o CLAUDE_CODE_INSTRUCTIONS.md https://raw.githubusercontent.com/natcrypto/droplet-tools/main/CLAUDE_CODE_INSTRUCTIONS.md

mkdir -p scripts
curl -o scripts/check-production-before-deploy.sh https://raw.githubusercontent.com/natcrypto/droplet-tools/main/scripts/check-production-before-deploy.sh
chmod +x scripts/check-production-before-deploy.sh

git add CLAUDE_CODE_INSTRUCTIONS.md scripts/
git commit -m "Add production safeguards from droplet-tools"
git push

GitHub Actions Integration

Add this step BEFORE your build in .github/workflows/deploy.yml:

- name: Checkout submodules
  run: git submodule update --init --recursive

- name: Check production sync
  env:
    PROJECT_NAME: your-project-name  # e.g., "powercanvas", "loci", etc.
    SSH_DEPLOY_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
  run: |
    mkdir -p ~/.ssh
    echo "$SSH_DEPLOY_KEY" > ~/.ssh/deploy_key
    chmod 600 ~/.ssh/deploy_key
    ssh-keyscan -H adaptiveedge.uk >> ~/.ssh/known_hosts

    echo "🔍 Checking production for uncommitted changes..."
    ./scripts/check-production-before-deploy.sh

Using the Script Manually

# Set your project name
export PROJECT_NAME=your-project-name

# Run the check
./scripts/check-production-before-deploy.sh

Environment variables:

• PROJECT_NAME (required): Name of your project
• SSH_KEY (optional): Path to SSH key (default: ~/.ssh/nathan_droplet_key)
• SSH_HOST (optional): Server hostname (default: adaptiveedge.uk)
• SSH_USER (optional): SSH user (default: root)
• DEPLOY_PATH (optional): Deployment path (default: /var/www/$PROJECT_NAME)

For Claude Code / AI Assistants

When working on any project that uses these tools:

1. Always read CLAUDE_CODE_INSTRUCTIONS.md first
2. Never deploy without checking production
3. If production has changes, commit them to git FIRST
4. Then proceed with your work

The instructions file contains detailed workflows for:

• Safe deployments
• Production hotfixes
• Apache configuration changes
• Emergency recovery

Updating All Projects

When you improve the workflow:

1. Update this repo (make changes and push)

2. All projects using submodules get updates automatically:

   cd your-project
   git submodule update --remote .droplet-tools
   git commit -am "Update droplet-tools"
   git push

3. Projects using direct downloads need manual update:

   cd your-project
   curl -o CLAUDE_CODE_INSTRUCTIONS.md https://raw.githubusercontent.com/natcrypto/droplet-tools/main/CLAUDE_CODE_INSTRUCTIONS.md
   curl -o scripts/check-production-before-deploy.sh https://raw.githubusercontent.com/natcrypto/droplet-tools/main/scripts/check-production-before-deploy.sh
   git commit -am "Update production safeguards"
   git push

Project-Specific Documentation

While the scripts and workflows are centralized here, each project should still have its own PRODUCTION_WORKFLOW.md documenting:

• Project-specific paths
• PM2 process names
• Apache configuration details
• Custom validation scripts
• Port numbers
• Special deployment steps

The central tools provide the HOW (workflow and scripts), while project-specific docs provide the WHAT (paths, names, configurations).

Server Details

Adaptive Edge Droplet:

• Host: adaptiveedge.uk (178.62.68.64)
• SSH Key: ~/.ssh/nathan_droplet_key
• Projects Path: /var/www/PROJECT_NAME/
• Process Manager: PM2
• Web Server: Apache2

Why This Matters

The Problem This Solves:

1. ✅ You fix a bug on production
2. ❌ You forget to commit it
3. ❌ You deploy new code from git
4. ❌ Deployment overwrites your fix
5. ❌ Bug reappears

The Solution:

These tools prevent deployments when production has uncommitted changes, ensuring you never lose work.

Scripts Reference

check-production-before-deploy.sh

Purpose: Check if production server has uncommitted changes before deployment

Usage:

export PROJECT_NAME=my-project
./scripts/check-production-before-deploy.sh

Exit Codes:

• 0 - Production is clean (safe to deploy)
• 1 - Production has uncommitted changes (STOP deployment)

Checks:

• ✅ Can connect to production server
• ✅ Project directory exists
• ✅ Git repository is clean
• ✅ No uncommitted changes

Output:

• Clear success/failure messages
• List of uncommitted files (if any)
• Instructions for resolving conflicts

Contributing

If you improve the workflow or add new scripts:

1. Make changes in this repo
2. Test with at least one project
3. Commit and push
4. Update all your projects to get the latest version

Support

If you encounter issues:

1. Check that environment variables are set correctly
2. Verify SSH key permissions: chmod 600 ~/.ssh/nathan_droplet_key
3. Test SSH connection: ssh -i ~/.ssh/nathan_droplet_key root@adaptiveedge.uk
4. Check the project's PRODUCTION_WORKFLOW.md for project-specific details

License

MIT - Feel free to use these tools in your own projects.

Changelog

2026-01-19 - Initial Release

• Created central repository for shared tools
• Added production sync check script
• Added Claude Code instructions
• Documented setup and usage