Rukia Labs — what we're building https://docs.rukialabs.com/sw/blog Rukia Labs Docs Blog Sat, 05 Sep 2026 00:00:00 GMT https://validator.w3.org/feed/docs/rss2.html https://github.com/jpmonette/feed sw Copyright © 2026 Rukia Labs <![CDATA[One documentation site, two front doors]]> https://docs.rukialabs.com/sw/blog/one-docs-two-front-doors https://docs.rukialabs.com/sw/blog/one-docs-two-front-doors Sat, 05 Sep 2026 00:00:00 GMT This site is served at two addresses:

docs.rukialabs.com            Rukia Labs' own colours
yourorg.rukialabs.com/docs    your organisation's colours

Same words, same pages, same build inputs. Only the branding differs — and, less obviously, the path everything is mounted at.

Why not just one​

An organisation's documentation should look like their product, because inside their programme it is their product. Sending a learner from a branded console to a page in somebody else's orange is a seam where there does not need to be one.

And the general site has to exist too, for everyone who has not signed in to anything yet.

The colours are the easy half​

Branding already arrives at the edge, injected into the HTML before the page runs — see Branding that arrives before the JavaScript does, earlier on this blog. The docs read the same value and repaint their palette from it.

The one subtlety is ordering. The injected configuration lands at the very end of <head>, so anything in the head runs too early to see it. The repaint happens in the first tag of <body> instead: after the whole head, before anything is painted. Late enough to have the data, early enough that nobody sees the default first.

A version of this that ran at hydration would also be correct, eventually, and would flash on every page load — which is the whole thing we were avoiding.

The path is the hard half​

A static site generator compiles its base path into everything: every link, every asset URL, the client router's notion of where the root is. Ours is no exception.

That makes one build physically unable to answer at both mounts. Served under /docs, a build made for / emits a link to /guides/intro — and the first click walks the reader out of the documentation and into the learner application, which has never heard of that route.

Rewriting the HTML at the edge does not save it either. You can re-base the href in the markup; you cannot re-base the base path already compiled into the router bundle. The first click is client-side and never reaches the edge at all.

So it is two builds of one directory, differing in a single variable. Same content, same theme, same everything — two artifacts, because the mount point is a build input rather than a runtime one.

The bit we nearly got wrong​

Two copies of identical content on different hostnames is a duplicate-content problem. Left indexable, an organisation's copy competes with the general site for the same queries, and search engines pick a winner we did not choose.

The per-organisation mounts are noindex. They are for the people already inside that organisation; the copy meant for everyone else is the one that gets indexed.

Not a deep insight, but the kind of thing that is free to get right on the day and expensive to notice six months later.

]]> Documentation Multi-tenancy Edge <![CDATA[Four frontends, one address]]> https://docs.rukialabs.com/sw/blog/four-frontends-one-deployment https://docs.rukialabs.com/sw/blog/four-frontends-one-deployment Sat, 22 Aug 2026 00:00:00 GMT An organisation's address serves three separate applications:

yourorg.rukialabs.com/            learner
yourorg.rukialabs.com/instructor  authoring and grading
yourorg.rukialabs.com/admin       administration

They are three builds, from three directories, with three bundles. They share a domain, a session and a design system, and a person moving between them does not sign in again.

Why not one application​

The three audiences barely overlap. A learner never opens the grading queue; an administrator rarely takes a course. Built as one application, everyone downloads all three — and the admin console, the heaviest of them, is the one the fewest people open.

Why not three domains​

Because of the session. Three domains means the sign-in state has to be shared across origins, and every mechanism for doing that is either a third-party cookie — increasingly not a mechanism at all — or a redirect dance that is visible to the user and fragile in exactly the situations where it matters.

One origin means one cookie jar. The session problem disappears rather than being solved.

The part that is genuinely awkward​

Serving three applications from one origin means each has to know where it lives. A build served at /admin has to request its assets from /admin/assets/…, and its router has to know that /admin is the root and not a route.

