From c19b179fbf2cc50697b41384cb74360397e86759 Mon Sep 17 00:00:00 2001 From: Eduardo Garcia Date: Sun, 25 Oct 2026 11:12:59 -0300 Subject: [PATCH 1/2] feat: let hosts brand the modern design with a theme.css frontend/styling/theme.css ships empty and is loaded after index.css on the modern page, so a host can override the CSS variables of colors.css, the background and the logo without touching the files of the project. There is no switch for the visitors. The README documents the variables, what a theme cannot reach, and the Docker paths: the entrypoint empties /var/www/html and copies /speedtest/frontend at every start, so a theme is mounted (or copied) into /speedtest/frontend. Follows the suggestion in #863 of a static style for hosts, kept apart from the localization. --- doc_docker.md | 8 +++ frontend/README.md | 58 ++++++++++++++++++ frontend/index.html | 1 + frontend/styling/theme.css | 7 +++ index-modern.html | 1 + tests/docker-compose-playwright.yml | 3 + tests/e2e/fixtures/theme-host.css | 8 +++ tests/e2e/static-repository-assets.spec.js | 1 + tests/e2e/theme.spec.js | 70 ++++++++++++++++++++++ 9 files changed, 157 insertions(+) create mode 100644 frontend/styling/theme.css create mode 100644 tests/e2e/fixtures/theme-host.css create mode 100644 tests/e2e/theme.spec.js diff --git a/doc_docker.md b/doc_docker.md index e116159..6937afc 100755 --- a/doc_docker.md +++ b/doc_docker.md @@ -96,6 +96,14 @@ This command starts LibreSpeed in standalone mode, with persisted telemetry, ID docker run -e MODE=standalone -e TELEMETRY=true -e ENABLE_ID_OBFUSCATION=true -e PASSWORD="yourPasswordHere" -e WEBPORT=86 -p 86:86 -v $PWD/db-dir/:/database -it ghcr.io/librespeed/speedtest ``` +## Branding the modern design + +To give your instance its own colors, background and logo, put your own `theme.css` (and `logo.svg`) in +`/speedtest/frontend/styling/` and `/speedtest/frontend/images/` of the container, either with a bind mount or with a +`COPY` in your own image. Mount at `/speedtest/frontend`, not at `/var/www/html/frontend`: the entrypoint empties +`/var/www/html` and copies the frontend into it at every start. The modern design needs `USE_NEW_DESIGN=true`. The +variables and examples are in [frontend/README.md](frontend/README.md#theming). + ## Multiple Points of Test For multiple servers, you need to set up 1+ LibreSpeed backends, and 1 LibreSpeed frontend. diff --git a/frontend/README.md b/frontend/README.md index b19be33..6abd1cb 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -18,6 +18,64 @@ page fetches them relative to itself: - `../settings.json` overrides selected `speedtest_worker.js` settings. - `index.html` and `../index-modern.html` show how the frontend is wired up. +## Theming + +The look of the modern design is driven by the CSS variables in `styling/colors.css`. To brand an instance, put your own +values in `styling/theme.css`. That file ships empty and is loaded after `index.css`, so it wins. There is no switch for +the visitors: the host decides. + +```css +:root { + --theme-green: #ff8a00; /* accents, links, the tagline */ + --theme-pink: #7a2cff; /* the second color of the button and the hover of the links */ + --background-backup-color: #101820; /* the page behind the background image */ +} + +html { + background-image: url("../images/my-background.jpg"); /* relative to theme.css, so to this folder */ +} +``` + +The variables that change the look are the ones in `styling/colors.css`: the accent colors (`--theme-green`, +`--theme-pink`), the texts (`--primary-text-color`, `--secondary-text-color`, `--tagline-text-color`, and the disabled +ones), the background (`--background-backup-color`, `--background-overlay-color`), the start button +(`--button-*`), the server selector (`--server-selector-*`), the gauges (`--gauge-background-color`, +`--gauge-pointer-green`, `--gauge-pointer-pink`), ping and jitter (`--ping-and-jitter-*`) and the popups +(`--popup-background-color`). `--gauge-progress-color` and `--popup-shadow-color` are declared but not used by the +page, so changing them has no effect. + +The logo is `images/logo.svg`; put your own file at that path. The favicon is `images/favicon.svg`. + +What the theme cannot reach: the colors written inside the SVG files (the logo and the favicon gradient, the chevron and +the close button), the `theme-color` of the page and of `manifest.webmanifest`, and the image that is made for sharing +a result (`results/index.php`). Change those files themselves if you need them to match. + +This applies to the modern design only. The classic design and the stability page have their own styles. + +### Docker + +The container copies `/speedtest/frontend` to the web root every time it starts, so a theme has to be put in +`/speedtest/frontend`, not in `/var/www/html/frontend`. Mounting a file over a path in `/var/www/html` makes the start +fail, because the entrypoint empties that folder first. + +```sh +docker run -d -p 80:8080 -e MODE=standalone -e USE_NEW_DESIGN=true \ + -v $PWD/theme.css:/speedtest/frontend/styling/theme.css:ro \ + -v $PWD/logo.svg:/speedtest/frontend/images/logo.svg:ro \ + ghcr.io/librespeed/speedtest +``` + +To bake the theme into your own image instead of mounting it: + +```dockerfile +FROM ghcr.io/librespeed/speedtest +COPY theme.css /speedtest/frontend/styling/theme.css +COPY logo.svg /speedtest/frontend/images/logo.svg +``` + +The modern design is only served when `USE_NEW_DESIGN=true`. A change to a mounted file needs a restart of the +container, because the files are copied at start. + ## Notes - The modern frontend expects modern browser features and does not support old diff --git a/frontend/index.html b/frontend/index.html index 8a804d7..3662a0c 100755 --- a/frontend/index.html +++ b/frontend/index.html @@ -14,6 +14,7 @@ + LibreSpeed - Free and Open Source Speedtest diff --git a/frontend/styling/theme.css b/frontend/styling/theme.css new file mode 100644 index 0000000..22fd1b5 --- /dev/null +++ b/frontend/styling/theme.css @@ -0,0 +1,7 @@ +/* + * Branding of the modern design, for people who host LibreSpeed. + * + * This file is empty on purpose and loaded after index.css, so what you write here wins. Replace it, or mount your own + * file over it, to give your instance its own look. See "Theming" in frontend/README.md for the variables, the logo and + * the background image. + */ diff --git a/index-modern.html b/index-modern.html index a5285c8..1c16d80 100644 --- a/index-modern.html +++ b/index-modern.html @@ -17,6 +17,7 @@ + LibreSpeed - Free and Open Source Speedtest diff --git a/tests/docker-compose-playwright.yml b/tests/docker-compose-playwright.yml index e63a466..6dedd79 100644 --- a/tests/docker-compose-playwright.yml +++ b/tests/docker-compose-playwright.yml @@ -51,6 +51,9 @@ services: - WEBPORT=8080 - USE_NEW_DESIGN=true - "TAGLINE=It'd rather be fast!" + volumes: + # A host theme, mounted where the entrypoint copies the frontend from + - ./e2e/fixtures/theme-host.css:/speedtest/frontend/styling/theme.css:ro ports: - "18186:8080" diff --git a/tests/e2e/fixtures/theme-host.css b/tests/e2e/fixtures/theme-host.css new file mode 100644 index 0000000..f30eee6 --- /dev/null +++ b/tests/e2e/fixtures/theme-host.css @@ -0,0 +1,8 @@ +:root { + --theme-green: rgb(255, 138, 0); + --background-backup-color: rgb(16, 24, 32); +} + +html { + background-image: none; +} diff --git a/tests/e2e/static-repository-assets.spec.js b/tests/e2e/static-repository-assets.spec.js index bc91b29..c3a0fee 100644 --- a/tests/e2e/static-repository-assets.spec.js +++ b/tests/e2e/static-repository-assets.spec.js @@ -7,6 +7,7 @@ const expectedAssets = [ "/settings.json", "/server-list.json", "/frontend/styling/index.css", + "/frontend/styling/theme.css", "/frontend/javascript/index.js", "/frontend/images/logo.svg", "/frontend/images/favicon.svg", diff --git a/tests/e2e/theme.spec.js b/tests/e2e/theme.spec.js new file mode 100644 index 0000000..de03bd0 --- /dev/null +++ b/tests/e2e/theme.spec.js @@ -0,0 +1,70 @@ +const fs = require("node:fs"); +const path = require("node:path"); +const { test, expect } = require("@playwright/test"); +const { baseUrls } = require("./helpers/env"); + +const staticRepositoryUrl = "http://127.0.0.1:18184"; +const root = path.resolve(__dirname, "../.."); +const hostTheme = fs.readFileSync(path.join(__dirname, "fixtures/theme-host.css"), "utf8"); + +const tagline = page => page.locator("main > p.tagline"); +const color = locator => locator.evaluate(element => getComputedStyle(element).color); +const rootStyle = page => + page.evaluate(() => { + const style = getComputedStyle(document.documentElement); + return { image: style.backgroundImage, color: style.backgroundColor }; + }); + +test.describe("Host theme of the modern design", () => { + test("ships an empty theme.css that leaves the default look alone", async ({ page, request }) => { + const response = await request.get(`${staticRepositoryUrl}/frontend/styling/theme.css`); + expect(response.ok()).toBeTruthy(); + expect(await response.text()).not.toContain("{"); + + await page.goto(`${staticRepositoryUrl}/index-modern.html`); + expect(await color(tagline(page))).toBe("rgb(92, 249, 253)"); + expect((await rootStyle(page)).image).toContain("background.jpeg"); + }); + + test("a theme.css of the host changes the colors and the background", async ({ page }) => { + await page.route("**/frontend/styling/theme.css", route => + route.fulfill({ body: hostTheme, contentType: "text/css" }) + ); + await page.goto(`${staticRepositoryUrl}/index-modern.html`); + expect(await color(tagline(page))).toBe("rgb(255, 138, 0)"); + expect(await rootStyle(page)).toEqual({ image: "none", color: "rgb(16, 24, 32)" }); + }); + + test("a relative url in theme.css is relative to the theme.css", async ({ page }) => { + await page.route("**/frontend/styling/theme.css", route => + route.fulfill({ + body: 'html { background-image: url("../images/background-original.jpeg"); }', + contentType: "text/css" + }) + ); + const requested = page.waitForRequest("**/frontend/images/background-original.jpeg"); + await page.goto(`${staticRepositoryUrl}/index-modern.html`); + await requested; + }); + + test("both modern pages load theme.css after index.css", () => { + const link = (file, folder) => { + const html = fs.readFileSync(path.join(root, file), "utf8"); + return [html.indexOf(`${folder}index.css`), html.indexOf(`${folder}theme.css`)]; + }; + for (const [file, folder] of [ + ["index-modern.html", "frontend/styling/"], + ["frontend/index.html", "styling/"] + ]) { + const [index, theme] = link(file, folder); + expect(index, file).toBeGreaterThan(-1); + expect(theme, file).toBeGreaterThan(index); + } + }); + + test("a theme.css mounted in the Docker image is the one that is served", async ({ page }) => { + await page.goto(`${baseUrls.standaloneApostrophe}/index-modern.html`); + expect(await color(tagline(page))).toBe("rgb(255, 138, 0)"); + expect(await rootStyle(page)).toEqual({ image: "none", color: "rgb(16, 24, 32)" }); + }); +}); From 0c596d685c5797eb3c3e2ebc7130578767b25fc0 Mon Sep 17 00:00:00 2001 From: Eduardo Garcia Date: Sun, 25 Oct 2026 13:57:23 -0300 Subject: [PATCH 2/2] fix(theme): address review findings on the theme.css PR --- doc_docker.md | 2 +- frontend/README.md | 4 ++-- frontend/styling/colors.css | 1 + frontend/styling/server-selector.css | 2 +- tests/e2e/global-setup.js | 1 + 5 files changed, 6 insertions(+), 4 deletions(-) diff --git a/doc_docker.md b/doc_docker.md index 6937afc..e9dbc45 100755 --- a/doc_docker.md +++ b/doc_docker.md @@ -101,7 +101,7 @@ docker run -e MODE=standalone -e TELEMETRY=true -e ENABLE_ID_OBFUSCATION=true -e To give your instance its own colors, background and logo, put your own `theme.css` (and `logo.svg`) in `/speedtest/frontend/styling/` and `/speedtest/frontend/images/` of the container, either with a bind mount or with a `COPY` in your own image. Mount at `/speedtest/frontend`, not at `/var/www/html/frontend`: the entrypoint empties -`/var/www/html` and copies the frontend into it at every start. The modern design needs `USE_NEW_DESIGN=true`. The +`/var/www/html` and copies the frontend into it at every start. `USE_NEW_DESIGN=true` makes the modern design the default; `index-modern.html` and `?design=new` work without it. The variables and examples are in [frontend/README.md](frontend/README.md#theming). ## Multiple Points of Test diff --git a/frontend/README.md b/frontend/README.md index 6abd1cb..f92b5ea 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -39,7 +39,7 @@ html { The variables that change the look are the ones in `styling/colors.css`: the accent colors (`--theme-green`, `--theme-pink`), the texts (`--primary-text-color`, `--secondary-text-color`, `--tagline-text-color`, and the disabled ones), the background (`--background-backup-color`, `--background-overlay-color`), the start button -(`--button-*`), the server selector (`--server-selector-*`), the gauges (`--gauge-background-color`, +(`--button-*`), the server selector (`--server-selector-*`, which includes the text of the options), the gauges (`--gauge-background-color`, `--gauge-pointer-green`, `--gauge-pointer-pink`), ping and jitter (`--ping-and-jitter-*`) and the popups (`--popup-background-color`). `--gauge-progress-color` and `--popup-shadow-color` are declared but not used by the page, so changing them has no effect. @@ -73,7 +73,7 @@ COPY theme.css /speedtest/frontend/styling/theme.css COPY logo.svg /speedtest/frontend/images/logo.svg ``` -The modern design is only served when `USE_NEW_DESIGN=true`. A change to a mounted file needs a restart of the +`USE_NEW_DESIGN=true` makes the modern design the default; `index-modern.html` and `?design=new` work without it. A change to a mounted file needs a restart of the container, because the files are copied at start. ## Notes diff --git a/frontend/styling/colors.css b/frontend/styling/colors.css index 6a948d4..10b14ac 100644 --- a/frontend/styling/colors.css +++ b/frontend/styling/colors.css @@ -18,6 +18,7 @@ --button-shadow-color: #5cf9fd47; --button-disabled-background-color: #a2a2a2; + --server-selector-text-color: var(--primary-text-color); --server-selector-border-color: #625b6b; --server-selector-hover-border-color: var(--theme-green); --server-selector-background-color: #251b32; diff --git a/frontend/styling/server-selector.css b/frontend/styling/server-selector.css index e614d63..c4aca48 100644 --- a/frontend/styling/server-selector.css +++ b/frontend/styling/server-selector.css @@ -142,7 +142,7 @@ font-size: 2.4rem; font-weight: 700; letter-spacing: -0.2rem; - color: var(--sprint-text-color); + color: var(--server-selector-text-color); text-transform: uppercase; text-decoration: none; text-align: left; diff --git a/tests/e2e/global-setup.js b/tests/e2e/global-setup.js index b95b178..19f1195 100644 --- a/tests/e2e/global-setup.js +++ b/tests/e2e/global-setup.js @@ -68,6 +68,7 @@ module.exports = async () => { const timeoutMs = 180_000; await waitForReady('standalone', 'http://127.0.0.1:18180/index.html', timeoutMs); await waitForReady('standalone-new', 'http://127.0.0.1:18185/index.html', timeoutMs); + await waitForReady('standalone-apostrophe', 'http://127.0.0.1:18186/index.html', timeoutMs); await waitForReady('standalone-alpine', 'http://127.0.0.1:18187/index.html', timeoutMs); await waitForReady('backend', 'http://127.0.0.1:18181/empty.php', timeoutMs); await waitForReady('frontend', 'http://127.0.0.1:18182/index-modern.html', timeoutMs);