Server side, you'll need:
- Apache 2 (nginx and IIS also supported). A fast internet connection is required (possibly gigabit), and the web server must accept large POST requests (up to 20MB)
- PHP 5.4 or newer, a 64-bit version is strongly recommended
- OpenSSL and its PHP module (this is usually installed automatically by most distros)
- If you want to store test results (telemetry), one of the following:
- MySQL/MariaDB and its PHP PDO module
- PostgreSQL and its PHP PDO module
- SQLite 3 and its PHP PDO module
- If you want to enable results sharing:
- FreeType 2 and its PHP module (this is usually installed automatically by most distros)
Let's install the speedtest.
Put all files on your web server via FTP or by copying them directly. You can install it in the root, or in a subdirectory.
Important: The speedtest needs write permissions in the installation folder!
ipinfo.io
The speedtest uses ipinfo.io to detect ISP and distance from server. This is completely optional and can be disabled if you want (see Speedtest settings), but it is enabled by default, and if you expect more than ~500 tests per day, you will need to sign up to ipinfo.io and edit backend/getIP_ipInfo_apikey.php to set your access token.
IpInfo.io has kindly offered free access to their APIs for users of this project; if you're interested, contact me at info@fdossena.com and provide a description of what you intend to do with the project, and you'll get the API key.
Telemetry and results sharing
The test supports storing test results and can generate shareable images that users can embed in forum signatures and such.
To use this function, you will need a database. The test supports MySQL, PostgreSQL and SQLite as backends.
Creating the database
This step is only required for MySQL and PostgreSQL. If you want to use SQLite, skip to the next step.
Log into your database using phpMyAdmin or a similar software and create a new database. Inside the results folder you will find telemetry_mysql.sql and telemetry_postgresql.sql, which are templates for MySQL and PostgreSQL respectively. Import the one you need, and you will see a speedtest_users table in the database. You can delete the templates afterwards.
Configuring telemetry
Open results/telemetry_settings.php in a text editor. Set $db_type to either mysql,postgresql or sqlite.
If you chose to use SQLite, you might want to change $Sqlite_db_file to another path where you want the database to be stored. Just make sure that the file cannot be downloaded by users. Sqlite doesn't require any additional configuration, you can skip the rest of this section.
If you chose to use MySQL, you must set your database credentials:
$MySql_username="USERNAME"; //your database username
$MySql_password="PASSWORD"; //your database password
$MySql_hostname="DB_HOSTNAME"; //database address, usually localhost
$MySql_databasename="DB_NAME"; //the name of the database where you loaded telemetry_mysql.sql
If you chose to use PostgreSQL, you must set your database credentials:
$PostgreSql_username="USERNAME"; //your database username
$PostgreSql_password="PASSWORD"; //your database password
$PostgreSql_hostname="DB_HOSTNAME"; //database address, usually localhost
$PostgreSql_databasename="DB_NAME"; //the name of the database where you loaded telemetry_postgresql.sql
Results sharing
This feature generates an image that can be share by the user containing the download, upload, ping, jitter and ISP (if enabled).
By default, the telemetry generates a progressive ID for each test. Even if no sensitive information is leaked, you might not want users to be able to guess other test IDs. To avoid this, you can turn on ID obfuscation, which turns IDs into a reversible hash, much like YouTube video IDs.
To enable ID obfuscation, edit results/telemetry_settings.php and set $enable_id_obfuscation to true. From now on, all test IDs will be obfuscated using a unique salt. The IDs in the database are still progressive, but users will only know their obfuscated versions and won't be able to easily guess other IDs.
Important: ID obfuscation currently only works on 64-bit PHP!
While you're editing results/telemetry_settings.php, you might want to set $redact_ip_addresses to true, this way, all IP addresses will be removed from the telemetry for better privacy. This is disabled by default.
Seeing the results
A basic front-end for visualizing and searching tests by ID is available in results/stats.php.
A login is required to access the interface. Important: change the default password in results/telemetry_settings.php.
The end
Now that the test is installed, rename one of the examples to index.html and delete the other examples.
The best starting point for most people is example-singleServer-pretty.html. If you want to use telemetry and results sharing, use example-singleServer-full.html instead.
If you're not using telemetry and results sharing, you can delete the results folder too.
Details about the examples and how to make custom UIs will be discussed here. If you don't want to make a custom UI, feel free to modify the example and replace "LibreSpeed Example" with the name of your test.
Privacy
Telemetry contains personal information (according to GDPR defintion), therefore it is important to treat this data respectfully of national and international laws, especially if you plan to offer the service in the European Union.
example-singleServer-full.html and example-multipleServers-full.html both contain a privacy policy for the service: you MUST read it, change it if necessary, and add your email address for data deletion requests. Failure to comply with GDPR regulations can get you in serious trouble.