RunR v0.7.5

Documentation

White-label: branding and self-service signup

RunR can be offered as a branded "serverless cloud in a box": your company's name, logos and colours everywhere a user looks, and self-service signup with e-mail verification and an onboarding wizard. What projects cost is calculated by the optional Billing module; your own invoicing system invoices and collects.

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.

Part Single-tenant Multi-tenant
Branding (platform) ✓ ✓
Branding per tenant — ✓ (when the platform allows it)
Self-service signup, e-mail verification, allowlist, invite-only, CAPTCHA, terms ✓ ✓
Tenant per signup + onboarding wizard — ✓
Bills per project and owner, billing API and events (Billing module, optional — billing.md) ✓ ✓

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


1. Branding#

1.1 Fields#

Field Meaning Default
product_name Console header, login page, browser title, e-mails RunR
company_name Copyright line of the login page and e-mails BRF Teknoloji
logo_light_url Logo on light backgrounds (light theme, e-mails) RunR wordmark
logo_dark_url Logo on dark backgrounds (dark themes, login page) RunR wordmark
logo_mark_url Square icon (compact header) RunR icon
favicon_url Browser tab icon RunR icon
primary_color Base colour #rrggbb — shade 500 of the primary scale #f97316
primary_scale Optional explicit shades 300–900 (#rrggbb or r g b) derived from the base colour
accent_color Highlight colour (#rrggbb) #e63946
dark_color Base colour of the dark theme's tones: its page background (tone 950) #0a0a0a
dark_scale Optional explicit tones 50–950 of the dark theme (#rrggbb or r g b) derived from dark_color
light_color Base colour of the light theme's tones: its page background (tone 950) #fffcf8
light_scale Optional explicit tones 50–950 of the light theme derived from light_color
default_theme dark or light: the theme of users who never picked one dark
login_headline, login_text Replace the login page carousel empty (carousel)
support_email, support_url Support contact on the login page and in e-mails empty
footer_links Up to 8 {label, url} links (https:// or mailto:) none
powered_by Show "Powered by RunR" on a re-branded login page and in e-mails true
email_from_name Sender name of RunR's e-mails product name
email_logo_url Logo in e-mails light logo

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 by GET /api/branding/assets/{kind}).

1.2 Precedence#

Per field, the first value that is set wins:

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

"Reset to default" on a field in Administration → 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 (45 % / 25 %) and 600–900 by mixing with black (12 / 30 / 45 / 58 %). The console, the mails and the public status page derive the same scale.
  • 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 Administration → Branding):

Shade Value
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

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

The console's colours. Every accent is the brand scale: buttons, links, highlights, info chips, category badges, charts. Where categories need telling apart they differ by the style of the brand, not by another hue: project types XaaS solid / FaaS tinted / CaaS outlined, isolation Kata solid / gVisor tinted / runc outlined, and likewise trigger kinds, strategies, roles and run states. Status keeps its own colours whatever the brand: green for success, yellow for warnings, red for errors (critical solid, high a red tint). Warnings are yellow, not amber or orange, so they read apart from an orange brand (on the light theme their text is an olive-yellow, about 47° of hue from RunR's 700 shade).

Theme tones and the default theme#

The console has two themes, dark and light; users pick one in their menu. Each theme has its own tone scale --gray-50 … --gray-950: 950–700 are the surfaces (page, cards, inputs, borders), 600–50 the text tones from muted to strongest. The branding sets both:

  • Give one base colour per theme (dark_color, light_color): the page background, tone 950. The other tones are derived from it in OKLCH: each takes the base colour's hue and a fixed share of its chroma per tone (a gray base gives a gray scale, a navy one navy surfaces and bluish text), the surfaces follow the base colour's lightness, and the text tones keep RunR's lightness and with it their contrast. RunR's own base colours give RunR's scales.
  • Or give the full scale (dark_scale, light_scale): tones you leave out are derived.
  • default_theme (dark | light) is the theme of users who never picked one; a user's own pick always wins.

RunR's tones (empty branding): the dark theme is neutral (R = G = B, no blue cast) with a near-black page, Tailwind's neutral surfaces and text tones of the same contrast as before; the light theme is warm, from the RunR orange hue at low saturation, with the contrast of the former light theme.

Tone Dark Light
950 (page) 10 10 10 255 252 248
900 (cards) 23 23 23 254 245 239
800 (inputs) 38 38 38 245 232 223
700 (borders) 64 64 64 223 206 193
600 (muted text) 186 186 186 85 67 53
500 215 215 215 58 43 32
400 232 232 232 42 29 20
300 240 240 240 32 21 14
200 246 246 246 23 15 9
100 250 250 250 16 10 6
50 (strongest text) 253 253 253 10 7 4

The "Ocean" preset also brings a navy dark theme (the console's former navy theme) and a cool light theme. The same with Helm values (section 1.4):

branding:
  colors:
    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"
    dark: { "950": "9 27 78", "900": "15 36 96", "800": "22 46 114", "700": "30 59 133",
            "600": "175 195 225", "500": "205 218 240", "400": "222 232 248", "300": "235 240 250",
            "200": "242 245 252", "100": "248 250 254", "50": "252 253 255" }
    light: { "950": "255 255 255", "900": "245 247 252", "800": "230 235 245", "700": "200 210 228",
             "600": "55 70 105", "500": "30 45 80", "400": "18 30 62", "300": "10 22 50",
             "200": "6 15 40", "100": "3 10 32", "50": "2 6 25" }

The console writes the tones to <style id="runr-branding"> (each theme's --gray-*, and both as --surface-dark-* / --surface-light-* for the login and sign-up pages, which show a dark panel beside a light card, and for the terminal, which stays dark). It caches the branding: on the next page load the script in index.html applies the cached tones, brand scale and default theme before the first paint, so a re-branded console does not flash RunR's palette. A browser's very first visit has no cached branding yet: it starts in the installation's branding defaults instead (the Helm values branding.colors.* and branding.defaultTheme, the API's BRANDING_* settings). The UI container gets the same keys of runr-config and writes them to /branding-defaults.js when it starts (only checked colours, shade maps and dark / light reach the file), which index.html reads before the script. Without either, RunR's own theme. A brand saved in Settings → Branding reaches a first visit once GET /api/branding answers and is cached from then on.

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"
    # the themes' tones: one base colour (the page background, tone 950) each, or the full
    # 50–950 scale (section 1.3); empty: RunR's black dark theme and warm light theme
    dark: "#0a0a0a"
    # light: "#ffffff"
  defaultTheme: dark          # dark | light: the theme of users who never picked one
  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_DARK_COLOR, BRANDING_DARK_SCALE, BRANDING_LIGHT_COLOR, BRANDING_LIGHT_SCALE, BRANDING_DEFAULT_THEME, 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, the tones of both themes and the default theme (the login and sign-up pages included).
  • E-mails: Laravel's mail theme is branded — header logo or product name, the primary button in the brand's 600 shade, links in its 700 shade (readable on white), 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#

Administration → Branding (branding.manage; multi-tenant: platform administrators): every field, logo uploads, colour presets with live swatches, per-field reset, the tenant-branding switch, and a Themes section: the base colour and the 11 tones of each theme, a preview of each with the brand's button, link and badge and the contrast of its text (a warning below 4.5:1), and the default theme. A tutorial restart on the page tours these controls. Administration → Organization Branding (multi-tenant, branding.manage in the tenant — owners and admins by default): the same fields for the tenant.

Method Path Who
GET /api/branding?tenant=<slug> public (Cache-Control: public, max-age=60)
GET /api/branding/assets/{kind} public (Cache-Control: public, max-age=300)
GET / PUT /api/admin/branding branding.manage (multi-tenant: platform administrators)
POST / DELETE /api/admin/branding/assets/{kind} (multipart file) same
GET / PUT /api/tenant/branding branding.manage in the tenant
POST / DELETE /api/tenant/branding/assets/{kind} branding.manage in 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, Administration → Regions & settings or Administration → Signup). Administration → Signup adds:

Setting Default Effect
E-mail verification off The account is created only when the link in the e-mail is opened
Verification link lifetime 48 h After that the link answers 410; the user asks for a new one
Allowed domains any example.com (exact), *.example.com (sub-domains)
Invite-only off Public signup answers 403; users join through tenant invitations or admin-created accounts
CAPTCHA none The bot protection's register form (2.2)
Terms / privacy URLs none When set, signup requires accepting them; the time is stored (users.terms_accepted_at)
Tenant per signup (multi-tenant) on Every signup gets its own organization
Default quota (multi-tenant) 2000 m CPU / 4096 MB Quota on the first region
Self-service regions (multi-tenant) all active platform regions Regions the onboarding wizard offers

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#

The sign-up form is the register form of the bot protection, which guards every anonymous form (sign-in, sign-up, the demo sign-in, the public forms):

  1. Create a widget at Cloudflare Turnstile (or Google reCAPTCHA v2, hCaptcha) for the console host name — an organization with its own white-label host names may set its own keys.
  2. Administration → Access & security → Bot protection: provider, site key, secret key (write-only, stored encrypted), the forms — or Helm captcha.{provider,siteKey,secret,forms}.
  3. The sign-up form renders the widget; the API verifies the token with the provider's siteverify once every other field is valid (a token is single-use).

While the provider cannot be reached, a short proof-of-work check in the browser stands in (409 with a challenge, the form sent again with captcha_local); a refused token answers 422. Settings saved in Administration → Signup by an earlier release moved there with the forms set to register; the Helm values signup.captcha.* keep guarding the sign-up form while captcha.provider is none.

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. 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 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. With the Billing module on, the region chosen in the wizard counts as an accepted region offer at the tenant's default markup (0 % until the tenant sets one).

Method Path Who
GET /api/auth/registration-status public (enabled, invite-only, verification, domains, CAPTCHA site key, terms, tenant per signup)
POST /api/auth/register public (captcha_token or captcha_local, accept_terms, tenant_name)
POST /api/auth/signup/verify, /api/auth/signup/resend public
GET / PUT /api/admin/signup-settings signup.manage (single-tenant; multi-tenant: platform administrators)
GET /api/onboarding every tenant member (status, offered regions, default quota)
POST /api/onboarding {org_name, region_id?} settings.manage in the tenant

3. Plans (removed)#

Plans, plan limits, subscriptions, trials, credits, purchases and add-ons were removed in 0.5.8, together with Settings → Plans & Billing, Settings → Subscription and Settings → Charges. Branding, self-service signup and the onboarding wizard stay as they were. What a project costs is now calculated by the Billing module from region prices — pay as you go or fixed resources —, one bill per project and month paid by the project's owner. The upgrade keeps the plans, subscriptions and purchases of 0.5.7 in billing_legacy_archive (Upgrading).


4. Helm values#

branding: { productName, companyName, logo: {light, dark, mark}, favicon,
            colors: {primary, accent, dark, light}, defaultTheme,
            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: "" }   # earlier releases: use captcha.* (docs/helm-values.md#captcha)
  termsUrl: ""
  privacyUrl: ""
  tenantAutoCreate: true
  defaultQuota: { cpuM: 2000, memoryMb: 4096 }
  regions: ""                 # region ids offered in the onboarding wizard

billing:                      # docs/billing.md — the Billing module
  enabled: false
  currency: USD
  webhookUrl: ""              # billing events → your invoicing system
  webhookSecret: ""           # signs them; → Secret

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 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:

Permission Allows Built-in roles
branding.manage single-tenant: the install's brand (Administration → Branding); multi-tenant: the tenant's own brand (Administration → Organization Branding) Owner, Admin
signup.manage the signup settings (single-tenant; Administration → Signup) Owner, Admin
settings.manage completing the onboarding wizard of a self-service tenant Owner, Admin
platform administrators multi-tenant: the install's brand and signup settings —

The onboarding status is open to every tenant member. Billing permissions: billing.md.

6. Data#

Table Content
brandings Platform branding (tenant_id null) and tenant overrides, uploaded asset paths
pending_signups Signups waiting for their e-mail verification (token stored as SHA-256)
secure_settings Secrets entered in the admin UI (payment gateway keys), encrypted (encrypted cast)
captcha_settings Bot protection of the platform (tenant_id null) and the organizations' own keys; the secret encrypted (encrypted cast)
tenant_onboarding Onboarding wizard state of self-service tenants
users.terms_accepted_at Terms / privacy acceptance at signup

Bills, prices and billing events: billing.md.

RunR v0.7.5 · MIT License