vps-deploy

name	vps-deploy
description	Deploy applications to VPS servers with automatic runtime detection, reverse proxy setup, SSL, and rollback support. Trigger phrases: "deploy", "sunucuya gonder", "VPS'e kur", "push to server", "release to production"

VPS Deploy

Deploy any application to a VPS with Docker or bare metal, including reverse proxy, SSL, health checks, and rollback.

Overview

This skill handles the full deployment lifecycle:

1. Analyze the project to detect runtime and choose deploy method
2. Read or create deploy configuration
3. Set up reverse proxy (Nginx or Caddy)
4. Configure SSL certificates
5. Deploy the application (Docker or bare metal)
6. Verify deployment with health checks
7. Rollback if something goes wrong
8. Generate deploy.sh and update.sh scripts for one-click future deploys

Pre-Deploy Checklist

• Project analyzed — runtime and deploy method determined
• Config loaded from .deploy.yml or collected from user
• SSH connectivity verified
• Current version backed up to releases/
• Reverse proxy configured
• SSL certificate in place
• User confirmed deployment
• Deploy scripts (deploy.sh, update.sh) offered to user

---

Step 1: Project Analysis

Detect the project type and choose the deploy method.

Detection logic:

# Check for Dockerfile
if [ -f Dockerfile ] || [ -f docker-compose.yml ]; then
  METHOD="docker"
# Check for Node.js
elif [ -f package.json ]; then
  METHOD="bare"
  RUNTIME="node"
# Check for Python
elif [ -f requirements.txt ] || [ -f pyproject.toml ] || [ -f Pipfile ]; then
  METHOD="bare"
  RUNTIME="python"
# Check for Go
elif [ -f go.mod ]; then
  METHOD="bare"
  RUNTIME="go"
else
  # Ask the user
  METHOD="unknown"
fi

Rules:

• If method: auto in config, use detection logic above
• If method: docker, use Docker regardless of Dockerfile presence (create one if missing)
• If method: bare, use bare metal deploy with runtime-specific process manager
• If no runtime detected and method is auto, ask the user

---

Step 2: Configuration

Read .deploy.yml from the project root. If it does not exist, ask the user for each value.

Config format (.deploy.yml):

host: 192.168.1.100
user: deploy
ssh_key: ~/.ssh/id_rsa
app_port: 3000
health_check: /api/health
deploy_path: /var/www/myapp
method: auto  # auto | docker | bare
domain: myapp.example.com
ssl: true
reverse_proxy: auto  # auto | nginx | caddy

Field descriptions:

• host — VPS IP address or hostname (required)
• user — SSH username (required)
• ssh_key — path to SSH private key (default: ~/.ssh/id_rsa)
• app_port — port the application listens on (required)
• health_check — HTTP path for health verification (default: /)
• deploy_path — absolute path on server where app is deployed (required)
• method — deploy method: auto detects, docker forces Docker, bare forces bare metal
• domain — domain name for reverse proxy and SSL (optional, uses IP if not set)
• ssl — enable SSL certificate provisioning (default: true if domain is set)
• reverse_proxy — auto detects installed proxy, or force nginx / caddy

Verify SSH connectivity:

ssh -i $SSH_KEY -o ConnectTimeout=5 -o StrictHostKeyChecking=accept-new $USER@$HOST "echo 'SSH connection OK'"

---

Step 3: Reverse Proxy

Auto-detect which reverse proxy is installed on the server, then generate the appropriate config.

Detection:

# Check what's installed on the server
ssh -i $SSH_KEY $USER@$HOST "command -v caddy && echo 'CADDY' || (command -v nginx && echo 'NGINX' || echo 'NONE')"

Rules:

• If reverse_proxy: auto — use Caddy if installed, otherwise Nginx. Install Nginx if neither is found.
• If reverse_proxy: nginx — use Nginx, install if missing.
• If reverse_proxy: caddy — use Caddy, install if missing.

Nginx Config Template

