Your platform

Your product is its platform: one deployment, built from scaledbox's module under your brand, on your own accounts, operated by you. This page is how it fits together.

Its parts

Components: your server (the API, the dashboard and console, its database, the reconciler and the scheduled jobs) and the machinery underneath (k3s, Traefik, Postgres's operator, boxd and the activators that run boxes, backups, metrics and logs). sync installs them from the cluster file.
Services: your product's own code, declared in scaledbox.toml and run as boxes: sandboxed processes of the JavaScript modules your build makes, awake as long as you ask, or asleep until their next request (Deploying). A service of only static files may be served by Cloudflare instead (static services).
Tenants (saas mode): your customers. Each has apps, and each environment of an app is a box, within the limits you set (Tenants). A tenant's box never shares a node with your server: tenants run on clusters of their own, which your platform runs.

Three modes

One stack, three modes. Pick by what your product runs:

saas, for a product with tenants: your customers' apps beside your own services.
single, for a product with server-side services and no tenants.
static, for a site of only static files: a homepage, docs, downloads.

	saas	single	static
Your server and cluster	yes	yes	none
Your services	boxes, and static services on Cloudflare	boxes, and static services on Cloudflare	static services on Cloudflare only
Tenants, their apps and databases	on clusters of their own	none: nothing of the tenant layer is installed	none
The tenants API, console and CLI	yes	no	no
Deployed by	your server, from a deploy your CLI posts	your server, from a deploy your CLI posts	your CI, to Cloudflare
Costs	your servers	your servers	nothing: Cloudflare's free plan

The cluster file decides between saas and single: a platform whose clusters run no tenants is single. Everything else is the same: the same components, sync, reconciler and runbooks. The smallest single platform is one cluster on one server; a saas platform adds a cluster for its tenants. A static platform has no cluster file: only scaledbox.toml, every service with provider = "cloudflare". scaledbox's own site, these pages included, is a static platform.

Two CLIs

	`shop-ops`	`shop`
Who runs it	you, and your CI	your customers, and your backend for one of them
Built from	`ops.Main`	`tenants.Main`
Reaches your server	through the control node; from CI, the public API (`SHOP_API_URL`, and a deploy token in `SHOP_TOKEN`)	the public API with one tenant's token: `shop login`, or `SHOP_TOKEN`
Commands	`sync`, nodes and backups; your services' deploys, secrets, logs and databases; tokens; any of your tenants	a tenant's apps: deploy, logs, secrets, domains, dumps, `dev`

shop-ops is never handed out, and its image is what your servers run. shop exists in saas mode only: it contains none of the operator's code, and your CI builds it for your customers' machines and you publish it where they download it (a static service of yours, for one). Its credentials live in their configuration directory under your brand's name (~/.config/shop/ on Linux). Your customers sign it in through your own page: Tenants.

How changes reach your servers

Everything is declared, then reconciled:

The cluster file (servers, components) by shop-ops sync, run by a person at a terminal. It shows its plan, with prices, and asks once.
Your services (scaledbox.toml) by a deploy. A CLI never deploys anything itself: it holds a token and posts the deploy to your server's API, nothing else. Your server records it, and its reconciler, which alone holds the rights, converges every target to it: its own cluster, your tenants' clusters, and Cloudflare for static services, with your platform's Cloudflare token. The CLI waits for the result.
Your tenants' apps by the tenants API, the same way.

What is derived (routes, certificates, Workers, a tenant's boxes) is rendered, applied and pruned by the reconciler, and repaired when changed by hand.

The one exception is a static platform: with no server to post to, its CI's shop-ops deploy plans, applies and prunes Cloudflare itself, with a token scoped to its zones and Workers.

Changes that cost money wait for a person. Your platform reconciles your tenants' clusters by itself, except changes that bill (a new server, a bigger type): those wait for your approval. Nothing removes a server, a firewall, a network or a bucket by itself.

Upgrades

Bump github.com/scaledbox/scaledbox in your go.mod, let your CI build the new image, then run shop-ops sync built from that commit: it rolls out the new server and components, and the database's migrations run forward, in order. Release shop with each upgrade: while scaledbox is in development, an older tenants' CLI may not work against a newer server. A static platform upgrades with its next deploy.