Features

| | | |---|---| | 🖥️ Web UI Dashboard | Monitor projects, deployments, and logs from your browser | | 🔄 GitHub Webhooks | Push to a branch and let VPS Deployer handle the rest | | 📧 Email Notifications | Get notified on deployment success or failure via SMTP | | ⚙️ Custom Build Commands | Define per-project command sequences (build, migrate, restart) | | 🔐 Per-Project Env Vars | Manage .env files through the UI | | 🪶 Lightweight | Single SQLite database, no external services required | | 🚀 CLI-Driven | Configure with one command, manage everything from the web | | 🔒 No Root Required | Runs entirely as a user-level systemd service |

Prerequisites

• Linux with systemd (user-level services)
• Node.js >= 20
• npm or pnpm

Quick Start

1. Install

npm install -g vps-deployer

2. One-Time Setup

Enable user-level systemd services to persist after logout:

loginctl enable-linger $USER

3. Configure

vps-deployer config -w /opt/vps-deployer -p 3000 -s your-super-secret-session-key

This creates the user-level systemd service file, database, and reference configs, then exits.

| Flag | Description | |------|-------------| | -w, --working-dir | Directory where projects and data will be stored | | -p, --port | Port for the web UI and API (1024–50000) | | -s, --session-key | Secret key for session encryption (min 6 characters) |

4. Start the Service

vps-deployer start

This enables and starts the systemd service. The terminal is freed immediately.

5. Open the Web UI

Navigate to http://<your-server-ip>:3000 and register your account.

6. Create a Project

1. Go to Projects → Create
2. Enter your GitHub repo URL and branch name
3. Add build/deploy commands (e.g., npm install, npm run build, pm2 restart app)
4. Save — your unique webhook URL and secret will be displayed

7. Configure the Webhook

Copy the webhook URL and secret from the project details page, then add them to your GitHub repo:

Settings → Webhooks → Add webhook → Paste URL → Set Content type to application/json → Paste Secret

8. Deploy

Push to your configured branch. VPS Deployer will receive the webhook, run your commands, and notify you via email.

Important: VPS Deployer does not automatically pull your repository on webhook receipt. You must explicitly add a git pull (or git clone) command as the first step in your project's command list. For example:

1. git pull origin main
2. npm install
3. npm run build

CLI Commands

| Command | Description | |---------|-------------| | vps-deployer config -w <dir> -p <port> -s <key> | Generate systemd service file, database, and configs | | vps-deployer start | Enable and start the user-level systemd service | | vps-deployer dev -w <dir> -p <port> -s <key> | Run in development mode (foreground, no systemd) | | vps-deployer uninstall | Stop, disable, and remove the systemd service |

Screenshots

Dashboard with project stats and recent deployments

Project configuration with commands and environment variables

Real-time deployment log output

Project Structure

When you run vps-deployer config, it creates the following structure in your working directory:

/opt/vps-deployer/
├── vps-deployer.db            # SQLite database
├── caddy.config               # Generated reverse proxy config
├── nginx.config               # Generated reverse proxy config
├── vps-deployer.log           # Application log file
└── <project-id>/              # Per-project workspace
    ├── .env                   # Environment variables
    └── ...                    # Cloned repository files

The systemd service file is created at ~/.config/systemd/user/vps-deployer.service.

Documentation

| Document | Description | |----------|-------------| | Quick Start | Step-by-step walkthrough from install to first deployment | | CLI Reference | All commands, flags, validation rules, and examples | | Webhook Setup | Configure GitHub webhooks for auto-deployment | | Email Setup | Configure SMTP for deployment notifications | | Architecture | System design, database schema, and deployment flow | | Database Schema | Full table definitions | | Privileged Commands | Configure sudoers for commands like pm2, docker, systemctl |

Managing the Service

# Start
vps-deployer start

# Status
systemctl --user status vps-deployer

# Logs
journalctl --user -u vps-deployer -f

# Stop
systemctl --user stop vps-deployer

# Remove entirely
vps-deployer uninstall

Security

• Runs as a user-level systemd service — no root required
• The web UI is protected by session-based authentication (login/register)
• Rate limiting is applied on auth endpoints (40 req/min per IP)
• Every webhook is verified using HMAC-SHA256 with a per-project secret
• Dangerous commands (rm -rf /, shutdown, reboot, mkfs, fork bombs) are blocked
• Use a strong, unique session key (-s flag)
• Keep the working directory restricted to the tool only

License

MIT — see LICENSE for details.