JumpGate

JumpGate

Lightweight, GitOps-driven Micro-PaaS for solo developers.

JumpGate is a single Go binary that turns any VPS into a Heroku-like deployment platform. Push to Git — JumpGate builds, deploys, and routes traffic with zero-downtime blue/green cutovers. No web dashboard, no Kubernetes, no bloat.

Architecture

                     ┌─────────────┐
  git push ─────────→│  GitHub/GitLab │
                     └──────┬──────┘
                            │ webhook (HMAC)
                     ┌──────▼──────┐
                     │  JumpGate    │
                     │  Daemon      │
                     │  (Go binary) │
                     └──┬───┬───┬──┘
                        │   │   │
              ┌─────────┘   │   └──────────┐
              ▼             ▼              ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │  Docker   │  │  SQLite  │  │  Traefik │
        │  Engine   │  │  (state) │  │  (proxy) │
        └──────────┘  └──────────┘  └─────┬────┘
                                          │
                        ┌─────────────────┘
                        ▼
              ┌──────────────────┐
              │  Your App        │
              │  Container(s)    │
              │  :80 / :443      │
              └──────────────────┘

How It Works

1. You push code to GitHub/GitLab
2. JumpGate receives the webhook (HMAC-verified, rate-limited)
3. Clones the repo at the specific commit hash into an isolated temp directory
4. Parses jumpgate.toml — your app's deployment manifest
5. Builds the Docker image, streaming logs to SQLite
6. Starts the new container with Traefik routing labels
7. Health-checks the new container (TCP port or HTTP endpoint)
8. Cuts over — marks new as Running, stops old container (blue/green)
9. Cleans up — old images pruned hourly

Quickstart

Prerequisites

• A Linux VPS (Ubuntu 22.04+ recommended)
• Docker Engine installed
• A domain pointed to your VPS
• Go 1.22+ (to build from source)

1. Install JumpGate

# One-line installer (Linux/macOS)
curl -sL https://github.com/VemorPhose/JumpGate/releases/latest/download/install.sh | bash

# Or build from source
git clone https://github.com/VemorPhose/JumpGate.git
cd JumpGate
go build -o jumpgate ./cmd/jumpgate/
sudo mv jumpgate /usr/local/bin/

2. Start Traefik (Ingress)

docker compose -f infra/docker-compose.traefik.yml up -d

Set the Let's Encrypt email:

export ACME_EMAIL="you@example.com"

3. Set Your Webhook Secret

export JUMPGATE_WEBHOOK_SECRET=$(openssl rand -hex 32)

4. Start JumpGate

jumpgate server

5. Add jumpgate.toml to Your Repo

# jumpgate.toml
name = "my-api"
domain = "api.yourdomain.com"
port = 8080
build_args = ["NODE_ENV=production"]
health_check_path = "/healthz"
env_vars = ["DATABASE_URL=postgres://..."]

6. Add a Webhook

• GitHub: Settings → Webhooks → Add webhook

  • Payload URL: http://<your-server>:9000/webhook
  • Content type: application/json
  • Secret: same as JUMPGATE_WEBHOOK_SECRET

• GitLab: Settings → Webhooks → Add webhook

  • URL: http://<your-server>:9000/webhook
  • Secret Token: same as JUMPGATE_WEBHOOK_SECRET

7. Deploy!

git push origin main

Watch the logs:

jumpgate logs my-api

CLI Reference

jumpgate server              Start the JumpGate daemon
jumpgate logs <app>          Stream build logs for an application
jumpgate status <app>        Show deployment status for an application
jumpgate env <app>           Show environment info for an application
jumpgate rollback <app>      Roll back to the previous deployment
jumpgate help                Show this help

jumpgate.toml Reference

Examples

Minimal Node.js app:

name = "web"
domain = "app.example.com"
port = 3000

Python API with health check and env vars:

name = "api"
domain = "api.example.com"
port = 8000
health_check_path = "/health"
env_vars = [
    "DATABASE_URL=postgres://user:pass@host/db",
    "LOG_LEVEL=info",
    "SECRET_KEY=${SECRET_KEY}"
]

Custom Dockerfile with build args:

name = "go-service"
domain = "go.example.com"
port = 9090
dockerfile = "Dockerfile.prod"
build_args = ["GO_VERSION=1.22", "CGO_ENABLED=0"]

Environment Variables

Deployment Lifecycle

Each deployment goes through these states:

Pending → Building → Running   (success)
                   → Failed    (build/health/cutover failure)
Running → Stopped              (cutover to new deployment)

• Pending: Deployment record created, waiting to enter the build queue
• Building: Docker image is being built; logs streamed to SQLite
• Running: Container is live, healthy, and receiving traffic
• Failed: Build, health check, or cutover failed; previous deployment untouched
• Stopped: Previous deployment was replaced by a newer one

Production Hardening

JumpGate includes several production-grade safety features:

• HMAC Signature Verification: All webhooks are cryptographically verified (SHA-256 for GitHub, token for GitLab)
• IP Rate Limiting: 5 req/s per IP with burst of 10; returns 429 on excess
• Deployment Debouncing: Duplicate commits are silently skipped while already building
• Health Check Timeout: Configurable timeout (default 5 min); unhealthy containers are killed, old deployment stays live
• Graceful Shutdown: SIGTERM → drain queue → stop Docker ops → close SQLite
• Image Pruning: Hourly garbage collection removes dangling images
• Isolated Builds: Each build clones to /tmp/jumpgate-builds/{hash}/ — never reused
• Single Worker Queue: Sequential Docker builds prevent OOM from concurrent operations

vs. Alternatives

Development

# Run tests
go test ./internal/...

# Build
go build -o jumpgate ./cmd/jumpgate/

# Run (requires Docker)
JUMPGATE_WEBHOOK_SECRET=test-secret-1234567890 jumpgate server

License

MIT — see LICENSE for details.