White-label: branding, self-service signup and plans

RunR can be offered as a branded "serverless cloud in a box": your company's name, logos and colours everywhere a user looks, self-service signup with e-mail verification, and optional plans with prices, limits and quotas. RunR calculates what each organization owes; your own billing system invoices and collects through the billing API.

Everything on this page is configured at runtime (admin UI) on top of the install values (Helm). Nothing needs a rebuild of the console or the API.

The default brand is RunR by BRF Teknoloji (RunR wordmark, RunR icon, RunR orange).

1. Branding#

1.1 Fields#

Logo and favicon values accept an https:// URL, a path on the console host (/brand/logo.svg), or a data:image/…;base64,… URI (PNG, JPEG, WebP, GIF, SVG, ICO; up to about 700 KB). SVGs are refused when they contain scripts, event handlers or embedded documents. Logos can also be uploaded in the admin UI (stored on the API volume, served under /storage).

1.2 Precedence#

Per field, the first value that is set wins:

1. Tenant override (multi-tenant, Settings → Organization Branding — only when the platform allows tenant branding; powered_by stays a platform decision)
2. Platform override (Settings → Branding)
3. Install brand (Helm values branding.*, applied when the pods start)
4. RunR default

"Reset to default" on a field in Settings → Branding removes the stored override, so the Helm value applies again. Changing a Helm value later changes every field that was never overridden in the admin UI.

1.3 Colours#

The console's colour tokens are CSS variables driven by the branding: --brand-300 … --brand-900 (the primary scale) and --brand-accent. The UI's Tailwind colour tokens keep their names and read these variables, so every button, link, badge and focus ring follows the brand.

• Give one base colour (primary_color, shade 500): RunR derives 300 / 400 by mixing with white (40 % / 20 %) and 600–900 by mixing with black (18 / 36 / 50 / 62 %).
• Or give the full scale (primary_scale) when your design system defines its own shades; shades you leave out are derived from the base colour.

Example preset "Ocean" (blue scale, also available as a preset button in Settings → Branding):

GET /api/branding returns the resolved palette (RGB triplets per shade) next to the colours.

1.4 Installing with your own brand via Helm values#

# values-brand.yaml — helm upgrade --install runr brf-tech/runr -f values-brand.yaml
domain: console.example.com
edition: multi-tenant

branding:
  productName: "Example Cloud"
  companyName: "Example Inc."
  logo:
    light: "https://cdn.example.com/brand/logo-light.svg"
    # a key of an existing ConfigMap / Secret in the release namespace; its content is a URL,
    # a data: URI or raw <svg> markup
    dark:
      configMapKeyRef: { name: example-brand, key: logo-dark.svg }
    mark: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  favicon:
    secretKeyRef: { name: example-brand-secret, key: favicon }
  colors:
    # one base colour …
    # primary: "#0f766e"
    # … or the full scale ("Ocean" example preset)
    primary:
      "300": "102 197 237"
      "400": "51 181 233"
      "500": "0 159 227"
      "600": "0 123 192"
      "700": "0 85 184"
      "800": "0 68 153"
      "900": "0 43 128"
    accent: "#009fe3"
  loginHeadline: "Serverless functions for your teams"
  loginText: "Deploy code in seconds on our private cloud."
  supportUrl: "https://support.example.com"
  supportEmail: "support@example.com"
  footerLinks:
    - { label: "Status", url: "https://status.example.com" }
    - { label: "Terms", url: "https://example.com/terms" }
  poweredBy: true
  email:
    fromName: "Example Cloud"
    logo: "https://cdn.example.com/brand/logo-mail.png"   # PNG reads best in mail clients
  tenantOverrides: true

Create the referenced ConfigMap / Secret before the release, for example:

kubectl -n runr create configmap example-brand --from-file=logo-dark.svg=./logo-dark.svg
kubectl -n runr create secret generic example-brand-secret --from-file=favicon=./favicon.png.b64

(favicon.png.b64 holds a data:image/png;base64,… line.) The chart validates every branding.* value against its values.schema.json (URLs, data: URIs, colour formats, links).

The values become environment variables of the API, Horizon and scheduler pods (BRANDING_PRODUCT_NAME, BRANDING_COMPANY_NAME, BRANDING_LOGO_LIGHT, BRANDING_LOGO_DARK, BRANDING_LOGO_MARK, BRANDING_FAVICON, BRANDING_PRIMARY_COLOR, BRANDING_PRIMARY_SCALE, BRANDING_ACCENT_COLOR, BRANDING_LOGIN_HEADLINE, BRANDING_LOGIN_TEXT, BRANDING_SUPPORT_EMAIL, BRANDING_SUPPORT_URL, BRANDING_FOOTER_LINKS, BRANDING_POWERED_BY, BRANDING_EMAIL_FROM_NAME, BRANDING_EMAIL_LOGO, BRANDING_TENANT_OVERRIDES); a ConfigMap / Secret reference is passed with valueFrom.

1.5 Where the brand appears#

• Login page (before sign-in): GET /api/branding (or ?tenant=<slug> once a user picked an organization's tenant sign-in) — logos, colours, headline, footer links, support link, copyright line.
• Console: header logo / product name, document title, favicon, colours.
• E-mails: Laravel's mail theme is branded — header logo or product name, button colour, footer links, support contact, copyright line, "Powered by RunR". Sender name: email_from_name (mails sent with the install's default sender name are renamed). Mails sent for a tenant (invitations) use that tenant's branding. A data: logo is served to mail clients through GET /api/branding/assets/email_logo.
• Brand images: GET /api/branding/assets/{logo_light|logo_dark|logo_mark|favicon|email_logo} (?tenant=<slug>): the uploaded file or decoded data: URI (sandboxing Content-Security-Policy), a redirect for a URL value.

