My Jitsi white-label broke every page, and the cause was a newline
Four lines of JavaScript in custom-config.js, one missing newline at the end of the file, and every page on the Jitsi instance went black. The parser rule behind it, the nginx fix that replaced it, and the gate that now catches the repeat.
Branding a Jitsi install looks like a small job from the outside. You want the page people land on to carry your name and your colour, plus one button that joins the room. On 1 November I was doing exactly that on a test instance of my own, and I took the whole thing offline for a while.
The design was fine. The CSS was fine. What broke it was where I put four lines of JavaScript, and one missing newline at the end of the file.
Here is the build, the failure, and the rules I follow now.
What I was trying to do
Jitsi's welcome page is Jitsi's. For a branded deployment it should open on a lobby: logo, brand name, the room you are joining, one button. The meeting itself can stay stock Jitsi, and in the end it did.
Docker Jitsi gives you a hook for exactly this. On boot the web container copies a mounted config directory into itself, and two files in there get appended to the app's own configuration: custom-config.js and custom-interface_config.js. App name, logo, language and welcome text all travel through them. That path already worked for the branding, so it looked like the obvious place for a stylesheet link and a small redirect.
I appended this to custom-config.js:
(function () {
document.documentElement.classList.add('shp-ui');
var l = document.createElement('link');
l.rel = 'stylesheet';
l.href = '/custom/skin.css';
document.head.appendChild(l);
if (location.pathname === '/') {
location.replace('/custom/lobby.html');
}
})();On its own that is ordinary DOM work. It runs before the app mounts, which is the earliest hook you get. (Cost is a different question, and I measured Jitsi against Zoom earlier.)
What happened
Every page went black. The root, the prejoin screen, every room URL. Two console lines took me a while to connect:
Uncaught SyntaxError: Unexpected token '<'
Uncaught ReferenceError: interfaceConfig is not definedconfig was undefined too. So I pulled the file off the server and ran node --check on it. It parsed. The file was valid JavaScript on disk and broken inside the page.
That gap is where the obvious explanation stops helping. I fetched the served HTML and looked at the line the browser complained about. My block ended like this:
// selfhostpilot: ui-v3 skin -- end</script>The closing script tag sat on the same line as the last line of my code, because the file I generated had no trailing newline. Everything after that tag was being read as script text, so the next script element became a syntax error, and the configuration that should have run before it never ran at all.
Why the file parses alone and breaks in the page
Docker Jitsi does not link custom-config.js. It reads the file at container boot and inlines the text into index.html as a script block.
From that moment the HTML parser owns it. Inside a script element the parser scans for the closing tag before the JavaScript engine sees a single line of your code, and comments and strings do not protect you. If your last line has no newline, the closing tag lands on the end of your comment and the rest of the document becomes script content.
Two things made it worse than a one line mistake:
- The failure is a blank screen on every route, including the page you would use to check your work.
- Nothing in the deploy told me. The branding verifier passed because the branding values were still in the config file. My change had broken the app underneath it, and the checks I had were pointed somewhere else.
The fix: serve the lobby from your own file
I stopped putting executable JavaScript into the config file. So the lobby became a static page I own, served by nginx at the root of the site:
location = / {
root /run/web/config;
try_files /custom/lobby.html =404;
default_type text/html;
charset utf-8;
add_header Cache-Control "no-store";
}The stylesheet is a plain <link> in that HTML file. No injection, no escape rules, no coupling to whatever upstream does to its config at boot.
It has three properties the append version did not have. It is a file, so a syntax error in my code breaks my page and nothing else. It lives in the mounted config tree, so a Jitsi image upgrade does not delete it. And it comes out with one flag that removes one nginx include, without touching anything upstream ships.
Two traps from the same afternoon
Do not claim /index.html
Jitsi's own configuration falls back to index.html for every room URL. I had pointed that path at my lobby, so a room request returned the 4.5 KB lobby page instead of the application. Opening a room looked blank and the logs looked fine.
Do not redirect the root with a 302
nginx builds an absolute redirect from the port the container listens on, so visitors were sent to :8443. Serving the lobby at / with root and try_files avoids the whole problem. That same quirk is why an alias to a single file inside location = / returned a 500 here.
What changed so the repeat cannot happen
The deploy now ends in a gate that runs against the running instance. It loads the root and confirms the lobby is served with the brand name in it, fetches the stylesheet and a font back to check they arrive with real bytes, and opens a room URL to confirm it returns the application.
Two more checks keep that gate honest. One asserts the rails in the build script offline, so a hardcoded path or a missing include fails before a server is touched. The other is a self test that makes the gate go red on purpose, because a check nobody has seen fail is a check you cannot trust.
That gate is wired into the upgrade lane too. A red design check counts as a failed upgrade and the stack rolls back to the release it was on. That is the difference between a design you shipped once and a design that survives the next release.
And I shipped less than I planned
The meeting restyle looked good in the mockup and wrong on a real screen. With two participants and the camera off, the dock sat over the speaker's name, and the corners I had designed disappeared behind the video tiles. Fixing that properly means forking Jitsi's React app and maintaining the fork across every release.
So the meeting went back to stock Jitsi and only the lobby shipped. The run had already finished with 30 of 30 verifier checks passing, five screenshots in the evidence folder, and a flag called MEETING_SKIN set to false so nothing can quietly switch the restyle back on.
The lobby took an afternoon. Removing the meeting skin took twenty minutes. I would rather write that down than pretend the first plan worked.
A supported hook takes you as far as the vendor designed it to go. Theming a product and rebuilding it are different jobs with different maintenance bills, and knowing which one you are in saves you a lot of evenings.
Frequently asked questions
Why did every Jitsi page go black after I edited custom-config.js?
Because the file is inlined into index.html as a script block at container boot. If the text you add ends on the same line as a closing script tag, the rest of the page is read as script. The configuration never runs, and the app has nothing to mount.
Does custom-config.js survive a Jitsi upgrade?
Yes. The file lives in the mounted config directory (/root/.jitsi-meet-cfg on the Docker setup), so a new image reads it again at boot. That is also why a syntax problem in it comes back after an upgrade that looked clean.
How do I serve my own page at the Jitsi root?
Serve it with nginx from the config tree: a location block for / that uses root and try_files to point at your file, plus a separate location for /custom/ for your assets. Leave /index.html alone, because Jitsi falls back to it for every room URL.
Written from the deploy logs, the design notes and the gate scripts of my own Jitsi test instance on uiv3.hiteshsaini.site, which was destroyed after the run. No client data is in this post. If you would rather hand that upgrade lane to someone who has broken it before, I do this for a living.