@blendsdk/proxybuilder

🔧 Proxybuilder

Nginx reverse proxy configuration builder with SSL, load balancing, and maintenance mode.

Proxybuilder builds and manages nginx reverse proxy configurations on Ubuntu servers. It handles SSL certificate provisioning via Let's Encrypt (including wildcard certificates through DNS-01 challenges), supports round-robin load balancing to multiple upstream servers, and provides a file-based maintenance mode that requires no nginx reloads — making it ideal for CI/CD pipelines. Two proxy modes are available: passthrough (SSL termination + routing only) and full (adds security headers, gzip, and logging).

Architecture

┌─────────────────────────────────────────────────┐
│                   Internet                      │
└────────────────────┬────────────────────────────┘
                     │ HTTPS (443) / HTTP (80)
                     ▼
┌─────────────────────────────────────────────────┐
│                Nginx Proxy                      │
│           (managed by proxybuilder)             │
│                                                 │
│  ┌──────────────┐ ┌──────────┐ ┌─────────────┐  │
│  │     SSL      │ │ Routing  │ │ Maintenance │  │
│  │ Termination  │ │ by domain│ │ Mode Check  │  │
│  └──────────────┘ └──────────┘ └─────────────┘  │
└──┬──────────────────┬────────────────┬──────────┘
   │                  │                │
   ▼                  ▼                ▼
┌──────────┐   ┌──────────┐   ┌───────────────┐
│ Upstream │   │ Upstream │   │ Upstream      │
│ App 1    │   │ App 2    │   │ App 3 (x3)    │
│ :3000    │   │ :4000    │   │ :8080,:8081   │
│          │   │ (nginx)  │   │ :8082         │
└──────────┘   └──────────┘   └───────────────┘

Features

• ✅ SSL via Let's Encrypt — automatic certificate provisioning with auto-renewal
• ✅ Wildcard certificates — *.example.com via DNS-01 challenge (ClouDNS, Namecheap)
• ✅ Round-robin load balancing — multiple upstream servers per domain
• ✅ Passthrough mode — SSL termination only (upstream handles the rest)
• ✅ Full mode — security headers, gzip compression, access logging
• ✅ Maintenance mode — no nginx reload needed, CI/CD friendly
• ✅ Auto-renewal — daily cron job for certificate renewal
• ✅ Let's Encrypt staging — --staging flag for testing without rate limits
• ✅ Comprehensive status — system health, cert expiry, domain overview

Quick Start

# 1. Install proxybuilder
npm install -g @blendsdk/proxybuilder

# 2. Install system prerequisites (on server, as root)
sudo proxybuilder setup

# 3. Initialize proxybuilder
proxybuilder init --email [e-mail]

# 4. Add your first domain
proxybuilder create --domain api.example.com --upstream 127.0.0.1:3000

# 5. Verify
proxybuilder list

Prerequisites

• Ubuntu 22.04+ (Debian-based)
• Node.js >= 20 LTS
• Root/sudo access (for nginx, certbot, firewall configuration)
• Domain DNS pointing to the server's public IP address

Installation

# Option A: Global install via npm
npm install -g @blendsdk/proxybuilder

# Option B: Global install via yarn
yarn global add @blendsdk/proxybuilder

System Setup

The setup command installs all system-level prerequisites on a fresh Ubuntu server:

sudo proxybuilder setup

What it does:

• Updates package lists (apt-get update)
• Installs base packages (curl, wget, ca-certificates, etc.)
• Installs nginx
• Installs certbot via snap
• Configures UFW firewall (allows OpenSSH + Nginx Full)
• Verifies all installations

Options:

Flag	Description
--dry-run	Show what would be installed without executing

# Preview what would be installed
sudo proxybuilder setup --dry-run

Command Reference

All commands accept these global options:

Flag	Alias	Default	Description
--target	-t	/opt/proxybuilder	Target folder for proxybuilder data
--verbose		false	Enable debug output
--quiet		false	Suppress all output except errors
--version			Show version number
--help	-h		Show help