# Write Nginx site config
ssh -i $SSH_KEY $USER@$HOST "cat > /etc/nginx/sites-available/$APP_NAME" << 'NGINX_CONF'
server {
    listen 80;
    server_name DOMAIN_PLACEHOLDER;

    location / {
        proxy_pass http://127.0.0.1:APP_PORT_PLACEHOLDER;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}
NGINX_CONF

# Enable the site
ssh -i $SSH_KEY $USER@$HOST "ln -sf /etc/nginx/sites-available/$APP_NAME /etc/nginx/sites-enabled/$APP_NAME"
ssh -i $SSH_KEY $USER@$HOST "nginx -t && systemctl reload nginx"

Caddy Config Template

# Write Caddyfile or append to existing
ssh -i $SSH_KEY $USER@$HOST "cat >> /etc/caddy/Caddyfile" << 'CADDY_CONF'
DOMAIN_PLACEHOLDER {
    reverse_proxy 127.0.0.1:APP_PORT_PLACEHOLDER
}
CADDY_CONF

# Reload Caddy
ssh -i $SSH_KEY $USER@$HOST "systemctl reload caddy"

Replace DOMAIN_PLACEHOLDER with the domain value and APP_PORT_PLACEHOLDER with app_port.

---

Step 4: SSL Certificates

Caddy (Automatic)

Caddy handles SSL automatically. No extra steps needed. When the domain is configured in the Caddyfile, Caddy obtains and renews Let's Encrypt certificates on its own.

Nginx (Certbot)

# Install certbot if not present
ssh -i $SSH_KEY $USER@$HOST "command -v certbot || (apt-get update && apt-get install -y certbot python3-certbot-nginx)"

# Obtain SSL certificate
ssh -i $SSH_KEY $USER@$HOST "certbot --nginx -d $DOMAIN --non-interactive --agree-tos -m admin@$DOMAIN"

# Verify auto-renewal is active
ssh -i $SSH_KEY $USER@$HOST "systemctl enable certbot.timer && systemctl start certbot.timer"

# Test renewal
ssh -i $SSH_KEY $USER@$HOST "certbot renew --dry-run"

Rules:

• Skip SSL if ssl: false or no domain is configured
• Never proceed with SSL for bare IP addresses
• Verify DNS resolves to the server IP before requesting a certificate

# Verify DNS before SSL
RESOLVED_IP=$(dig +short $DOMAIN)
if [ "$RESOLVED_IP" != "$HOST" ]; then
  echo "WARNING: $DOMAIN resolves to $RESOLVED_IP, not $HOST. SSL will fail."
  # Ask user whether to continue
fi

---

Step 5: Deploy

5a. Backup Current Version

Always backup before deploying.

# Create releases directory
ssh -i $SSH_KEY $USER@$HOST "mkdir -p $DEPLOY_PATH/releases"

# Backup current version with timestamp
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
ssh -i $SSH_KEY $USER@$HOST "
  if [ -d $DEPLOY_PATH/current ]; then
    cp -a $DEPLOY_PATH/current $DEPLOY_PATH/releases/$TIMESTAMP
    echo 'Backup created: releases/$TIMESTAMP'
  else
    echo 'No current version to backup (first deploy)'
  fi
"

# Prune old releases — keep only last 3
ssh -i $SSH_KEY $USER@$HOST "
  cd $DEPLOY_PATH/releases && ls -dt */ | tail -n +4 | xargs -r rm -rf
"

5b. Docker Deploy

# Build the Docker image locally
docker build -t $APP_NAME:latest .

# Save image to tar
docker save $APP_NAME:latest | gzip > /tmp/$APP_NAME.tar.gz

# Transfer to server
scp -i $SSH_KEY /tmp/$APP_NAME.tar.gz $USER@$HOST:/tmp/

# Load image and run on server
ssh -i $SSH_KEY $USER@$HOST "
  # Load the image
  docker load < /tmp/$APP_NAME.tar.gz

  # Stop existing container if running
  docker stop $APP_NAME 2>/dev/null || true
  docker rm $APP_NAME 2>/dev/null || true

  # Run the new container
  docker run -d \
    --name $APP_NAME \
    --restart unless-stopped \
    -p 127.0.0.1:$APP_PORT:$APP_PORT \
    $APP_NAME:latest

  # Clean up
  rm /tmp/$APP_NAME.tar.gz
"

# Clean up local tar
rm /tmp/$APP_NAME.tar.gz

5c. Bare Metal — Node.js with PM2

# Sync project files to server
rsync -avz --delete \
  --exclude node_modules \
  --exclude .git \
  --exclude .env.local \
  -e "ssh -i $SSH_KEY" \
  ./ $USER@$HOST:$DEPLOY_PATH/current/

# Install dependencies and start with PM2
ssh -i $SSH_KEY $USER@$HOST "
  cd $DEPLOY_PATH/current

  # Install dependencies
  npm ci --production

  # Install PM2 globally if not present
  command -v pm2 || npm install -g pm2

  # Detect start script
  START_SCRIPT=\$(node -e \"console.log(require('./package.json').scripts.start || 'node index.js')\")

  # Stop existing process if running
  pm2 stop $APP_NAME 2>/dev/null || true
  pm2 delete $APP_NAME 2>/dev/null || true

  # Start the application
  pm2 start ecosystem.config.js --name $APP_NAME 2>/dev/null || \
    pm2 start npm --name $APP_NAME -- start

  # Save PM2 process list and set up startup script
  pm2 save
  pm2 startup systemd -u $USER --hp /home/$USER 2>/dev/null || true
"

5d. Bare Metal — Python with systemd

# Sync project files to server
rsync -avz --delete \
  --exclude __pycache__ \
  --exclude .git \
  --exclude .venv \
  --exclude .env.local \
  -e "ssh -i $SSH_KEY" \
  ./ $USER@$HOST:$DEPLOY_PATH/current/

# Set up virtualenv and systemd service
ssh -i $SSH_KEY $USER@$HOST "
  cd $DEPLOY_PATH/current

  # Create/update virtualenv
  python3 -m venv venv
  ./venv/bin/pip install -r requirements.txt 2>/dev/null || ./venv/bin/pip install -e . 2>/dev/null

  # Detect the entry point
  if [ -f manage.py ]; then
    EXEC_CMD='$DEPLOY_PATH/current/venv/bin/gunicorn --bind 127.0.0.1:$APP_PORT --workers 3 config.wsgi:application'
  elif [ -f app.py ] || [ -f main.py ]; then
    ENTRY=\$([ -f app.py ] && echo app.py || echo main.py)
    EXEC_CMD='$DEPLOY_PATH/current/venv/bin/python \$ENTRY'
  fi

  # Write systemd service file
  sudo tee /etc/systemd/system/$APP_NAME.service > /dev/null << SERVICE
[Unit]
Description=$APP_NAME
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=$DEPLOY_PATH/current
ExecStart=\$EXEC_CMD
Restart=always
RestartSec=5
Environment=PORT=$APP_PORT

[Install]
WantedBy=multi-user.target
SERVICE

  # Enable and restart the service
  sudo systemctl daemon-reload
  sudo systemctl enable $APP_NAME
  sudo systemctl restart $APP_NAME
"

5e. Bare Metal — Go with systemd

# Build the Go binary locally (cross-compile for Linux)
GOOS=linux GOARCH=amd64 go build -o /tmp/$APP_NAME .

# Transfer binary to server
scp -i $SSH_KEY /tmp/$APP_NAME $USER@$HOST:$DEPLOY_PATH/current/$APP_NAME

# Set up systemd service
ssh -i $SSH_KEY $USER@$HOST "
  chmod +x $DEPLOY_PATH/current/$APP_NAME

  # Write systemd service file
  sudo tee /etc/systemd/system/$APP_NAME.service > /dev/null << SERVICE
[Unit]
Description=$APP_NAME
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=$DEPLOY_PATH/current
ExecStart=$DEPLOY_PATH/current/$APP_NAME
Restart=always
RestartSec=5
Environment=PORT=$APP_PORT

[Install]
WantedBy=multi-user.target
SERVICE

  # Enable and restart the service
  sudo systemctl daemon-reload
  sudo systemctl enable $APP_NAME
  sudo systemctl restart $APP_NAME
"

---

Step 6: Health Check

Run immediately after deploy. Wait up to 30 seconds for the service to become healthy.

# HTTP health check with retries
HEALTH_URL="http://127.0.0.1:$APP_PORT$HEALTH_CHECK"
MAX_RETRIES=6
RETRY_DELAY=5

ssh -i $SSH_KEY $USER@$HOST "
  for i in \$(seq 1 $MAX_RETRIES); do
    STATUS=\$(curl -s -o /dev/null -w '%{http_code}' $HEALTH_URL 2>/dev/null)
    if [ \"\$STATUS\" = '200' ]; then
      echo 'Health check PASSED (HTTP 200)'
      exit 0
    fi
    echo \"Attempt \$i/$MAX_RETRIES: HTTP \$STATUS — retrying in ${RETRY_DELAY}s...\"
    sleep $RETRY_DELAY
  done
  echo 'Health check FAILED after $MAX_RETRIES attempts'
  exit 1
"

Process verification:

# Verify the process is running
ssh -i $SSH_KEY $USER@$HOST "
  if [ '$METHOD' = 'docker' ]; then
    docker ps --filter name=$APP_NAME --format '{{.Status}}'
  else
    # Check systemd or PM2
    systemctl is-active $APP_NAME 2>/dev/null || pm2 show $APP_NAME 2>/dev/null | grep status
  fi
"

If health check fails, trigger rollback automatically.

---

Step 7: Rollback

Restore the most recent backup from releases/ and restart the service.

# Find the latest release backup
LATEST_RELEASE=$(ssh -i $SSH_KEY $USER@$HOST "ls -dt $DEPLOY_PATH/releases/*/ 2>/dev/null | head -1")

if [ -z "$LATEST_RELEASE" ]; then
  echo "ERROR: No release backups found. Cannot rollback."
  exit 1
fi

echo "Rolling back to: $LATEST_RELEASE"

ssh -i $SSH_KEY $USER@$HOST "
  # Restore the backup
  rm -rf $DEPLOY_PATH/current
  cp -a $LATEST_RELEASE $DEPLOY_PATH/current

  # Restart the service
  if [ '$METHOD' = 'docker' ]; then
    # For Docker: the backup contains the image tag info
    docker stop $APP_NAME 2>/dev/null || true
    docker rm $APP_NAME 2>/dev/null || true
    # Re-run from the previous image (tagged during backup)
    docker run -d --name $APP_NAME --restart unless-stopped \
      -p 127.0.0.1:$APP_PORT:$APP_PORT \
      $APP_NAME:previous
  else
    # For bare metal: restart the service
    sudo systemctl restart $APP_NAME 2>/dev/null || pm2 restart $APP_NAME 2>/dev/null
  fi

  echo 'Rollback complete.'
"

# Run health check after rollback
# (repeat Step 6)

---

Step 8: Generate Deploy Scripts

After a successful deployment, generate project-specific deploy.sh and update.sh scripts so the user can deploy and update with a single command.

Always ask the user: "Deploy başarılı. Gelecekte tek komutla deploy/update yapabilmeniz için deploy.sh ve update.sh scriptlerini oluşturmamı ister misiniz?"

Why Project-Specific?

Generic scripts cannot cover all cases. Every project has different:

• Build steps (npm build, go build, pip install, docker compose, custom Makefile)
• Runtime configurations (environment variables, config files, .env handling)
• Process managers (PM2 with ecosystem.config.js, systemd with custom unit, Docker with specific flags)
• Dependency installation (npm ci, pip install, bundle install, go mod download)
• File exclusions (project-specific directories like uploads/, data/, logs/)
• Pre/post deploy hooks (database migrations, cache clearing, asset compilation)

DO NOT use a generic template. Analyze the actual project and generate scripts tailored to it.

How to Generate

1. Analyze the project — read package.json scripts, Dockerfile, Makefile, existing CI/CD configs, docker-compose.yml, .env.example, etc.
2. Identify the exact build/start commands this project uses
3. Check for project-specific needs:
   • Does it need a build step? (npm run build, go build -o app, asset compilation)
   • Does it have database migrations? (add migration step to deploy)
   • Does it use environment variables? (handle .env file sync)
   • Does it have a custom start command? (check package.json start, Procfile, etc.)
   • Does it use docker-compose? (use docker compose up -d instead of plain docker)
   • Does it have pre/post deploy hooks? (test suites, seed scripts)
4. Generate two scripts customized to this project

deploy.sh — First-Time Full Setup + Deploy

Must include (adapted to the project):

• Config loading from .deploy.yml
• SSH verification
• Reverse proxy setup (Nginx or Caddy — based on what was used in Step 3)
• SSL setup (based on what was used in Step 4)
• Backup current version to releases/ with timestamp
• Project-specific build commands
• Transfer and deployment (Docker or bare metal — based on Step 1 detection)
• Project-specific dependency installation
• Project-specific process start/restart
• Health check with retry loop
• Automatic rollback on failure
• Release pruning (keep last 3)

update.sh — Quick Code Update + Restart

Must include (adapted to the project):

• Config loading from .deploy.yml
• Backup current version
• Sync code to server (rsync or docker build+transfer)
• Project-specific dependency installation (only if needed)
• Project-specific build step (if applicable)
• Process restart
• Health check with retry loop
• Automatic rollback on failure

Script Structure Template

Use this as a structural guide, but fill in project-specific commands:

#!/usr/bin/env bash
set -euo pipefail

# ============================================
# [deploy.sh | update.sh] — [Full setup | Quick update]
# Generated for: [project-name]
# Project type: [Node.js/Python/Go/Docker/etc.]
# Deploy method: [docker | pm2 | systemd]
# ============================================

# --- Config (read from .deploy.yml) ---
# [Parse .deploy.yml and set variables]

# --- SSH verification ---
# --- Backup current version ---
# --- [PROJECT-SPECIFIC: Build step] ---
# --- [PROJECT-SPECIFIC: Transfer files] ---
# --- [PROJECT-SPECIFIC: Install dependencies] ---
# --- [PROJECT-SPECIFIC: Run migrations if needed] ---
# --- [PROJECT-SPECIFIC: Start/restart process] ---
# --- Health check ---
# --- Rollback on failure ---

Script Generation Rules

• Always set executable permission: chmod +x deploy.sh update.sh
• Add to .gitignore consideration: Ask the user if .deploy.yml should be in .gitignore (it may contain server credentials)
• Never overwrite existing scripts without user confirmation
• If the user already has deploy.sh or update.sh, show a diff and ask before replacing
• Scripts must read config from .deploy.yml — no hardcoded server credentials
• Include comments explaining each project-specific decision so the user can modify later
• Test the scripts mentally — trace through each command and verify it would work for this specific project

---

Step 9: Safety Rules

These rules are mandatory and must never be skipped:

1. Never deploy without user confirmation. Always show the deploy plan (method, target host, domain, app port) and wait for explicit approval before executing.

2. Always backup before deploy. The current version must be copied to releases/ with a timestamp before any deployment begins. If backup fails, abort the deploy.

3. Always run health check after deploy. Every deployment must be followed by an HTTP health check and process verification. If the health check fails, trigger automatic rollback.

4. Keep the last 3 releases. After a successful deploy, prune the releases/ directory to keep only the 3 most recent backups. Never delete all backups.

5. Never deploy to production without knowing the target. Always confirm the host, deploy path, and domain with the user. Double-check if the host looks like a production server.

6. Always verify SSH access first. Test the SSH connection before starting any deploy operation. Fail fast if the connection cannot be established.

7. Never expose app ports directly. The application should bind to 127.0.0.1 and be accessible only through the reverse proxy.

8. SSL is required when a domain is configured. If domain is set and ssl is not explicitly false, always set up SSL.