Providers & control plane

Configure a VPS provider, wire an auth domain with wildcard TLS, and stand up a regional control plane. Provisioning uses bootstrap-fetch and a scoped Admin Proxy — no shared secrets, no shell.

Panel: Addons → ImpulseAuth · Tabs: Settings, Infrastructure

1. Supported VPS providers

A control plane is a regional VPS you own. ImpulseAuth uses ImpulseCore’s shared VPS provider catalog, so provider slugs, labels, setting keys, and capabilities are identical across the Impulse stack (Auth, Object Storage, Postgres). Add credentials for one or more providers under Settings → Providers & Regions.

Provider	Provisioning
AWS	API-driven instance creation.
Vultr	API-driven.
Linode	API-driven.
Hetzner	API-driven.
DigitalOcean	API-driven.
Azure	API-driven.
GCP	API-driven.
Proxmox	Self-hosted; cloud-init snippet support. Server identity is stored as node:vmid.

Vultr, Hetzner, DigitalOcean, and Linode take an API token, a default region, a default plan/size, and a default OS image; their provider SSH key field is used only for HIGH RISK break-glass access. AWS, Azure, and GCP take their own credentials (an IAM access key, a service principal, or a service-account JSON key), and their regions are mapped under ImpulseCore → Projects → Regions. Proxmox VE uses an API URL, a token, an optional certificate fingerprint, snippet storage, a default node, and a JSON plan catalog backed by cloud-init template VMs. Proxmox snippets upload through the API; the SSH snippet fallback works only while break-glass SSH is enabled.

Validate without SSH

After saving a provider, run Diagnostics → Health Checks → VPS Providers. It exercises the provider API directly — no host access needed — and confirms the token, default region, and default plan are usable.

2. Infrastructure settings

Open Settings → General & Access and set the values every control plane bakes into its bootstrap:

• WHMCS server IPs — used to write the Admin Proxy firewall allow rules. Include both IPv4 and IPv6 addresses of the host WHMCS runs on (Auto-detect IPs fills them in).
• Break-Glass Access — the HIGH RISK SSH toggle (off by default) and its SSH public key and private key path, which are used only while the toggle is on.
• Default GoTrue version — the version pin new control planes provision with (per-server overrides exist).
• Default region and provisioning timeout — placement fallback, and how long a control plane may stay provisioning before it’s marked failed (default 30 minutes).
• JWT secret pepper (optional) — an extra secret mixed into per-project JWT signing material.

Both IP families

The proxy port is opened to your WHMCS host over both IPv4 and IPv6. If you list only an IPv4 address and WHMCS reaches the host over IPv6 (or vice-versa), health checks will read the control plane as unreachable even though it is up.

3. DNS & wildcard TLS

Every project is served at <slug>.<auth-domain>, so you need an auth domain whose DNS is hosted at Cloudflare plus a wildcard certificate. Set these under Settings → DNS & TLS.

1. Point the auth domain’s nameservers at Cloudflare and enable the zone.
2. Create a Cloudflare API token with Zone → Zone → Read and Zone → DNS → Edit for that zone, and save it with the zone ID. ImpulseAuth uses it for DNS-01 wildcard issuance and to write DNS records.
3. Set the Let’s Encrypt registration email and the DNS-01 propagation delay.

You don’t create DNS records by hand: ImpulseAuth writes an A/AAAA record for each control plane’s hostname and for each project hostname, pointing at the control plane that holds the project. Each control plane obtains a wildcard certificate via DNS-01 and renews it weekly through certbot. If a certificate ever needs to be replaced out of band, use Reissue TLS in the server’s menu — a typed Admin Proxy operation (POST /admin/v1/tls/reissue) rather than an SSH rebuild.

Verify it later

Test DNS Connection on the DNS & TLS tab, and the DNS Provider health check, confirm the Cloudflare token can read the zone and write a test record. Blank or failing wildcard TLS almost always traces back to a token missing DNS-edit scope.

