Docs/Quick Start

Quick Start

Get VersionGate running on a fresh VM (or existing server) in under 3 minutes with Nginx reverse proxying, PM2 systemd boot persistence, and optional automatic Certbot TLS.

Option A: Universal One-Line Host Installer (Recommended)

On a clean VPS (Ubuntu, Debian, RHEL) with nothing installed, run this single command to provision Docker Engine, Nginx reverse proxy, Node 20, Bun, PM2 boot persistence, and start VersionGate:

terminal

curl -fsSL https://versiongate.tech/install.sh | sudo bash

Automatic TLS / Custom Domain Setup

If you have a domain pointing to your VM's public IP address, pass the DOMAIN environment variable to provision free Let's Encrypt SSL/TLS certificates automatically via Certbot:

terminal

DOMAIN=versiongate.tech curl -fsSL https://versiongate.tech/install.sh | sudo bash

The installer configures Nginx to proxy incoming traffic on ports 80 and 443 to the local VersionGate API and dashboard on 127.0.0.1:9090.

Azure Network Security Group (NSG) Configuration

Azure firewalls traffic at the subscription level using Network Security Groups (NSGs). OS firewall rules (ufw/firewalld) alone will not allow external traffic until Azure NSG inbound rules are created.

If the Azure CLI (az) is installed and authenticated, the installer auto-configures these rules for you. Otherwise, enable ports 80, 443, and 9090 (TCP) in the Azure Portal (VM -> Networking -> Add inbound port rule) or run:

terminal

az network nsg rule create \
  --resource-group <YOUR_RESOURCE_GROUP> \
  --nsg-name <YOUR_NSG_NAME> \
  --name Allow-VersionGate-Inbound \
  --priority 1010 \
  --direction Inbound \
  --access Allow \
  --protocol Tcp \
  --destination-port-ranges 80 443 9090

Option B: Existing Server (Manual Clone)

If you already have Docker and Node/Bun installed on your server and want to launch manually:

terminal

git clone https://github.com/dineshkorukonda/VersionGate.git
cd VersionGate
bun install
bun run agent      # Audit system prerequisites & copy-paste fix commands
bun run dev        # Start engine on port 9090 in Setup Mode

Complete In-UI Setup Wizard

Once started, open your browser directly at:

browser

http://<your-vm-ip>/   (or https://<your-domain>/)

Enter your PostgreSQL connection string, JWT secrets, and administrator account details. The Setup Wizard tests your database connection, applies Drizzle ORM schema migrations, writes .env, and launches the full control-plane dashboard.

Setup Mode (Zero Crash-Looping)

VersionGate binds to port 9090 immediately behind Nginx without requiring PostgreSQL pre-configuration. You never get locked out of the setup wizard due to database connection errors.

Architecture Deployment & Promotion