setup — Install system prerequisites

sudo proxybuilder setup [--dry-run]

Flag	Description
--dry-run	Show what would happen without executing

init — Initialize working directory

Creates the full directory structure, generates DH parameters, self-signed certificate, nginx config, and installs the renewal cron job.

proxybuilder init --email [e-mail]

Flag	Alias	Required	Default	Description
--email	-e	Yes	—	Let's Encrypt contact email
--no-cron		No	false	Skip cron job installation
--dry-run		No	false	Show what would happen

create — Add a domain

Creates a new domain with SSL certificate and nginx configuration.

# Standard domain (HTTP-01 webroot challenge)
proxybuilder create --domain api.example.com --upstream 127.0.0.1:3000

# Multiple upstreams (round-robin)
proxybuilder create --domain api.example.com \
  --upstream 127.0.0.1:3000 \
  --upstream 127.0.0.1:3001 \
  --upstream 127.0.0.1:3002

# Full mode (security headers, gzip, logging)
proxybuilder create --domain app.example.com --upstream 127.0.0.1:4000 --mode full

# Wildcard domain (DNS-01 challenge)
proxybuilder create --domain "*.example.com" --upstream 127.0.0.1:8080 --dns-provider cloudns

# Staging certificate (for testing)
proxybuilder create --domain test.example.com --upstream 127.0.0.1:5000 --staging

Flag	Alias	Required	Default	Description
--domain	-d	Yes	—	Domain name (or *.example.com for wildcard)
--upstream	-u	Yes	—	Upstream address(es) in host:port format
--mode	-m	No	passthrough	Proxy mode: passthrough or full
--dns-provider		No	—	DNS provider for wildcard certs (cloudns, namecheap)
--staging	-x	No	false	Use Let's Encrypt staging environment
--dry-run		No	false	Show what would happen

delete — Remove a domain

Fully removes a domain: revokes the certificate, deletes nginx configs and the app folder, and updates proxybuilder.json.

# Interactive (prompts for confirmation)
proxybuilder delete --domain api.example.com

# Non-interactive (skip prompt)
proxybuilder delete --domain api.example.com --force

# Keep the certificate
proxybuilder delete --domain api.example.com --force --keep-cert

Flag	Alias	Required	Default	Description
--domain	-d	Yes	—	Domain to delete
--force	-f	No	false	Skip confirmation prompt
--keep-cert		No	false	Don't revoke the SSL certificate

enable — Enable a disabled domain

Moves the nginx config from sites-disabled/ to sites-enabled/ and reloads nginx.

proxybuilder enable --domain api.example.com

Flag	Alias	Required	Description
--domain	-d	Yes	Domain to enable

disable — Disable a domain

Moves the nginx config to sites-disabled/ without deleting anything. The certificate and app folder are preserved.

proxybuilder disable --domain api.example.com

Flag	Alias	Required	Description
--domain	-d	Yes	Domain to disable

update — Update domain configuration

Changes upstream addresses and/or proxy mode for an existing domain. Re-renders nginx templates and reloads.

# Update upstreams
proxybuilder update --domain api.example.com \
  --upstream 127.0.0.1:4000 \
  --upstream 127.0.0.1:4001

# Change proxy mode
proxybuilder update --domain api.example.com --mode full

# Both at once
proxybuilder update --domain api.example.com \
  --upstream 127.0.0.1:5000 --mode passthrough

Flag	Alias	Required	Default	Description
--domain	-d	Yes	—	Domain to update
--upstream	-u	No	—	New upstream address(es) — replaces all existing
--mode	-m	No	—	New proxy mode: passthrough or full

list — List all domains

Displays all configured domains in a table or JSON format.

# Table output
proxybuilder list

# JSON output (for scripting)
proxybuilder list --json

Flag	Default	Description
--json	false	Output as JSON instead of table

