Networking

VersionGate manages an Nginx upstream file and a dedicated Docker network. Traffic switching is a config rewrite plus reload — never a restart.

Ports and slots

Each environment reserves two host ports: basePort (blue) and basePort + 1 (green). Inside the container your app listens on appPort; Docker maps it to the slot's host port.

Nginx upstream switching

upstream myapp {
    server 127.0.0.1:3101;   # rewritten by VersionGate on every switch
}

After a health-checked deploy, VersionGate rewrites the upstream port and runs nginx -s reload. Existing connections drain gracefully; new requests hit the new container.

Docker network

docker network create versiongate-net

All deployed containers join versiongate-net (configurable via DOCKER_NETWORK), so services can reach each other by container name.

Project custom domains (production)

Each project can attach one production hostname (for example app.example.com). VersionGate writes dedicated nginx files under /etc/nginx/conf.d/ and never overwrites the dashboard vhost in upstream.conf or versiongate.conf.

# upstream — rewritten on every blue/green switch
/etc/nginx/conf.d/vg-app-myapp.upstream.conf

# server — one file per hostname (Certbot-safe)
/etc/nginx/conf.d/vg-app-myapp-app-example-com.conf

Attach from the project page or via POST /api/v1/projects/:id/domains. Point DNS A/AAAA at this server, then run POST .../domains/:domainId/ssl to issue TLS with Certbot (CERTBOT_EMAIL in .env). Until a production deploy is ACTIVE, the upstream uses a down marker and the hostname returns 502/503.

Domains & HTTPS (dashboard)

Settings → Dashboard URL lets you set PUBLIC_DOMAIN and provision certificates via Certbot. Preflight validates DNS resolution, certbot availability, and CERTBOT_EMAIL before attempting issuance.

Webhook endpoints

The official VersionGate GitHub App sends webhooks to https://versiongate.tech/api/webhooks/github. The public relay looks up your installation and forwards the event to {PUBLIC_URL}/api/webhooks/github/relay on your VPS (verified with GITHUB_STATE_SECRET). Direct {PUBLIC_URL}/api/webhooks/github remains available for local testing. Legacy per-project webhooks (/api/v1/webhooks/:secret) continue to work without the App.