1.6 Admin UI and API#

Settings → Branding (branding.manage; multi-tenant: platform administrators): every field, logo uploads, colour presets with live swatches, per-field reset, the tenant-branding switch. Settings → Organization Branding (multi-tenant, branding.manage in the tenant — owners and admins by default): the same fields for the tenant.

PUT is a partial update; a field sent as null returns to its default.

2. Self-service signup#

Registration stays on by default (registration_enabled, Settings → Platform or Settings → Signup). Settings → Signup adds:

2.1 E-mail verification#

POST /api/auth/register      → 202 {verification_required: true, email}
  (signup stored in pending_signups: name, username, bcrypt password, workspace name, consent)
e-mail link  https://<console>/signup/verify?token=…
POST /api/auth/signup/verify {token} → 201 {user, token, tenants, active_tenant}
POST /api/auth/signup/resend {email} → 200 (same answer for every address; at most once a minute)

No account, no tenant and no database schema exists for an unverified address. Signing up again with the same address replaces the waiting signup; a username held by another waiting signup is refused. Expired waiting signups are removed after a week (scheduled daily).

2.2 CAPTCHA#

1. Create a site at Cloudflare Turnstile or hCaptcha for the console host name.
2. Settings → Signup: provider, site key, secret key (write-only, stored encrypted) — or Helm signup.captcha.{provider,siteKey,secret}.
3. The signup form renders the widget; the API verifies the token with the provider's siteverify endpoint once every other field is valid (a token is single-use).

A provider selected without a secret, an unreachable provider or an unexpected answer rejects the signup (fail closed) and is logged.

2.3 Tenant per signup and onboarding (multi-tenant)#

The signup's tenant is named from the form ("Workspace name") or <name>'s workspace; the user becomes its owner. With plans on, the tenant starts on the default plan (when one is marked default). On the first sign-in the owner sees the onboarding wizard:

1. Organization name (renames the tenant)
2. Region — asked only when several self-service regions are offered; with one region it is assigned directly. The quota is the plan's (plans on) or the default signup quota, lowered to what is still free of the region capacity (the organizations' quotas on a region add up to at most its capacity; inside a quota, scale-to-zero projects overcommit by the region's factors, Organization quotas).

Tenants created by a platform administrator never see the wizard. Other plans are put into effect by the platform administrator or by your billing system (billing.md).

3. Plans#

Plans are off by default. While off, no plan appears anywhere — not in the console, not in the API's public listing — and tenant quotas are managed per region by the platform administrator as before.

Switch them on in Settings → Plans & Billing (or Helm plans.enabled: true). A plan is an input of RunR's calculation: its price is the plan fee per period, its limits and features apply to the tenants on it. How plans are put into effect, renewed and ended — and how your billing system changes them or sells prepaid terms and add-ons — is described in billing.md.

3.1 A plan#

Limits left empty are unlimited. Add-ons bought in your system raise a tenant's limits for their term (billing.md). Refused requests answer 422 {code: "plan_limit", limit, max, used} (limit: "feature", feature: … for a feature flag). Platform administrators are never limited.

A plan whose CPU / memory limit changes is written to the quotas of all its tenants. A plan in use is archived instead of deleted (hidden, kept for its tenants).

3.2 What tenants see#

Settings → Subscription (every member of the tenant): the plan, its status (trialing, active, canceled), period and trial end, the limits with their usage (add-ons included) and the public plans. Members with billing.manage (Owner, Admin, Billing) get a link to your store when billing.storeUrl is set — that is where plans and credits are bought; your billing system then records the purchase in RunR. Settings → Charges in the tenant (billing.view) lists the tenant's charges, credit and purchases.

4. Helm values#

branding: { productName, companyName, logo: {light, dark, mark}, favicon, colors: {primary, accent},
            loginHeadline, loginText, supportUrl, supportEmail, footerLinks, poweredBy, email: {fromName, logo},
            tenantOverrides }                                        # section 1.4

signup:
  emailVerification: false
  verificationTtlHours: 48
  allowedDomains: ""          # "example.com,*.example.org"
  inviteOnly: false
  captcha: { provider: none, siteKey: "", secret: "" }   # turnstile | hcaptcha; secret → Secret
  termsUrl: ""
  privacyUrl: ""
  tenantAutoCreate: true
  defaultQuota: { cpuM: 2000, memoryMb: 4096 }
  regions: ""                 # region ids offered in the onboarding wizard

plans:
  enabled: false

billing:                      # docs/billing.md
  webhookUrl: ""              # billing events → your billing system
  webhookSecret: ""           # signs them; → Secret
  usageThresholds: ""         # "100,500,1000"
  storeUrl: ""                # where tenants buy plans and credits

Every value is an install default: a value saved in the admin UI wins. Secrets go to the release Secret (secretName); with secret.create: false add the keys BILLING_WEBHOOK_SECRET and SIGNUP_CAPTCHA_SECRET to the pre-created Secret yourself (both optional).

5. Permissions#

Roles and permissions (docs/permissions.md) authorize every route; the white-label routes use:

Reading the tenant's plan (GET /api/tenant/subscription) and the onboarding status is open to every tenant member.

6. Data#

Charges, purchases and billing events: billing.md.