Example table output:

DOMAIN                  STATUS      MODE            UPSTREAMS                       CERT EXPIRES    MAINT   STAGING
──────────────────────  ──────────  ──────────────  ──────────────────────────────  ──────────────  ───────  ────────
api.example.com         enabled     passthrough     127.0.0.1:3000,3001            2026-06-15      off     no
app.example.com         enabled     full            127.0.0.1:4000                 2026-06-15      off     no
*.example.com           enabled     passthrough     127.0.0.1:8080                 2026-06-15      off     no
staging.example.com     disabled    passthrough     127.0.0.1:5000                 2026-06-15      off     yes

Total: 4 domain(s)

renew — Renew SSL certificates

Renews certificates for one or all enabled domains. Uses the correct challenge method (webroot or DNS-01) based on each domain's stored configuration.

# Renew all enabled domains
proxybuilder renew

# Renew a specific domain
proxybuilder renew --domain api.example.com

# Force renewal (even if not expiring)
proxybuilder renew --force

# Check what would be renewed
proxybuilder renew --dry-run

Flag	Alias	Required	Default	Description
--domain	-d	No	—	Specific domain to renew (omit for all)
--staging	-x	No	false	Use Let's Encrypt staging environment
--force	-f	No	false	Force renewal even if not expiring
--dry-run		No	false	Check what would be renewed

revoke — Revoke a certificate

Revokes the SSL certificate for a domain via certbot. The domain configuration is preserved.

# Interactive (prompts for confirmation)
proxybuilder revoke --domain api.example.com

# Non-interactive
proxybuilder revoke --domain api.example.com --force

Flag	Alias	Required	Default	Description
--domain	-d	Yes	—	Domain whose certificate to revoke
--force	-f	No	false	Skip confirmation prompt

cert-info — Certificate details

Displays detailed SSL certificate information including subject, issuer, validity, SANs, and key type.

proxybuilder cert-info --domain api.example.com

Flag	Alias	Required	Description
--domain	-d	Yes	Domain to inspect

Example output:

  Subject:        CN = api.example.com
  Issuer:         C = US, O = Let's Encrypt, CN = R3
  Valid From:     Mar 15 00:00:00 2026 GMT
  Valid Until:    Jun 13 00:00:00 2026 GMT
  Days Remaining: 80
  Serial:         03:a1:b2:c3:...
  SANs:           api.example.com
  Staging:        No
  Key Type:       2048 bit

  Certificate Path: /opt/proxybuilder/letsencrypt/live/api.example.com/fullchain.pem

maintenance — Toggle maintenance mode

Enables or disables maintenance mode per domain using a file-based flag. No nginx reload is needed — nginx checks for the flag file on each request.

# Enable maintenance mode
proxybuilder maintenance --domain api.example.com --on

# Disable maintenance mode
proxybuilder maintenance --domain api.example.com --off

# Check current status
proxybuilder maintenance --domain api.example.com --status

Flag	Alias	Required	Default	Description
--domain	-d	Yes	—	Domain to toggle
--on		No	false	Enable maintenance mode
--off		No	false	Disable maintenance mode
--status	-s	No	false	Check current state

CI/CD pipeline example:

# Deploy with zero-downtime maintenance window
ssh user@server "proxybuilder maintenance --domain api.example.com --on"
deploy_app
ssh user@server "proxybuilder maintenance --domain api.example.com --off"

Custom maintenance page:

# Replace the default page with your own
cp my-maintenance.html /opt/proxybuilder/apps/api.example.com/maintenance.html

dns-setup — Configure DNS provider

Interactively configures DNS provider API credentials for DNS-01 challenges (required for wildcard certificates). Tests the credentials, saves them to the config, and generates certbot hook scripts.

proxybuilder dns-setup --provider cloudns
proxybuilder dns-setup --provider namecheap

Flag	Alias	Required	Description
--provider	-p	Yes	DNS provider: cloudns or namecheap

