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://raw.githubusercontent.com/dineshkorukonda/VersionGate/main/install.sh -o /tmp/versiongate-install.sh && sudo bash /tmp/versiongate-install.sh

The installer downloads from the GitHub repository over HTTPS and runs only after the download succeeds.

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

curl -fsSL https://raw.githubusercontent.com/dineshkorukonda/VersionGate/main/install.sh -o /tmp/versiongate-install.sh && sudo env DOMAIN=vg.example.com bash /tmp/versiongate-install.sh

Replace vg.example.com with your own domain.

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.

Domain set, dashboard says working, browser does not open it

That is usually DNS on the client, hairpin NAT when curling the public IP from the VPS, or three nginx files claiming the same hostname. See Domain troubleshooting.

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