vpn-deploy

name	vpn-deploy
description	Guided VPN deployment wizard. Use when user says 'deploy VPN', 'deploy my VPN', 'set up VPN', 'install VPN'. Also use when opening the project for the first time and user wants to get started.

VPN Deployment Wizard

Управляемый деплой VPN-инфраструктуры для начинающих пользователей. Каждый шаг проверяется перед переходом к следующему.

When to Use

Use when the user wants to deploy a VPN:

• "Deploy VPN", "deploy my VPN"
• "Set up VPN", "install VPN"
• "Help me get started"

The Iron Law

NO STEP WITHOUT VERIFICATION OF THE PREVIOUS STEP

Do not proceed to deployment if connectivity check failed. Do not claim success without running status check.

Workflow

Execute these phases IN ORDER. Do not skip phases.

Phase 1: Environment Setup

Goal: Ensure .env file exists and is correctly filled.

1. Check if .env file exists in project root
2. If NO:
   • Read .env.example to understand required fields
   • Ask user for VPS details (in Russian):
     • IP-адрес VPS (VPN_HOST)
     • SSH-порт (default 22, recommend 49152)
     • SSH-пользователь (default root)
     • SSH-ключ path OR пароль (VPN_SSH_KEY or VPN_SSH_PASS)
   • Create .env from .env.example with user's values
3. If YES:
   • Read .env and verify VPN_HOST is set (not placeholder <YOUR_VPS_IP>)
   • If placeholder values remain, ask user to fill them

Verification: .env exists AND VPN_HOST contains a real IP address.

Phase 2: Dependency Check

Goal: Ensure Python 3 and paramiko are available.

1. Run python --version or python3 --version
2. If Python not found: tell user to install Python 3
3. Run python -c "import paramiko; print(paramiko.__version__)"
4. If paramiko not found: run pip install paramiko scp

Verification: Both Python 3 and paramiko import successfully.

Phase 3: Connectivity Test

Goal: Verify SSH access to VPS.

1. Run python ssh_exec.py status
2. Interpret output:
   • Success: xray status shown, uptime visible -> proceed
   • "Connection refused": Port might be blocked. If port is 22, suggest trying 49152 (TSPU blocks port 22 to foreign IPs). Update .env and retry
   • "Authentication failed": Wrong password or SSH key. Ask user to verify credentials
   • "Connection timed out": VPS might be down or IP wrong. Ask user to verify VPS is running
   • "Host key verification failed": First connection to this server. Ask user to confirm the IP is correct, then suggest removing old known_hosts entry if IP was reused

Verification: ssh_exec.py status returns xray status or server info without errors.

Special case — fresh VPS (xray not installed yet): If SSH connects but xray is not found, that's EXPECTED for first-time deployment. Proceed to Phase 4.

Phase 4: Deployment

Goal: Deploy VPN infrastructure on the VPS.

1. Inform user: "Starting deployment. This takes 15-20 minutes. The script will install 3X-UI panel, create VLESS Reality connections, configure firewall and monitoring."
2. Run python ssh_exec.py deploy quick-rebuild.sh
3. Monitor output for:
   • VLESS URIs (lines starting with vless://) — SAVE ALL OF THEM
   • Error messages — if script fails, check the last error message
   • Credentials (panel URL, username, password) — note these for user
4. If deployment fails:
   • Read error output
   • Common issues: disk space, network timeout during package install, port conflict
   • Suggest: python ssh_exec.py restart then retry deployment

Verification: Script completes without errors AND outputs at least one VLESS URI.

Phase 5: Post-Deploy Verification

Goal: Confirm VPN is actually running.

1. Run python ssh_exec.py status
2. Verify:
   • xray process is "running"
   • At least one inbound is active
   • Server uptime is fresh (just deployed)
3. If xray is not running: python ssh_exec.py restart, then check again

Verification: ssh_exec.py status shows xray running with active inbounds.

Phase 6: Client Setup Instructions

Goal: Give user everything needed to connect.

Based on user's platform, provide:

Windows (v2rayN — recommended):

1. Present all VLESS URIs from deployment output
2. Point to client-configs/v2rayn-setup.md for detailed setup
3. Key points:
   • Import URI via clipboard
   • Enable TUN mode (critical — without it, DNS and UDP leak)
   • Select split routing preset "RUv1" (Russian sites bypass VPN)
   • Use sing-box core for best compatibility

iOS (Shadowrocket — recommended):

1. Present VLESS URIs
2. Point to docs/04-client-setup.md iOS section
3. Key: copy URI -> open Shadowrocket -> auto-imports

Android (v2rayNG):

1. Present VLESS URIs
2. Point to docs/04-client-setup.md Android section

Verification (user does this manually):

• Tell user: "After connecting, open 2ip.ru in your browser. It should show your VPS country (Sweden/Netherlands/etc), NOT Russia. For Russian sites (yandex.ru, vk.com), it should show Russia."

Communication Rules

• Communicate with user in Russian (per CLAUDE.md)
• Never display raw credentials or .env contents in chat output
• Present VLESS URIs clearly — user needs to copy them
• If something fails, explain in simple terms what happened and what to try next
• Do not overwhelm beginner with technical details — keep explanations concise