status — Health overview

Displays system health, domain summary, and certificate expiry status.

# Formatted output
proxybuilder status

# JSON output (for monitoring)
proxybuilder status --json

Flag	Default	Description
--json	false	Output as JSON

Example output:

─── Proxybuilder Status ──────────────────────────

  Version:    2.0.0
  Target:     /opt/proxybuilder
  Config:     ✓ Valid

─── System ───────────────────────────────────────
  nginx:      ✓ Running (pid 1234)
  certbot:    ✓ certbot 2.11.0
  Cron:       ✓ Installed

─── Domains (3 total) ────────────────────────────
  Enabled:      2
  Disabled:     1
  Maintenance:  0

─── Certificate Health ───────────────────────────
DOMAIN                  EXPIRES        DAYS LEFT     STATUS
──────────────────────  ─────────────  ────────────  ────────────────────
api.example.com         2026-06-15     82            ✓ OK
app.example.com         2026-04-10     16            ⚠ Expiring soon
staging.example.com     2026-06-15     82            ⚠ Staging cert

Proxy Modes

Passthrough Mode (default)

When to use: Your upstream has its own nginx (or web server) that handles security headers, gzip, logging, etc. You only need SSL termination and routing.

What it does:

• SSL termination (HTTPS → HTTP)
• Proxy headers (Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto)
• Route traffic to upstream server(s)

What it does NOT do:

• No security headers (no HSTS, no X-Content-Type-Options, etc.)
• No gzip compression
• No favicon/robots.txt handling
• No access logging (handled by upstream)

proxybuilder create --domain api.example.com --upstream 127.0.0.1:3000
# or explicitly:
proxybuilder create --domain api.example.com --upstream 127.0.0.1:3000 --mode passthrough

Full Mode

When to use: Your upstream is a bare HTTP application (Node.js, Python, Go) that doesn't have its own web server or security headers.

What it adds on top of passthrough:

• Security headers (HSTS, X-Content-Type-Options, X-Frame-Options, etc.)
• Gzip compression
• Favicon and robots.txt handling
• Access and error logging per domain

proxybuilder create --domain app.example.com --upstream 127.0.0.1:4000 --mode full

Wildcard Certificates

Wildcard certificates cover *.example.com — all subdomains under a domain. They require DNS-01 challenge, which means proxybuilder needs API access to your DNS provider.

Step 1: Configure your DNS provider

proxybuilder dns-setup --provider cloudns
# Follow the prompts to enter API credentials

Step 2: Create the wildcard domain

proxybuilder create --domain "*.example.com" --upstream 127.0.0.1:8080 --dns-provider cloudns

Supported DNS providers:

• ClouDNS — Requires auth-id and auth-password
• Namecheap — Requires API user, API key, and client IP

Multiple Upstreams (Load Balancing)

Proxybuilder supports round-robin load balancing across multiple upstream servers via nginx upstream blocks.

# Create with multiple upstreams
proxybuilder create --domain api.example.com \
  --upstream 127.0.0.1:3000 \
  --upstream 127.0.0.1:3001 \
  --upstream 127.0.0.1:3002

# Update upstreams later
proxybuilder update --domain api.example.com \
  --upstream 127.0.0.1:4000 \
  --upstream 127.0.0.1:4001

Note: --upstream on update replaces all existing upstreams.

Let's Encrypt Staging

For testing without hitting Let's Encrypt rate limits:

# Create with staging certificate (not trusted by browsers)
proxybuilder create --domain test.example.com --upstream 127.0.0.1:5000 --staging

# Renew with staging
proxybuilder renew --domain test.example.com --staging

⚠️ Staging certificates are not trusted by browsers. They are for testing only.

Configuration File

Proxybuilder stores all state in a single JSON config file:

Location: <target>/proxybuilder.json (default: /opt/proxybuilder/proxybuilder.json)

Schema:

