From e52fcda7c3baf30ccaff9926fdea32579d98201a Mon Sep 17 00:00:00 2001 From: Stefan Stidl Date: Sun, 26 Apr 2026 14:23:09 +0200 Subject: [PATCH] docs: update install instructions (closes #790) --- README.md | 5 ++- doc.md | 15 ++++++-- frontend/README.md | 94 +++++++--------------------------------------- 3 files changed, 27 insertions(+), 87 deletions(-) diff --git a/README.md b/README.md index 1ff5f72..00c21e0 100755 --- a/README.md +++ b/README.md @@ -40,9 +40,10 @@ Works with mobile versions too. Assuming you have PHP and a web server installed, the installation steps are quite simple. 1. Download the source code and extract it -1. Copy the following files to your web server's shared folder (ie. /var/www/html/speedtest for Apache): index.html, speedtest.js, speedtest_worker.js, favicon.ico and the backend folder +1. Copy the project files to your web server's shared folder (ie. `/var/www/html/speedtest` for Apache). For the current layout, the web root should contain `index.html`, `index-classic.html`, `index-modern.html`, `design-switch.js`, `config.json`, `speedtest.js`, `speedtest_worker.js`, `favicon.ico`, and the `backend` folder. +1. Also copy the contents of `frontend/` into the same web root so the modern UI assets end up in `styling/`, `javascript/`, `images/`, and `fonts/` next to the HTML files. 1. Optionally, copy the results folder too, and set up the database using the config file in it. -1. Be sure your permissions allow execute (755). +1. Be sure your permissions allow read and execute access where needed. 1. Visit YOURSITE/speedtest/index.html and voila! ### Installation Video diff --git a/doc.md b/doc.md index 2224b74..1690ac8 100755 --- a/doc.md +++ b/doc.md @@ -174,18 +174,25 @@ Requirements: * FreeType 2 and its PHP module * The PHP gd library -To install the speed test frontend, copy the following files to your web server: +To install the speed test frontend, copy the project files to your web server and keep the modern UI assets next to the HTML files: +* `index.html` +* `index-classic.html` +* `index-modern.html` +* `design-switch.js` +* `config.json` * `speedtest.js` * `speedtest_worker.js` +* `favicon.ico` +* the `backend` folder +* the contents of `frontend/`, copied so `styling/`, `javascript/`, `images/`, and `fonts/` sit next to the HTML files * Optionally, the `results` folder -* `index.html` (or one of the example UIs in the `examples` folder) -__Important:__ The speed test needs write permissions in the installation folder! +__Important:__ The speed test needs read and execute permissions in the installation folder where applicable! ##### Server list -Edit `index.html` and uncomment the list of servers: +Edit `index-classic.html` and uncomment the list of servers: ```js var SPEEDTEST_SERVERS=[ diff --git a/frontend/README.md b/frontend/README.md index dc5ed71..60566ce 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,90 +1,22 @@ # LibreSpeed frontend -This is a re-implementation of the LibreSpeed user interface based on [the -design by fromScratch](https://github.com/librespeed/speedtest/issues/585). The -code that's doing the actual speed test is still the same. +This directory contains the modern LibreSpeed UI assets. -### Desktop +## Deployment -![Desktop screenshot](./screenshots/desktop.png) - -### Mobile - -![Mobile screenshot](./screenshots/mobile.png) - -## How to use - -Copy everything in this directory into the LibreSpeed root, next to -`speedtest.js` and `speedtest_worker.js`, overwriting the `index.html` file that -may already be there. That's it! +For installation and deployment, follow the top-level [README.md](../README.md) +and [DESIGN_SWITCH.md](../DESIGN_SWITCH.md). In non-Docker deployments, the +contents of this directory must be copied so `styling/`, `javascript/`, +`images/`, and `fonts/` sit next to the root HTML files. ## Configuration -In the [`server-list.json`](./server-list.json) file you can provide a list of -testing servers. If you only have a single testing server, just provide a list -with one item in it, being your server. The frontend will then skip doing an -automatic server selection and will not allow the user to change servers. +- `server-list.json` contains the default server list used by the modern UI. +- `settings.json` overrides selected `speedtest_worker.js` settings. +- `index.html` and `index-modern.html` show how the frontend is wired up. -If you want to load the server list from a different URL, change the -`SPEEDTEST_SERVERS` variable in `index-modern.html` before -`javascript/index.js` is loaded. For example: +## Notes -```html - - -``` - -You can also provide a relative URL, for example -`var SPEEDTEST_SERVERS = "/speedtest/servers.json";`. - -For more advanced applications, you can override any of the settings that are -defined in `speedtest_worker.js` using the file -[`settings.json`](./settings.json). See -[`speedtest_worker.js`](../speedtest_worker.js) for documentation on the -different settings (scroll down a bit to where you find the definition of the -`settings` object). - -## Features - -- Shows upload and download speed and progress -- Shows ping and jitter -- Shows your IP address and internet service provider if the testing server - supports it -- Can handle a single testing server or a list of servers -- Can save telemetry and share results if the hosting server supports it (set - `telemetry_level` in [`settings.json`](./settings.json)) -- Does not require any build steps; implementation is pure JS & CSS -- Has zero dependencies - -## Limitations - -- This frontend relies heavily on modern browser features. It should work very - well in all modern ("evergreen") browsers, but has **no** backwards compatibility - with older browsers. - -## Credits - -**Design** by fromScratch Studio - 2022, 2023 -([www.fromscratch.io](https://www.fromscratch.io)) - -> "During Hacktoberfest 2022 & 2023, fromScratch Studio took on the request for -> LibreSpeed redesign and UI improvements. We ran 2 design sprints one on '22 and -> one on '23, and produced high-fidelity screens for LibreSpeed redesign. -> Furthermore, this year, we produced high-fidelity screens for mobile-view as -> well." - -_-- Chris-ZoGo, https://github.com/librespeed/speedtest/issues/585_ - -**Implementation** by Timendus - 2024 -([https://github.com/Timendus](https://github.com/Timendus)) - -> "I had a couple of days of free time, and I came across the design by -> fromScratch. I thought it looked great, and that it deserved a good -> implementation, so I set out to make one. I've taken the liberty of changing a -> couple of details, coming up with some animations and adding a few small -> features, but otherwise I've tried to stay as close to the "intention" of the -> design as I could." - -_-- Timendus, https://github.com/librespeed/speedtest/pull/649_ +- The modern frontend expects modern browser features and does not support old + browsers. +- This directory does not contain the backend or results-sharing files.