--- name: vps-deploy description: "Deploy a full-stack app to any VPS from zero to production in one command. Handles SSH hardening, firewall, Docker, Nginx reverse proxy, SSL certificates, and health verification. Works with any stack (Node.js, Python, Go, Next.js) and any VPS provider (Hostinger, DigitalOcean, Hetzner, Linode, Vultr). Use when the user says 'deploy to VPS', 'set up my server', 'deploy to production', 'configure my VPS', or needs to go from a bare Ubuntu/Debian server to a running production app." --- # VPS Deploy Deploy any application to any VPS — from bare server to production with SSL — in one session. ## When to Use - User has a VPS (Ubuntu/Debian) and wants to deploy an application - User says "deploy to VPS", "set up my server", "go to production" - User has a running app locally and wants it live on a server - User needs SSL, Nginx, Docker setup on a VPS ## When NOT to Use - Deploying to Vercel, Netlify, or other managed platforms (use their CLIs) - Deploying to Kubernetes (use `/k8s-deploy` if it exists) - The user just wants to push code (use `git push`) ## Prerequisites - SSH access to a VPS (IP address + root or sudo credentials) - A domain pointed to the VPS IP (for SSL — can skip SSL if no domain) - The app must have a Dockerfile or be deployable via Docker ## Execution Flow ### Phase 1: Gather Information Ask the user for (skip what you can detect): 1. **VPS IP address** and **SSH credentials** (root password or key path) 2. **Domain name** (optional — needed for SSL) 3. **Application type** — detect from the current directory if possible: - Look for `package.json` (Node.js/Next.js) - Look for `requirements.txt` / `pyproject.toml` (Python) - Look for `go.mod` (Go) - Look for `Dockerfile` (any) 4. **Port** the app runs on (detect from Dockerfile EXPOSE, or ask) 5. **Environment variables** needed (check `.env.local`, `.env.example`) 6. **Database requirements** (Postgres, MySQL, Redis, MongoDB — detect from dependencies) ### Phase 2: Server Setup (SSH into VPS) Run these via `ssh root@` commands. Chain with `&&` for safety. #### 2a. System Update ```bash apt update && apt upgrade -y ``` #### 2b. Create Deploy User ```bash adduser --disabled-password --gecos "" deploy usermod -aG sudo docker deploy echo "deploy ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers.d/deploy ``` #### 2c. SSH Hardening ```bash # Copy root's authorized_keys to deploy user mkdir -p /home/deploy/.ssh cp ~/.ssh/authorized_keys /home/deploy/.ssh/ 2>/dev/null || true chown -R deploy:deploy /home/deploy/.ssh chmod 700 /home/deploy/.ssh chmod 600 /home/deploy/.ssh/authorized_keys 2>/dev/null || true # Harden SSH config sed -i 's/#\?PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config sed -i 's/#\?PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config sed -i 's/#\?PubkeyAuthentication.*/PubkeyAuthentication yes/' /etc/ssh/sshd_config systemctl restart sshd ``` **CRITICAL:** Before disabling root login, verify the deploy user can SSH in. Test in a separate connection. If the user doesn't have SSH keys set up, help them first. #### 2d. Firewall (UFW) ```bash apt install -y ufw ufw default deny incoming ufw default allow outgoing ufw allow 22/tcp # SSH ufw allow 80/tcp # HTTP ufw allow 443/tcp # HTTPS ufw --force enable ``` #### 2e. Install Docker ```bash curl -fsSL https://get.docker.com | sh usermod -aG docker deploy ``` #### 2f. Install Docker Compose (v2) ```bash apt install -y docker-compose-plugin # Verify docker compose version ``` ### Phase 3: Application Deployment #### 3a. Generate Dockerfile (if none exists) Detect the stack and generate an appropriate multi-stage Dockerfile: **Node.js / Next.js:** ```dockerfile FROM node:22-alpine AS deps WORKDIR /app COPY package*.json ./ RUN npm ci --omit=dev FROM node:22-alpine AS builder WORKDIR /app COPY --from=deps /app/node_modules ./node_modules COPY . . RUN npm run build FROM node:22-alpine AS runner WORKDIR /app ENV NODE_ENV=production COPY --from=builder /app/.next/standalone ./ COPY --from=builder /app/.next/static ./.next/static COPY --from=builder /app/public ./public EXPOSE 3000 CMD ["node", "server.js"] ``` **Python (FastAPI/Flask):** ```dockerfile FROM python:3.13-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] ``` Adapt based on what you detect in the project. #### 3b. Generate docker-compose.yml Generate a **production-grade** compose file. Include: ```yaml services: app: build: . restart: unless-stopped ports: - "127.0.0.1:${APP_PORT:-3000}:${APP_PORT:-3000}" env_file: .env healthcheck: test: ["CMD", "curl", "-f", "http://localhost:${APP_PORT:-3000}/"] interval: 30s timeout: 10s retries: 3 start_period: 40s deploy: resources: limits: memory: 512M cpus: '1.0' logging: driver: json-file options: max-size: "10m" max-file: "3" # Add database services based on detection: # postgres: # image: postgres:16-alpine # restart: unless-stopped # volumes: # - pgdata:/var/lib/postgresql/data # environment: # POSTGRES_DB: ${DB_NAME:-app} # POSTGRES_USER: ${DB_USER:-app} # POSTGRES_PASSWORD: ${DB_PASSWORD} # healthcheck: # test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-app}"] # interval: 10s # timeout: 5s # retries: 5 # volumes: # pgdata: ``` Key rules: - **Always** bind app port to `127.0.0.1` (Nginx handles external traffic) - **Always** include health checks - **Always** include resource limits - **Always** include logging limits - **Always** use `restart: unless-stopped` - **Never** expose database ports to the host #### 3c. Transfer Files to VPS ```bash # Create app directory ssh deploy@ "mkdir -p ~/apps/" # Copy project files (exclude node_modules, .git, etc.) rsync -avz --exclude='node_modules' --exclude='.git' --exclude='.next' \ ./ deploy@:~/apps// ``` #### 3d. Build and Start ```bash ssh deploy@ "cd ~/apps/ && docker compose up -d --build" ``` ### Phase 4: Nginx Reverse Proxy ```bash apt install -y nginx # Generate site config cat > /etc/nginx/sites-available/ << 'EOF' server { listen 80; server_name ; location / { proxy_pass http://127.0.0.1:; 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; proxy_read_timeout 86400; } } EOF ln -sf /etc/nginx/sites-available/ /etc/nginx/sites-enabled/ rm -f /etc/nginx/sites-enabled/default nginx -t && systemctl reload nginx ``` ### Phase 5: SSL Certificate (Let's Encrypt) Skip if no domain provided. ```bash apt install -y certbot python3-certbot-nginx certbot --nginx -d --non-interactive --agree-tos -m # Auto-renewal is configured automatically by certbot ``` ### Phase 6: Verification Run these checks and report results: ```bash # Check Docker containers are running docker compose ps # Check health status docker inspect --format='{{.State.Health.Status}}' # Check Nginx is serving curl -sI https:// | head -5 # Check SSL certificate echo | openssl s_client -servername -connect :443 2>/dev/null | openssl x509 -noout -dates ``` Report to the user: - Container status (running/healthy) - HTTP response code - SSL expiry date - URL to visit ## Safety Rules - **NEVER** disable the firewall without asking - **NEVER** expose database ports to the internet - **ALWAYS** verify SSH access with the deploy user BEFORE disabling root login - **ALWAYS** back up existing Nginx configs before overwriting - **ALWAYS** run `nginx -t` before reloading Nginx - **ALWAYS** ask before running destructive commands (rm, drop, etc.) - If anything fails, stop and tell the user what went wrong. Don't chain workarounds. ## Troubleshooting - **Port already in use:** `lsof -i :` to find what's using it - **Docker build fails:** Check Dockerfile, show build logs - **SSL fails:** Verify domain DNS points to VPS IP (`dig `) - **App crashes:** `docker compose logs -f` to show logs - **Can't SSH as deploy user:** Don't disable root login yet, fix keys first ## Post-Deploy Checklist Tell the user to: 1. Set up monitoring (suggest Uptime Kuma) 2. Configure automated backups for database volumes 3. Set up log rotation (already configured in compose) 4. Consider a CI/CD pipeline (suggest `/ci-gen` skill) 5. Add the domain to their DNS if not done

VPS Deploy

Description

Latest Changes

Install VPS Deploy with One Click