That value is compiled in at build time. Which means the same source, built for a different mount point, is a different artifact — and if the mount point and the build disagree, the failure is not subtle. You get a blank page and a console full of 404s for JavaScript files that exist, at a path nobody asked for.

We have hit this from both directions. A build that captured the browser's path into a post-sign-in redirect — a path that already contained the prefix — and replayed it through a router that prepends the prefix itself, landing everyone on /instructor/instructor/. The learner console escaped it because its prefix is empty, which is exactly why it took a while to see: the bug was invisible in the application we look at most.

What holds it together​

A router at the edge decides which application serves a path, and rewrites the asset URLs in the HTML on the way back so the browser only ever sees the public layout. The applications behind it can be one deployment or several, at their own roots or under their prefixes, and the choice is configuration rather than code.

That flexibility earns its keep during migrations, and costs something the rest of the time: there are now two places a mount point is decided, and they have to agree. Our defence is that disagreement fails loudly — an unconfigured application returns an error naming the variable to set, rather than quietly falling back to a default that serves the wrong environment's code under the right hostname.

That specific failure — "not configured" and "working" being indistinguishable — is worth more attention than it usually gets. A fallback that makes a broken configuration look healthy does not prevent the outage. It just moves it to a worse moment.

]]> Architecture Multi-tenancy <![CDATA[Branding that arrives before the JavaScript does]]> https://docs.rukialabs.com/sw/blog/branding-before-the-bundle https://docs.rukialabs.com/sw/blog/branding-before-the-bundle Sat, 18 Jul 2026 00:00:00 GMT Every organisation on the platform gets its own address and its own branding. The obvious way to build that is to fetch the branding when the app starts. We did, and it was wrong in a way that took a while to name.

The flash​

Fetching branding on mount produces a sequence: the app boots with defaults, asks the server who this organisation is, and repaints. On a fast connection that is a flicker. On a slow one it is two seconds of the wrong logo.

It is worst exactly where it matters most — the sign-in page, the first thing a new learner sees. They arrive at their own organisation's address and are shown somebody else's brand while the page makes up its mind.

No amount of optimising the fetch fixes this. The request cannot start until the bundle runs, and the bundle cannot run until it is downloaded. The branding is always at least one round trip behind the first paint.

Moving the work in front of the app​

Every request to an organisation's address already passes through our router at the edge, which is what decides which application serves it. That router knows the hostname before any application does, and the hostname is precisely what identifies the organisation.

So it looks the organisation up and writes the result into the HTML on its way past:

<script>window.__TENANT__ = { "name": "…", "logoUrl": "…", "settings": { … } }</script>
</head>

By the time the browser parses the document, the branding is already in it. The application reads a value that is present before it starts rather than fetching one, and the first painted frame is correct. There is nothing to flash from.

What it cost​

Three things, none of them free.

The HTML cannot be shared. A page carrying one organisation's name must never be served to another, so these responses are no-store. The HTML shell is small and the hashed assets behind it still cache normally, so the trade is mostly fine — but it is a real one, and it is the reason this technique does not generalise to every page on the internet.

Lookups have to be fast. A per-request database query in front of every page load is not viable. The lookup reads a key-value store at the edge, written by the platform whenever an organisation's settings change, with a short in-process cache in front of it. Which means writes have to invalidate that cache — a cache that also caches misses, so a newly-created organisation stays "not found" for the length of the TTL unless someone purges it. We learned that the direct way.

The fallback has to stay. Injection can fail: a misconfigured host, a lookup that times out, local development where there is no edge at all. The application still fetches its own configuration when the injected value is absent. The fast path is an optimisation, never a requirement — the moment it becomes a requirement, every one of those cases becomes an outage.

Where else it goes​

Once the shell is being rewritten at the edge for one reason, other things want the same treatment. Shared badge and certificate pages now get their og: tags injected the same way, because link-preview crawlers do not run JavaScript either — a credential pasted into Slack used to preview as the generic application shell.

Same mechanism, same constraint: if it has to be in the HTML, it cannot wait for the bundle.

]]> Edge Multi-tenancy Architecture