JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 11
  • Score
    100M100P100Q95632F
  • License MIT

A lightweight, self-hosted continuous deployment (CD) system with a built-in web UI — manages projects on your VPS, accepts GitHub webhooks for automatic deployments, and sends real-time email notifications on deployment events

Package Exports

  • vps-deployer
  • vps-deployer/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (vps-deployer) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

VPS Deployer Logo

VPS Deployer

Deployment made easy.

A lightweight, self-hosted continuous deployment (CD) system with a built-in web UI — manages projects on your VPS, accepts GitHub webhooks for automatic deployments, and sends real-time email notifications on deployment events.

npm version Node.js version License Platform

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

Dashboard with project stats and recent deployments

Project Details

Project configuration with commands and environment variables

Deployment Logs

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.