Installation

Prerequisites

Before you begin, make sure your VPS meets these requirements:

Check your versions:

node --version   # should be 18 or higher
npm --version

Install VPS Deployer globally via npm:

npm install -g vps-deployer

Verify the installation:

vps-deployer --version

By default, systemd user services stop when you log out. Enable lingering so your service persists:

loginctl enable-linger $USER

This is a one-time setup. Without it, your deployments would stop every time you disconnect from SSH.

Run the config command to generate your systemd service file, database, and reference configs:

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

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

The command exits immediately after setup — it does not start the server.

vps-deployer start

This enables and starts the user-level systemd service. Your terminal is freed immediately — the process runs in the background.

Verify it’s running:

systemctl --user status vps-deployer

Open your browser and navigate to:

http://<your-server-ip>:3000

You’ll be prompted to register an account. Only one user can register — the first one wins.

If you want to run VPS Deployer in the foreground (useful for testing or development), use the dev command instead:

vps-deployer dev -w /opt/vps-deployer -p 3000 -s your-secret-key

This skips systemd setup and runs the Express server directly in your terminal. Press Ctrl+C to stop.