4. Custom domains (Cloudflare for SaaS)

Customer custom domains route through managed cdn-* origins using Cloudflare for SaaS. Configure it under Settings → CDN & Custom Domains: this lets a customer serve the Auth API and the hosted app portal from their own hostname (for example login.customer.com) while the default per-project endpoint always stays available for direct API traffic. The token also needs Zone → SSL and Certificates → Edit, and the zone needs a Cloudflare for SaaS fallback origin before customer hostnames can activate.

The Cloudflare for SaaS health check validates custom-hostname creation, DNS, certificate issuance, and fallback-origin access. Custom domains need a Pro-tier plan and an IAUTH- license; otherwise the default project endpoint is the only hostname.

5. The bootstrap-fetch control plane

Provisioning never places secrets in provider user-data. Instead, the provider receives only a short-lived one-time token and a fetch URL. WHMCS holds the full encrypted bootstrap payload — the Admin Proxy bearer secret, database admin credentials, SMTP credentials, DNS token, and JWT secret pepper — and burns the token after the host fetches it once.

The bootstrap then installs the web front end, PostgreSQL, certbot, the auth-engine systemd template, and the FastAPI Admin Proxy, which serves HTTPS on port 9098 (plain HTTP on 9099 stays open for older WHMCS connections). The firewall opens 22/80/443 publicly and restricts 9098 and 9099 to your WHMCS host over both IPv4 and IPv6.

Treat provider-console access as privileged

Because the one-time token is the only sensitive value in user-data, anyone who can read the raw cloud-init before first boot could redeem it. Never paste full cloud-init user-data into tickets or logs, and rotate if a token was exposed before it was burned.

6. Provision a control plane

Under Infrastructure, use + Provision New Server to create a fresh host through a configured provider (recommended), or + Add Existing Server to register a host you run yourself (its menu then offers a one-time installer).

1. Choose a provider, region, and size, and give the server a region code used for placement.
2. Submit; the row starts as provisioning. For Proxmox, region means node and the plan maps to a cloud-init template VM.
3. Create any DNS records the UI shows once the provider returns an IP.
4. Watch the bootstrap log from the server row (View Log). When the Admin Proxy answers /health, the host joins the pool and flips to active.

The refresh_servers cron (every 2 minutes) polls control planes that are provisioning or rebuilding: it flips each to active once its Admin Proxy answers, or to provision_failed once it passes the provisioning timeout. For a running control plane, use Test Admin Proxy or Refresh health from its menu, or Diagnostics → Health Checks → Auth Control Planes.

Apply/Rebuild is in-place

Apply/Rebuild on a server row preserves the VPS, its IP, the Postgres schemas, the project route map, and stored credentials while re-applying the current bootstrap through the Admin Proxy. Only its SSH fallback — available while break-glass SSH is enabled — is a HIGH RISK rescue path.

7. Apply & drift correction

Normal configuration changes reapply through the typed bootstrap/apply endpoint, which supports dry-run (Preview Apply), apply (Apply/Rebuild), and rollback (Rollback Apply). If an apply installs a new Admin Proxy bundle, WHMCS waits for the restarted bundle hash and runs a second pass rather than falling back to SSH.

POST /admin/v1/bootstrap/apply    # scoped dry-run, apply, rollback
GET  /admin/v1/log/bootstrap      # tail the bootstrap log

Config drift and rebuilds are treated the same way: reapply routes through typed, scoped Admin Proxy endpoints. An SSH rebuild is HIGH RISK break-glass / rescue only.

8. Regions & placement

Region codes on control planes drive order placement:

• Explicit region requested — a hard guarantee. If the requested region has no capacity, the order fails loudly rather than being silently placed elsewhere.
• No region requested — ImpulseAuth places into the least-loaded eligible control plane.

Expose a Region configurable option or custom field on the WHMCS product if you want customers to choose placement at checkout. Add capacity in a region by provisioning another control plane with the same region code.