{
  "version": "2.0",
  "email": "[e-mail]",
  "targetFolder": "/opt/proxybuilder",
  "defaults": {
    "proxyMode": "passthrough",
    "certMethod": "webroot"
  },
  "domains": {
    "api.example.com": {
      "proxyMode": "passthrough",
      "upstreams": ["127.0.0.1:3000", "127.0.0.1:3001"],
      "certMethod": "webroot",
      "enabled": true,
      "maintenance": false,
      "wildcard": false,
      "staging": false,
      "created": "2026-03-15T10:00:00.000Z",
      "updated": "2026-03-15T10:00:00.000Z"
    }
  },
  "dns": {
    "cloudns": {
      "provider": "cloudns",
      "authId": "1234",
      "authPassword": "secret"
    }
  }
}

This file is the single source of truth. All commands read from and write to it. Manual editing is possible but not recommended — use the CLI commands instead.

Directory Structure

/opt/proxybuilder/
├── proxybuilder.json           # Configuration (single source of truth)
├── dhparam.pem                 # Diffie-Hellman parameters (2048-bit)
├── nginx/
│   ├── nginx.conf              # Main nginx config (symlinked to /etc/nginx/)
│   ├── sites-enabled/          # Active domain configs
│   ├── sites-disabled/         # Disabled domain configs
│   ├── modules-enabled/
│   └── conf.d/
├── proxy/
│   ├── proxy.conf              # Shared proxy headers
│   └── letsencrypt.conf        # ACME challenge location
├── ssl/
│   ├── self-ssl.key            # Self-signed key (default server fallback)
│   └── self-ssl.crt            # Self-signed cert (default server fallback)
├── apps/
│   └── <domain>/
│       ├── upstream.conf       # Upstream server list
│       ├── ssl.conf            # SSL certificate paths
│       ├── maintenance.conf    # Maintenance mode check
│       ├── maintenance.html    # Maintenance page (customisable)
│       ├── maintenance.flag    # Maintenance mode flag (when active)
│       └── (mode-specific: security.conf, general.conf, log.conf)
├── logs/
│   ├── access.log
│   ├── error.log
│   ├── renewal.log
│   └── <domain>.access.log    # Per-domain logs (full mode only)
├── letsencrypt/
│   ├── lib/                    # Certbot working directory
│   └── live/
│       └── <domain>/
│           ├── fullchain.pem
│           ├── privkey.pem
│           └── chain.pem
└── dns/
    ├── cloudns-auth.sh         # DNS-01 auth hook (auto-generated)
    └── cloudns-cleanup.sh      # DNS-01 cleanup hook (auto-generated)

Troubleshooting

Issue	Solution
"nginx not found"	Run sudo proxybuilder setup
"certbot not found"	Run sudo proxybuilder setup
"Not initialized"	Run proxybuilder init --email [e-mail]
Certificate request fails	Check domain DNS points to server, check firewall allows port 80/443
502 Bad Gateway	Check upstream is running on the specified port
Wildcard cert fails	Verify DNS credentials with proxybuilder dns-setup --provider <name>
Permission denied	Run setup as root (sudo), init as the target user
Rate limited by Let's Encrypt	Use --staging flag for testing
nginx config test fails	Run nginx -t manually to see the detailed error
Maintenance mode not working	Check maintenance.flag exists: ls /opt/proxybuilder/apps/<domain>/

Migration from v1

For users upgrading from @truesoftware/proxybuilder:

• Backup your existing /opt/proxybuilder/ directory
• Install v2: npm install -g @blendsdk/proxybuilder
• Initialize: proxybuilder init --email [e-mail]
• Re-create domains: For each existing domain, run proxybuilder create ...
• Certificates: Existing certificates in /opt/proxybuilder/ssl/live/ should still be valid

v2 is a complete rewrite. It uses a new directory structure and config format (proxybuilder.json). Direct upgrade without re-creating domains is not supported.

License

ISC