Glossary

If a term in another doc page reads like alphabet soup, look it up here. Definitions are written for people who are new to the system — there's no shame in skimming the whole page.

Core platform

PaaS — Platform-as-a-Service. The user pushes code; the platform builds, runs, scales, and routes it. WiseHosting is a small, self-hosted PaaS in the spirit of Heroku.

Control plane — The single Go binary that runs the dashboard, REST API, scheduler, alert manager, usage recorder, and the WSS hub. One process, one host, no replicas. See Architecture.

Worker — A separate Linux host that actually runs user containers. The control plane never runs user code; it dispatches jobs to workers over WSS.

App — A user's deployed project. Backed by one Postgres row, one Podman container, and one or more domains.

Job — A queued unit of work for a worker — typically deploy, restart, stop. Stored in Postgres and picked up via SELECT … FOR UPDATE SKIP LOCKED. There's no Redis or RabbitMQ.

Networking

WireGuard (WG) — Modern in-kernel VPN. Two peers exchange a public key, the kernel encrypts every packet end-to-end with ChaCha20-Poly1305. WiseHosting uses WG to keep all CP↔worker traffic off the public internet. See WireGuard mesh.

Mesh — A small, fully-connected (or hub-and-spoke) network of WG peers. Ours is hub-and-spoke: every worker peers with the control plane, not with each other.

Cloudflare-for-SaaS — A Cloudflare feature that lets you serve arbitrary user-supplied domains from your own infrastructure with TLS terminated at Cloudflare's edge. We use it so end users can point myapp.com at WiseHosting without us managing certs.

Cloudflare Tunnel (cloudflared) — A daemon that opens an outbound persistent connection to Cloudflare's edge. The worker doesn't need a public IP for app traffic — Cloudflare proxies inbound HTTPS through the tunnel.

Traefik — A reverse proxy that routes HTTP based on Host: and Path:. We run it as a Podman container on each worker. It pulls its config every 2 s from the control plane's HTTP-provider endpoint.

Identity & encryption

OAuth 2.0 — A delegation protocol. The user signs in to Google (or GitHub/GitLab/etc.), Google tells us who they are, and we issue our own session cookie. We never see the user's Google password.

TOTP — Time-based One-Time Password (RFC 6238). The 6-digit code from your authenticator app. Optional second factor at sign-in.

JWT — JSON Web Token. A signed, self-contained credential. Workers carry an HS256-signed JWT (15-minute TTL, refreshed 2 minutes before expiry) on every WSS frame.

HS256 — HMAC-SHA256. Symmetric JWT signing — same key signs and verifies. Fine when both signer and verifier live in the same trust boundary (control plane signs; control plane verifies).

HMAC — Hashed Message Authentication Code. A one-line proof that someone with the key sent this exact message. Each WSS envelope is HMAC-SHA256 signed with sha256(api_key).

HKDF — HMAC-based Key Derivation Function (RFC 5869). Lets us turn one master secret into many purpose-bound keys: wisehosting-aes-v1, wisehosting-worker-jwt-v1, etc. A leaked OAuth-state key can't decrypt user env vars even though both come from the same root.

AES-GCM — A modern authenticated cipher. We use AES-256-GCM for at-rest encryption of git tokens, env vars, TOTP secrets, and job payloads.

Bcrypt — A password-hashing function with a built-in work factor. Used for admin account passwords (regular users sign in via Google OAuth — no password to hash).

Bearer token — A credential carried in Authorization: Bearer <opaque-string>. Possession proves access; there's no challenge-response. We use bearer tokens for the loopback internal-api.

Containers & runtime

Podman — A daemonless OCI container runtime, drop-in docker replacement. We run Podman 5 on workers. No Docker daemon, so the worker survives podman crashes and runs containers under the unprivileged user namespace where possible.

OCI image — Open Container Initiative image. The standardised tarball-of-layers + manifest format both Docker and Podman use.

wisehosting-build network — A Podman network on 10.89.0.0/16 we create on each worker. Builds run with --network=wisehosting-build so they have working DNS but no access to the host's loopback or the WG mesh. Egress is further locked down with iptables rules dropping RFC-1918 traffic during builds.

Image digest pinning — Instead of running image:latest, the worker reads back the local image ID after build and runs by digest. If the bytes are tampered with between build and run, the run fails closed with an unresolvable reference.

Cosign — Sigstore tool for signing OCI images. scripts/cosign-setup.sh provisions a per-host keypair; verification is optional and bolted on at podman run time if your threat model requires it.

WSS protocol

WSS — Secure WebSocket (WebSocket over TLS). The persistent bidirectional channel between the control plane and each worker. Carries jobs, heartbeats, log lines, and admin queries.

Envelope — Our wire-format wrapper around every WSS message: type + ID + sequence number + timestamp + payload + HMAC. See WSS protocol.

Sequence number / replay window — Each direction of the WSS connection has a monotonic counter. Both sides reject duplicates within a 256-entry sliding window so a captured frame can't be replayed.

Clock-skew bound — Both sides reject envelopes whose ts (unix milliseconds) is more than 5 minutes off local time. Cheap defence against captured-and-delayed replays.

Heartbeat — A periodic envelope from worker to control plane carrying live stats (CPU, memory, network, disk). The hub uses the gap between heartbeats to drive the offline alert.

Dashboard & frontend

SPA — Single-page application. The React dashboard at internal/web/spa/. One JavaScript bundle, client-side routing, talks to /api/*. See Frontend reference.

me — The shape returned by GET /api/me: user, plan, apps, platform info. Acts as the SPA's global data bus — every page reads from it.

SSG — Static-site generation. scripts/prerender.mjs runs the SPA through headless Chromium and writes /, /login, /plans, /privacy, /terms as static HTML so search engines see real content.

//go:embed assets — Go directive that bakes the contents of internal/web/assets/ into the compiled binary. The SPA ships inside the Go binary — no separate static-file server.

Infrastructure

golang-migrate — A versioned SQL migration runner. We commit internal/database/migrations/000N_<name>.{up,down}.sql files; on startup the binary applies any unran ones in order.

schema_migrations — A single Postgres table maintained by golang-migrate that records the highest applied migration. Touch it manually only when recovering from a botched migration.

audit_events — The append-only table where every privileged action lands (logins, deploys, env writes, domain verifies, etc.). Originally login_events, renamed in 0005_rename_login_events.up.sql.

api_key_hash — The sha256 hex of a worker's raw API key. The control plane stores only the hash; the worker stores the raw key in its config. Comparison is constant-time.

Idle/absolute timeouts — Two clocks on every session. Idle resets on activity; absolute doesn't. A user session is 30 days absolute; an admin session is 8 hours absolute / 60 minutes idle.

SSRF guard — Server-Side Request Forgery defence. internal/httpx/NewWebhookClient does a DNS resolve before dialing and refuses any address in private RFC-1918 ranges. Stops a malicious user-supplied webhook URL from reaching e.g. 169.254.169.254 (cloud metadata).

Constant-time compare — crypto/subtle.ConstantTimeCompare. Compares two byte strings in time independent of where they differ — closes the timing-oracle hole that lets an attacker leak a secret byte at a time.

Roles in the admin subsystem

super_admin — Full read + write across every tenant. Reserved for break-glass on-call use.

support — Read-only access to user data + ability to issue refunds, pause an app, or unlock a stuck deploy. No DB writes outside that scope.

billing — Plan changes and invoice access. No app-level access.

read_only — Dashboards only. Used for new hires before they're trusted with anything destructive.

See Admin subsystem for how grants are stored and resolved.

Acronyms cheatsheet