diff --git a/.gitbook/assets/cf-tunnel.png b/.gitbook/assets/cf-tunnel.png new file mode 100644 index 0000000..80eafb3 Binary files /dev/null and b/.gitbook/assets/cf-tunnel.png differ diff --git a/.gitbook/assets/dashboard.png b/.gitbook/assets/dashboard.png new file mode 100644 index 0000000..d0f172c Binary files /dev/null and b/.gitbook/assets/dashboard.png differ diff --git a/.gitbook/assets/dashboard_screenshot.jpg b/.gitbook/assets/dashboard_screenshot.jpg deleted file mode 100644 index 4a12994..0000000 Binary files a/.gitbook/assets/dashboard_screenshot.jpg and /dev/null differ diff --git a/.gitbook/assets/db_notification.png b/.gitbook/assets/db_notification.png index 8fd19c6..68116c5 100644 Binary files a/.gitbook/assets/db_notification.png and b/.gitbook/assets/db_notification.png differ diff --git a/.gitbook/assets/influxdb2_settings.png b/.gitbook/assets/influxdb2_settings.png deleted file mode 100644 index 55d0ce8..0000000 Binary files a/.gitbook/assets/influxdb2_settings.png and /dev/null differ diff --git a/.gitbook/assets/influxdbv2_settings.png b/.gitbook/assets/influxdbv2_settings.png new file mode 100644 index 0000000..6661161 Binary files /dev/null and b/.gitbook/assets/influxdbv2_settings.png differ diff --git a/.gitbook/assets/mail_notification.png b/.gitbook/assets/mail_notification.png index e15973d..0281aba 100644 Binary files a/.gitbook/assets/mail_notification.png and b/.gitbook/assets/mail_notification.png differ diff --git a/.gitbook/assets/openapi.json b/.gitbook/assets/openapi.json new file mode 100644 index 0000000..f66c53c --- /dev/null +++ b/.gitbook/assets/openapi.json @@ -0,0 +1,51 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Speedtest Tracker API", + "version": "1.0.0" + }, + "paths": { + "/api/v1/results/latest": { + "get": { + "description": "Get the latest result.", + "operationId": "4b44d6935caeb91d3e687ab4bc176f62", + "responses": { + "200": { + "description": "OK" + }, + "404": { + "description": "No result found" + } + } + } + }, + "/api/v1/results": { + "get": { + "description": "List results.", + "operationId": "32a45ba8e8e9a81955a178ae686273ce", + "responses": { + "200": { + "description": "OK" + }, + "422": { + "description": "Unprocessable Entity" + } + } + } + }, + "/api/v1/results/{id}": { + "get": { + "description": "Get result.", + "operationId": "bc182a4008f0ff94a6318893359f3adc", + "responses": { + "200": { + "description": "OK" + }, + "404": { + "description": "Result not found" + } + } + } + } + } +} \ No newline at end of file diff --git a/.gitbook/assets/prometheus_settings.png b/.gitbook/assets/prometheus_settings.png new file mode 100644 index 0000000..a4d97fb Binary files /dev/null and b/.gitbook/assets/prometheus_settings.png differ diff --git a/.gitbook/assets/webhook_notification.png b/.gitbook/assets/webhook_notification.png new file mode 100644 index 0000000..04c1783 Binary files /dev/null and b/.gitbook/assets/webhook_notification.png differ diff --git a/README.md b/README.md index 8f12cb0..1875132 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,21 @@ --- description: >- - A Docker image to check your internet speed using Ookla's Speedtest service. - Build using Laravel and the Speedtest CLI. + Speedtest Tracker is a self-hosted application that monitors the performance + and uptime of your internet connection. Build using Laravel and Speedtest CLI + from Ookla®, deployable with Docker. --- # Introduction {% hint style="info" %} -Docs are up to date through version: `0.17.x` +Docs are up-to-date through version: `v1.13.x` {% endhint %} -
- -### Introduction - -Speedtest Tracker is a self-hosted internet performance tracking application that runs speedtest checks against Ookla's Speedtest service. +
#### Why might I want this? -The main use case for Speedtest Tracker is to build a history of your internet's performance so that you can be informed when you're not receiving your ISP's advertised rates. +The main use case for Speedtest Tracker is to build a history of your internet performance and ISP's uptime so you can be informed when you're not receiving your ISP's advertised rates. _...also some of us just like a lot of data._ @@ -28,4 +25,4 @@ As far as I can tell [https://github.com/henrywhitaker3/Speedtest-Tracker](https #### Do you have a demo? -No, but [DB Tech](https://www.youtube.com/watch?v=feArak6WCLw) and [Awesome Opens Source](https://www.youtube.com/watch?v=iyRUj77cjKg) over on YouTube have awesome videos showing you how to get Speedtest Tracker up and running with and a quick demo. +No, but [DB Tech](https://www.youtube.com/watch?v=feArak6WCLw), [Awesome Opens Source](https://www.youtube.com/watch?v=iyRUj77cjKg) and [Techdox](https://www.youtube.com/watch?v=vZiaWyuqsaY) over on YouTube have awesome videos showing you how to get Speedtest Tracker up and running with and a quick demo. diff --git a/SUMMARY.md b/SUMMARY.md index d877a81..9f02157 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -7,13 +7,14 @@ ## 🚀 Getting Started * [Installation](getting-started/installation/README.md) - * [Using Docker or Docker Compose](getting-started/installation/installation.md) - * [Using Kubernetes](getting-started/installation/kubernetes.md) - * [Using QNAP](getting-started/installation/qnap.md) - * [Using Synology](getting-started/installation/synology.md) - * [Using Unraid](getting-started/installation/unraid.md) -* [Database Drivers](getting-started/database-drivers.md) + * [Using Docker Compose](getting-started/installation/using-docker-compose.md) + * [Using Docker](getting-started/installation/using-docker.md) + * [Using Kubernetes](getting-started/installation/using-kubernetes.md) + * [Using QNAP](getting-started/installation/using-qnap.md) + * [Using Synology](getting-started/installation/using-synology.md) + * [Using Unraid](getting-started/installation/using-unraid.md) * [Environment Variables](getting-started/environment-variables.md) +* [Database Drivers](getting-started/database-drivers.md) ## 🆘 Help @@ -24,29 +25,47 @@ * [Authentication](security/authentication.md) * [Authorization](security/authorization.md) +* [Encryption](security/encryption.md) ## ⚙️ Settings * [Data Integrations](settings/data-platforms/README.md) - * [InfluxDB2](settings/data-platforms/influxdb2.md) + * [InfluxDB v2](settings/data-platforms/influxdb2.md) + * [Prometheus](settings/data-platforms/prometheus.md) * [Notifications](settings/notifications/README.md) + * [Apprise](settings/notifications/apprise.md) * [Database](settings/notifications/database.md) * [Mail](settings/notifications/mail.md) - * [Telegram](settings/notifications/telegram.md) + * [Webhook](settings/notifications/webhook.md) ## 👀 Other -* [Caching](other/caching.md) +* [Speedtest Process](other/speedtest-process.md) +* [Proxies](other/proxies/README.md) + * [Cloudflare Tunnel (Zero Trust)](other/proxies/cloudflare-tunnel-zero-trust.md) + * [Traefik](other/proxies/traefik.md) + * [Tailscale](other/proxies/tailscale.md) + * [Nginx](other/proxies/nginx.md) * [Commands](other/commands.md) * [Data Dictionary](other/data-dictionary.md) * [Embed Dashboard](other/embed-dashboard.md) * [Health Check](other/health-check.md) -* [Stream Deck](other/stream-deck.md) +* [Community Projects](other/community-projects.md) ## 🖥️ API -* [Getting Started](api/getting-started.md) -* [Latest Result](api/latest-result.md) +* [Authorization](api/authorization.md) +* [Responses](api/responses/README.md) + * ```yaml + props: + models: true + type: builtin:openapi + dependencies: + spec: + ref: + kind: openapi + spec: speedtest-tracker-api + ``` ## 🤹 Contributing @@ -57,5 +76,5 @@ * [Source Code](https://github.com/alexjustesen/speedtest-tracker) * [Releases](https://github.com/alexjustesen/speedtest-tracker/releases) * [Update the Docs](https://github.com/alexjustesen/speedtest-tracker-docs) -* [About Me](https://alexjustesen.com/?utm\_campaign=oss-projects\&utm\_source=speedtest-tracker-docs\&utm\_medium=textlink) +* [About Me](https://alexjustesen.com/?utm_campaign=oss-projects\&utm_source=speedtest-tracker-docs\&utm_medium=textlink) * [Donate](https://github.com/sponsors/alexjustesen) diff --git a/api/authorization.md b/api/authorization.md new file mode 100644 index 0000000..1fad05d --- /dev/null +++ b/api/authorization.md @@ -0,0 +1,14 @@ +# Authorization + +A "Bearer Token" is required to authenticate into the API, you can generate tokens for your user account on `/admin/api-tokens`. + +### Token Abilities + +Each token is provisioned with one or more abilities. When calling an endpoint, the token must include the ability required by that endpoint + +| Abilities | Description | +| ------------- | ------------------------------- | +| Read Results | Allows token to read results. | +| Run Speedtest | Allows token to run speedtests. | +| List servers | Allows token to list servers. | + diff --git a/api/getting-started.md b/api/getting-started.md deleted file mode 100644 index a9a0ff3..0000000 --- a/api/getting-started.md +++ /dev/null @@ -1,5 +0,0 @@ -# Getting Started - -### Postman Collection - -A [Postman](https://www.postman.com/) collection can be found in the [repository](https://github.com/alexjustesen/speedtest-tracker/blob/main/%F0%9F%90%87%20Speedtest%20Tracker.postman\_collection.json) to test all API endpoints. diff --git a/api/latest-result.md b/api/latest-result.md deleted file mode 100644 index c926218..0000000 --- a/api/latest-result.md +++ /dev/null @@ -1,43 +0,0 @@ -# Latest Result - -### Legacy Endpoints - -#### Authentication - -No authentication required. - -{% swagger method="get" path="" baseUrl="/api/speedtest/latest" summary="Get the latest speedtest result" expanded="false" %} -{% swagger-description %} -Provides backwards compatibility for [Homepage](https://github.com/benphelps/homepage) and [Organizr](https://github.com/causefx/Organizr) home lab dashboards. -{% endswagger-description %} - -{% swagger-response status="200: OK" description="" %} -```javascript -{ - "message": "ok", - "data": { - "id": 1, - "ping": 11.111, - "download": 694.20, - "upload": 420.69, - "server_id": 12345, - "server_host": "host.of.server.com", - "server_name": "Name of Server", - "url": "https://www.speedtest.net/result/c/slug-to-results", - "scheduled": false, - "failed": true, - "created_at": "2023-03-10T13:17:46.000000Z", - "updated_at": "2023-03-10T13:17:46.000000Z" - } -} -``` -{% endswagger-response %} - -{% swagger-response status="404: Not Found" description="" %} -```javascript -{ - "message": "No results found." -} -``` -{% endswagger-response %} -{% endswagger %} diff --git a/api/responses/README.md b/api/responses/README.md new file mode 100644 index 0000000..6b32fe1 --- /dev/null +++ b/api/responses/README.md @@ -0,0 +1,2 @@ +# Responses + diff --git a/changelog.md b/changelog.md index 0ce6be5..2126209 100644 --- a/changelog.md +++ b/changelog.md @@ -8,28 +8,3 @@ description: Important milestones in the project. A complete history of all changes can be found on GitHub in the [releases](https://github.com/alexjustesen/speedtest-tracker/releases). {% endhint %} -### 2024 - -#### Feb. 19th, 2024 - Data Quality Release - -`v0.16.0` fixes a hand full of data quality issues that have been around for a while and also adds some nice new features like a more robust export method and automatic pruning of older results. - -Read more: [https://github.com/alexjustesen/speedtest-tracker/releases/tag/v0.16.0](https://github.com/alexjustesen/speedtest-tracker/releases/tag/v0.16.0) - -#### Feb. 9th, 2024 - LinuxServer.io Docker image now available! - -The fantastic gents over at [LinuxServer.io](https://www.linuxserver.io/) have build an [image](https://fleet.linuxserver.io/image?name=linuxserver/speedtest-tracker) that is 3-4x faster and 1/2 the build size of the current image! For more details check out the published [issue](https://github.com/alexjustesen/speedtest-tracker/issues/1117) on GitHub. - -*** - -### 2023 - -🤷‍♂️ I did a lot, just haven't filled this in yet. - -*** - -### 2022 - -#### Sep. 13th, 2022 - First release! - -Where it all [started](https://github.com/alexjustesen/speedtest-tracker/releases/tag/v0.1.0-alpha.1). diff --git a/contributing/development-environment.md b/contributing/development-environment.md index a5c4e71..03c5742 100644 --- a/contributing/development-environment.md +++ b/contributing/development-environment.md @@ -20,10 +20,10 @@ These directions assume you have a working knowledge of the Laravel framework. I #### 1. Clone the repository -First let's clone the [repository](https://github.com/alexjustesen/speedtest-tracker) to your machine, I prefer [GitHub's CLI](https://cli.github.com/) so that command is included below. +First let's clone the [repository](https://github.com/alexjustesen/speedtest-tracker) to your machine. ```bash -gh repo clone alexjustesen/speedtest-tracker \ +git clone git@github.com:alexjustesen/speedtest-tracker \ && cd speedtest-tracker ``` @@ -35,17 +35,20 @@ Next we need to make a copy of `.env.example`, the environment file is what Lara cp .env.example .env ``` -You'll also want to fill in a few `DB_` variables here as well which will control which database Laravel will use. I've included MySQL as the default database for the development environment. +You will copy and fill in the following Environment Variables ``` -DB_CONNECTION=mysql -DB_HOST=mysql -DB_PORT=3306 -DB_DATABASE=speedtest_tracker -DB_USERNAME=sail -DB_PASSWORD=password +APP_NAME="Speedtest Tracker" +APP_ENV=local +APP_KEY= +APP_DEBUG=false +APP_TIMEZONE=UTC ``` +{% hint style="info" %} +Generate the APP\_KEY at with the command; `echo -n 'base64:'; openssl rand -base64 32;` +{% endhint %} + #### 3. Install Composer dependencies We'll use a temporary container to install the Composer dependencies for the application. @@ -55,7 +58,7 @@ docker run --rm \ -u "$(id -u):$(id -g)" \ -v "$(pwd):/var/www/html" \ -w /var/www/html \ - laravelsail/php82-composer:latest \ + laravelsail/php83-composer:latest \ composer install --ignore-platform-reqs ``` @@ -81,20 +84,47 @@ To start up the environment we can now use the Sail binary that is included with sail up -d ``` -#### 6. Installing the application +#### 6. Create the database + +To start up the environment we need to make a database + +```bash +touch database/database.sqlite +``` -Once the environment is setup you can install a fresh version of the application by running the following command. Keep in mind this WILL refresh the entire database. +As well need to make the needed tables etc in the database. ```bash -./vendor/bin/sail artisan app:install --force +./vendor/bin/sail artisan migrate:fresh --force # or if you have a Sail alias setup... -sail artisan app:install --force +sail artisan migrate:fresh --force ``` -{% hint style="info" %} -You can reset your development environment at any time by running the `app:install` command. -{% endhint %} +#### 7. Installing NPM assets + +We will need to install the needed NPM assets + +```bash +./vendor/bin/sail npm install && ./vendor/bin/sail npm run build + +# or if you have a Sail alias setup... +sail npm install && sail npm run build + +``` + +*** + +### Reset your development environment + +You can reset your development environment at any time by re-running a fresh migration: + +```bash +./vendor/bin/sail artisan migrate:fresh --force + +# or if you have a Sail alias setup... +sail artisan migrate:fresh --force +``` *** @@ -113,7 +143,7 @@ sail artisan queue:work ### Lint your code before opening a PR or committing changes -To keep PHP's code style consistant across multiple contributors a successful lint workflow is required to pass. Check your code quality locally by running the commnand below and fixing it's recommendations. +To keep PHP's code style consistent across multiple contributors a successful lint workflow is required to pass. Check your code quality locally by running the command below and fixing it's recommendations. ```bash ./vendor/bin/sail bin duster lint --using=pint -v diff --git a/features.md b/features.md index 2aab85d..20da87e 100644 --- a/features.md +++ b/features.md @@ -4,6 +4,4 @@ description: A full list of implemented features and those that are planned. # Features -
Dashboard page

Dashboard page

- -
FeaturesStatus
Install options
Docker images for x86Done
Docker images for arm64Done
unRAID Community AppDone
Dashboard
Show the most recent resultsDone
Pretty graphsDone
Results
History of failed and successful resultsDone
Filter by scheduled and successfulDone
Export selected results to CSVDone
Speedtest options
Scheduled testsDone
Adhoc testDone
Manually specify a serverDone
Manually specify a list of serversDone
Threshold alertsDone
Ping options
Ping a domain or list of domainsPlanned
Database support
SQLite (default)Done
MariaDB / MySQLDone
PostgresqlDone
InfluxDB v1Planned
InfluxDB v2Done
PrometheusPlanned
Notification Channels
In-appDone
MailDone
DiscordPlanned
GotifyPlanned
SlackPlanned
TelegramDone
WebhooksDone
Application Monitoring
https://ohdear.app/Planned
https://thenping.me/Planned
https://healthchecks.io/Planned
Other
Backup / RestorePlanned
Import data from https://github.com/henrywhitaker3/Speedtest-TrackerPlanned
+
FeaturesStatus
Install options
Docker images for x86Done
Docker images for arm64Done
unRAID Community AppDone
Dashboard
Show the most recent resultsDone
Pretty graphsDone
Results
History of failed and successful resultsDone
Filter by scheduled and successfulDone
Export selected results to CSVDone
Speedtest options
Scheduled testsDone
Adhoc testDone
Manually specify a serverDone
Manually specify a list of serversDone
Threshold alertsDone
Ping options
Ping a domain or list of domainsPlanned
Database support
SQLite (default)Done
MariaDB / MySQLDone
PostgresqlDone
InfluxDB v2Done
PrometheusDone
Notification Channels
In-appDone
MailDone
WebhooksDone
AppriseDone
Application Monitoring
https://ohdear.app/Planned
https://thenping.me/Planned
https://healthchecks.io/Planned
diff --git a/getting-started/database-drivers.md b/getting-started/database-drivers.md index 720e3cb..af9287f 100644 --- a/getting-started/database-drivers.md +++ b/getting-started/database-drivers.md @@ -8,7 +8,9 @@ description: >- Since Speedtest Tracker is built on the Laravel Framework any of the framework's supported database [drivers](https://laravel.com/docs/10.x/database#configuration) are also supported. -SQLite ships as the default driver but you can also use MySQL/MariaDB and Postgres. While SQL Server is supported by Laravel it hasn't been tested with Speedtest Tracker so no support will be provided for that driver. +SQLite ships as the default driver but you can also use MySQL/MariaDB/Postgres. + +> While SQL Server is supported by Laravel it hasn't been tested with Speedtest Tracker so no support will be provided for that driver. *** @@ -16,31 +18,33 @@ SQLite ships as the default driver but you can also use MySQL/MariaDB and Postgr #### SQLite (Default) -SQLite is a good option for simple installs and only not recommended because I think separating your application and the database into separate services is a better idea. - -To use SQLite follow the steps below to create your database file: - -1. Create a volume called `speedtest-tracker` or mount a directory to the container. -2. Create a file called `database.sqlite`, you can do this by running `touch database.sqlite` in the mounted volume or create it in the mounted directory. -3. Update your environment variables to only include the following environment variable in the table below. -4. On start-up the container will checked for the database on the file system, if it can find it errors will be thrown to the log. +SQLite is a good option for simple installs. The database will be create automatically inside the docker volume. | Environment Variable | Value | | -------------------- | -------- | | `DB_CONNECTION` | `sqlite` | -#### MySQL/MariaDB +#### MariaDB + +| Environment Variable | Value | +| -------------------- | -------------------------------------------------------- | +| `DB_CONNECTION` | `mariadb` | +| `DB_HOST` | The FQDN or address to the database instance. | +| `DB_PORT` | `3306` is the default port but can depend on your setup. | +| `DB_DATABASE` | Name of the database you'll connect to. | +| `DB_USERNAME` | User that'll be used to connect to the database. | +| `DB_PASSWORD` | Password for the user above. | -MariaDB ships as the default database that's included in the `docker-compose.yml` configuration, it's functionally the same as MySQL just an open-source earlier fork. +#### MySQL -| Environment Variable | Value | -| -------------------- | -------------------------------------------------------------------------------------------------------------- | -| `DB_CONNECTION` |

mysql

The mysql driver can be used for both MySQL and MariaDB.

| -| `DB_HOST` | The FQDN or address to the database instance. | -| `DB_PORT` | `3306` is the default port but can depend on your setup. | -| `DB_DATABASE` | Name of the database you'll connect to. | -| `DB_USERNAME` | User that'll be used to connect to the database. | -| `DB_PASSWORD` | Password for the user above. | +| Environment Variable | Value | +| -------------------- | -------------------------------------------------------- | +| `DB_CONNECTION` | `mysql` | +| `DB_HOST` | The FQDN or address to the database instance. | +| `DB_PORT` | `3306` is the default port but can depend on your setup. | +| `DB_DATABASE` | Name of the database you'll connect to. | +| `DB_USERNAME` | User that'll be used to connect to the database. | +| `DB_PASSWORD` | Password for the user above. | #### Postgres @@ -52,3 +56,4 @@ MariaDB ships as the default database that's included in the `docker-compose.yml | `DB_DATABASE` | Name of the database you'll connect to. | | `DB_USERNAME` | User that'll be used to connect to the database. | | `DB_PASSWORD` | Password for the user above. | +| `DB_SEARCH_PATH` | To change the database schema used by Postgres. | diff --git a/getting-started/environment-variables.md b/getting-started/environment-variables.md index ed5fa9d..c1eba47 100644 --- a/getting-started/environment-variables.md +++ b/getting-started/environment-variables.md @@ -1,3 +1,29 @@ +--- +description: >- + A complete inventory of all environment variables for configuring Speedtest + Tracker. +--- + # Environment Variables -
NameDescription
PUID

(required)		Used to set the user the container should run as.

- Default:1000
PGID

(required)		Used to set the group the container should run as.

- Default:1000
APP_NAMEUsed to define the application's name in the dashboard and in notifications.
FAQ
APP_KEY

Key used to encrypt and decrypt data. To create your own key to persist runphp artisan key:generate --showfrom within the running container.

Make sure to include the prependedbase64:prefix.

CONTENT_WIDTHWidth of the content section of each page. Can be set to any value found in the Filamentdocs.

- Default:7xl
PUBLIC_DASHBOARDEnables the public dashboard for guest (unauthenticated) users.

- Default:false
DASHBOARD_POLLINGFrequency charts and stats refresh on the dashboard. Can be represented using a string in seconds orfalseto disable.

- Default:60s
NOTIFICATION_POLLINGFrequency database notifications are polled. Can be represented using a string in seconds orfalseto disable.

- Default:60s
RESULTS_POLLINGFrequency data refreshes in the results table. Can be represented using a string in seconds orfalseto disable.

- Default:false
MAIL_ENCRYPTIONMail encryption used for sending test results and notifications trough email.
Can besslortls
MAIL_FROM_ADDRESSEmail address used for sending test results and notifications trough email.
MAIL_FROM_NAMEName used for sending test results and notifications trough email.
MAIL_HOSTSMTP server used for sending test results and notifications trough email.
MAIL_MAILEREmail protocol used for sending test results and notifications trough email.
MAIL_PASSWORDSMTP password from email address used for sending test results and notifications trough email.
MAIL_PORTSMTP port from email server used for sending test results and notifications trough email.
MAIL_USERNAMEUsername from SMTP server used for sending test results and notifications trough email.
TZTime zone used to get the date and time of tests
APP_URLURL used on emails sent.
That URL is the one that appears on links that are sent trough emailFAQ
+### Application + +
NameRequiredDescriptionExample
PUIDtrueUsed to set the user the container should run as.1000
PGIDtrueUsed to set the group the container should run as.1000
APP_KEYtrueKey used to encrypt and decrypt data. See the install docs to generate a key.
APP_URLtrueURL used for links in emails and notifications.https://speedtest.example.com
APP_NAMEfalseUsed to define the application's name in the dashboard and in notifications.
ADMIN_NAMEfalseName of the initial admin user.
Note: Only effective during initial setup.		Admin
ADMIN_EMAILfalseEmail of the initial admin user.
Note: Only effective during initial setup.		admin@example.com
ADMIN_PASSWORDfalsePassword of the initial admin user.
Note: Only effective during initial setup.		password
ASSET_URLfalseURL used for assets, needed when using a reverse proxy.https://speedtest.example.com
APP_LOCALEfalseChange the default language.
APP_TIMEZONEfalseApplication timezone should be set if your database does not use UTC as its default timezone.Europe/London
ALLOWED_IPSfalseBlock requests to the application unless from the allowed addresses.127.0.0.1,127.0.0.2
+ +*** + +### Display + +
NameRequiredDescriptionExample
CHART_BEGIN_AT_ZEROfalseBegin the dashboard axis charts at zero.

- Default: true		true or false
CHART_DATETIME_FORMATfalseSet the formatting of timestamps in charts.

Formatting: https://www.php.net/manual/en/datetime.format.php		j/m G:i
(18/10 20:06)
DATETIME_FORMATfalseSet the formatting of timestamps in tables and notifications.

Formatting: https://www.php.net/manual/en/datetime.format.php		j M Y, G:i:s
(18 Oct 2024, 20:06:01)
DISPLAY_TIMEZONEfalseDisplay timestamps in your local time.America/New_York
CONTENT_WIDTHfalseWidth of the content section of each page. Can be set to any value found in the Filament docs.

- Default: 7xl
PUBLIC_DASHBOARDfalseEnables the public dashboard for guest (unauthenticated) users.

- Default: false
DEFAULT_CHART_RANGEfalseSet the default time range for the dashboards

- Default: 24h		Options: 24h, week or month
+ +*** + +### Speed tests + +
NameRequiredDescriptionExample
SPEEDTEST_SKIP_IPSfalseA comma separated list of public IP addresses where tests will be skipped when present.127.0.0.1 or 127.0.0.0/16
SPEEDTEST_SCHEDULEfalseCron expression used to run speedtests on a scheduled basis. https://crontab.guru/ is a helpful tool.6 */2 * * *
(At minute 6 past every 2nd hour)
SPEEDTEST_SERVERSfalse

Comma separated list of server IDs to randomly use for speedtest.

To find servers near you visit: https://c.speedtest.net/speedtest-servers-static.php

52365 or 36998,52365
SPEEDTEST_BLOCKED_SERVERSfalseComma separated list of server IDs that should not be used when running an Ookla Speedtest.
SPEEDTEST_INTERFACEfalseSet the network interface to use for the test. This need to be the network interface available inside the containereth0
SPEEDTEST_EXTERNAL_IP_URLfalseURL of a service used to get the external WAN IP address.
SPEEDTEST_INTERNET_CHECK_HOSTNAMEfalseHostname used to ping for an active internet connection.
THRESHOLD_ENABLEDfalseEnable the thresholds. Note: Only effective during initial setup.true
THRESHOLD_DOWNLOADfalse

Set the Download Threshold

Note: Only effective during initial setup.

900
THRESHOLD_UPLOADfalse

Set the Upload Threshold

Note: Only effective during initial setup.

900
THRESHOLD_PINGfalse

Set the Ping Threshold

Note: Only effective during initial setup.

25
PRUNE_RESULTS_OLDER_THANfalseSet the value to greater than zero to prune stored results. This value should be represented in days, e.g. 7 will purge all results over 7 days old.7
+ +*** + +### API + +
NameRequiredDescriptionExample
API_RATE_LIMITfalseNumber of requests per minute to the API.

- Default: 60		100
API_MAX_RESULTSfalseSets the maximum number of results returned by API.

- Default 500
500
diff --git a/getting-started/installation/README.md b/getting-started/installation/README.md index d54bcb5..e37ce3b 100644 --- a/getting-started/installation/README.md +++ b/getting-started/installation/README.md @@ -1,24 +1,21 @@ # Installation -Speedtest Tracker can be run on a variety of platforms including using [Docker and Docker Compose](installation.md) along with [Synology NAS](synology.md) devices and on [Unraid OS](unraid.md). +Speedtest Tracker is containerized so you can run it anywhere you run your containers. The image is built by LinuxServer.io, build information can be found [here](https://fleet.linuxserver.io/image?name=linuxserver/speedtest-tracker). -{% hint style="info" %} -Docker Compose is the recommended platform. +{% hint style="danger" %} +Only the installation methods listed below are supported. Any other installation methods, such as bare metal setups or Proxmox LXCs, are **not supported** by this project. {% endhint %} -### Environment Variables +Use the install guides listed below to install Speedtest Tracker: -#### Core +### Docker -
NameDescription
PUID

(required)		Used to set the user the container should run as. To find your UID run id username on the host machine.

- Default: 1000
PGID

(required)		Used to set the group the container should run as. To find your GID run id username on the host machine.

- Default: 1000
APP_KEYKey used to encrypt and decrypt data. To create a key to persist follow the directions in the FAQ.

Currently not used and generated at random on startup of the container.
APP_DEBUGUsed to help narrow down issues in a running container, see FAQ for when to use it.

- Default: false
DB_CONNECTION

(required)		Type of database to be used for storing data. Accepted values are sqlite, mysql and pgsql.
DB_HOST

(required)		FQDN or container name where the database is located.
DB_PORTPort used to connect to the host where the database is located. Only needs to be defined if the database is running on a different port.

- Default: 3306 when using MySQL or MariaDB
- Default: 5432 when using Postgresql
DB_DATABASE

(required)		Name of the database.
DB_USERNAME

(required)		Database user used to connect to the database. Needs read/write access.
DB_PASSWORD

(required)		Password for the user specified to connect to the database.
FORCE_HTTPSEnforces the user of https protocol when viewing the UI, port 443 must be mapped to the container for this to work.

- Default: false
+* [Docker Compose](using-docker-compose.md) +* [Docker Run](using-docker.md) +* [Kubernetes](using-kubernetes.md) -#### Functional - -
NameDescription
CONTENT_WIDTHWidth of the content section of each page. Can be set to any value found in the Filament docs.

- Default: 7xl
DASHBOARD_POLLINGFrequency charts and stats refresh on the dashboard. Can be represented using a string in seconds or false to disable.

- Default: 60s
NOTIFICATION_POLLINGFrequency database notifications are polled. Can be represented using a string in seconds or false to disable.

- Default: 60s
RESULTS_POLLINGFrequency data refreshes in the results table. Can be represented using a string in seconds or false to disable.

- Default: false
ALLOW_EMBEDSCan be a comma separated list of URLs that the application will allow to be embedded in.

- Default: null
- -*** - -### Port Mapping - -
ProtocolExternal port (default)Internal port
HTTP8080
HTTPS443443
+### NAS Devices +* [QNAP](using-qnap.md) +* [Synology](using-synology.md) +* [Unraid](using-unraid.md) diff --git a/getting-started/installation/installation.md b/getting-started/installation/installation.md deleted file mode 100644 index 59ab35a..0000000 --- a/getting-started/installation/installation.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -description: >- - These steps will run you through setting up the application using Docker and - Docker Compose. ---- - -# Using Docker or Docker Compose - -### Install with Docker Compose (recommended) - -Setting up your environment with Docker Compose is the recommended infrastructure pattern as it'll setup the application and a database for you. SQLite is fine for most installs but we also provide instructions for setting up MariaDB, MySQL and Postgres should you prefer those database drivers. - -If you would like to provide your own SSL keys, they must be named `cert.crt` (full chain) and `cert.key` (private key), and mounted in the container folder `/config/keys`. - -{% tabs %} -{% tab title="SQLite" %} -```yaml -version: '3.4' -services: - speedtest-tracker: - container_name: speedtest-tracker - ports: - - 8080:80 - - 8443:443 - environment: - - PUID=1000 - - PGID=1000 - - DB_CONNECTION=sqlite - volumes: - - /path/to/data:/config - - /path/to-custom-ssl-keys:/config/keys - image: lscr.io/linuxserver/speedtest-tracker:latest - restart: unless-stopped -``` -{% endtab %} - -{% tab title="MariaDB/MySQL" %} -```yaml -version: '3.4' -services: - speedtest-tracker: - container_name: speedtest-tracker - ports: - - 8080:80 - - 8443:443 - environment: - - PUID=1000 - - PGID=1000 - - DB_CONNECTION=mysql - - DB_HOST=db - - DB_PORT=3306 - - DB_DATABASE=speedtest_tracker - - DB_USERNAME=speedy - - DB_PASSWORD=password - volumes: - - /path/to/data:/config - - /path/to-custom-ssl-keys:/config/keys - image: lscr.io/linuxserver/speedtest-tracker:latest - restart: unless-stopped - depends_on: - - db - db: - image: mariadb:10 - restart: always - environment: - - MARIADB_DATABASE=speedtest_tracker - - MARIADB_USER=speedy - - MARIADB_PASSWORD=password - - MARIADB_RANDOM_ROOT_PASSWORD=true - volumes: - - speedtest-db:/var/lib/mysql -volumes: - speedtest-db: -``` -{% endtab %} - -{% tab title="Postgres" %} -```yaml -version: '3.4' -services: - speedtest-tracker: - container_name: speedtest-tracker - ports: - - 8080:80 - - 8443:443 - environment: - - PUID=1000 - - PGID=1000 - - DB_CONNECTION=pgsql - - DB_HOST=db - - DB_PORT=5432 - - DB_DATABASE=speedtest_tracker - - DB_USERNAME=speedy - - DB_PASSWORD=password - volumes: - - /path/to/data:/config - - /path/to-custom-ssl-keys:/config/keys - image: lscr.io/linuxserver/speedtest-tracker:latest - restart: unless-stopped - depends_on: - - db - db: - image: postgres:15 - restart: always - environment: - - POSTGRES_DB=speedtest_tracker - - POSTGRES_USER=speedy - - POSTGRES_PASSWORD=password - volumes: - - speedtest-db:/var/lib/postgresql/data -volumes: - speedtest-db: -``` -{% endtab %} -{% endtabs %} - -*** - -### Install with Docker - -{% hint style="info" %} -These instructions assume you have an appropriate database instance that already exists. -{% endhint %} - -{% tabs %} -{% tab title="SQLite" %} -```bash -docker run -d --name speedtest-tracker --restart unless-stopped \ - -p 8080:80 \ - -p 8443:443 \ - -e PUID=1000 \ - -e PGID=1000 \ - -e DB_CONNECTION=sqlite \ - -v /path/to/data:/config \ - -v /path/to-custom-ssl-keys:/config/keys \ - lscr.io/linuxserver/speedtest-tracker:latest -``` -{% endtab %} - -{% tab title="MariaDB/MySQL" %} -```bash -docker run -d --name speedtest-tracker --restart unless-stopped \ - -p 8080:80 \ - -p 8443:443 \ - -e PUID=1000 \ - -e PGID=1000 \ - -e DB_CONNECTION=mysql \ - -e DB_HOST= \ - -e DB_PORT=3306 \ - -e DB_DATABASE=speedtest_tracker \ - -e DB_USERNAME= \ - -e DB_PASSWORD= \ - -v /path/to/data:/config \ - -v /path/to-custom-ssl-keys:/config/keys \ - lscr.io/linuxserver/speedtest-tracker:latest -``` -{% endtab %} - -{% tab title="Postgres" %} -```bash -docker run -d --name speedtest-tracker --restart unless-stopped \ - -p 8080:80 \ - -p 8443:443 \ - -e PUID=1000 \ - -e PGID=1000 \ - -e DB_CONNECTION=pgsql \ - -e DB_HOST= \ - -e DB_PORT=5432 \ - -e DB_DATABASE=speedtest_tracker \ - -e DB_USERNAME= \ - -e DB_PASSWORD= \ - -v /path/to/data:/config \ - -v /path/to-custom-ssl-keys:/config/keys \ - lscr.io/linuxserver/speedtest-tracker:latest -``` -{% endtab %} -{% endtabs %} diff --git a/getting-started/installation/kubernetes.md b/getting-started/installation/kubernetes.md deleted file mode 100644 index a80bb87..0000000 --- a/getting-started/installation/kubernetes.md +++ /dev/null @@ -1,5 +0,0 @@ -# Kubernetes - -### Community Manifests - -* [https://github.com/maximemoreillon/kubernetes-manifests/tree/master/speedtest-tracker](https://github.com/maximemoreillon/kubernetes-manifests/tree/master/speedtest-tracker) diff --git a/getting-started/installation/synology.md b/getting-started/installation/synology.md deleted file mode 100644 index dcb18f4..0000000 --- a/getting-started/installation/synology.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -description: >- - These instructions will run you through setting up the application on a - Synology NAS. ---- - -# Using Synology - -{% hint style="warning" %} -The following directions are for the old "Docker" application, if you're using "Container Manager" you can follow the docker compose instructions in [installation.md](installation.md "mention"). -{% endhint %} - -### Install on a Synology NAS - -Open the Docker interface of your Synology Device, search for `ajustesen/speedtest-tracker` in the Registry and download it. - -![download\_image](https://user-images.githubusercontent.com/92191413/210480118-b15f83af-6617-4a0d-b631-760f419425b9.png) - -Create a local directory (i.e. `/volume1/docker/speedtest-tracker`) which later can be mapped to the docker container. - -Launch the image once the download is completed. - -![launch\_image](https://user-images.githubusercontent.com/92191413/210480210-baa06b52-c3b0-41a4-b50e-ce7af82d683c.png) - -Map the ports to available ports. - -![port\_mapping](https://user-images.githubusercontent.com/92191413/210481629-6fa76992-403a-415e-9967-af7b00c97d87.png) - -{% hint style="info" %} -Make sure the ports you choose are not used by any other application or DSM service on your device and remember to adjust the Synology Firewall settings accordingly. -{% endhint %} - -Map the directory you created earlier to the mount path `/config`. - -![volume\_mapping](https://user-images.githubusercontent.com/92191413/210480901-069703e3-c6ab-446c-b53b-8c5ef3c87085.png) - -Review your settings and click "done". - -![summary](https://user-images.githubusercontent.com/92191413/210480977-3e24ba39-b23e-463f-acba-0a1aad1e57ec.png) - -You can now access Speedtest-Tracker via `http://YOUR_IP_ADDRESS:8080` or `https://YOUR_IP_ADDRESS:8443`. diff --git a/getting-started/installation/using-docker-compose.md b/getting-started/installation/using-docker-compose.md new file mode 100644 index 0000000..96fdaba --- /dev/null +++ b/getting-started/installation/using-docker-compose.md @@ -0,0 +1,232 @@ +--- +description: >- + These instructions will run you through setting up Speedtest Tracker on a + Docker server using Docker Compose. +--- + +# Using Docker Compose + +Setting up your environment with Docker Compose is the recommended way as it'll setup the application and a database for you. These steps will run you through setting up the application using Docker and Docker Compose. + +{% hint style="info" %} +Docker run commands can be found on the [Using Docker](using-docker.md) page and assume you already have a database installed and configured. +{% endhint %} + +### Install with Docker Compose + +{% stepper %} +{% step %} +**Generate an Application Key** + +Run the command below to generate a key, the key is required for [encryption](../../security/encryption.md). Copy this key including the `base64:` prefix and paste it as your `APP_KEY` value. + +```bash +echo -n 'base64:'; openssl rand -base64 32; +``` +{% endstep %} + +{% step %} +**Setting Up Docker** + +SQLite is fine for most installs but you can also use more traditional relational databases like MariaDB, MySQL and Postgres. + +{% hint style="info" %} +You will need to get your user's `PUID` and `PGID`, you can do this by running `id $user` on the host. + +[https://docs.linuxserver.io/general/understanding-puid-and-pgid/](https://docs.linuxserver.io/general/understanding-puid-and-pgid/) +{% endhint %} + +{% tabs %} +{% tab title="SQLite" %} +```yaml +services: + speedtest-tracker: + image: lscr.io/linuxserver/speedtest-tracker:latest + restart: unless-stopped + container_name: speedtest-tracker + ports: + - 8080:80 + - 8443:443 + environment: + - PUID= + - PGID= + - APP_KEY= # Required + - APP_URL= # Required + - DB_CONNECTION=sqlite + volumes: + - /path/to/data:/config + - /path/to-custom-ssl-keys:/config/keys +``` +{% endtab %} + +{% tab title="MariaDB" %} +
services:
+    speedtest-tracker:
+        image: lscr.io/linuxserver/speedtest-tracker:latest
+        restart: unless-stopped
+        container_name: speedtest-tracker
+        ports:
+            - 8080:80
+            - 8443:443
+        environment:
+            - PUID=
+            - PGID=
+            - APP_KEY= # Required
+            - APP_URL= # Required
+            - DB_CONNECTION=mariadb
+            - DB_HOST=db
+            - DB_PORT=3306
+            - DB_DATABASE=speedtest_tracker
+            - DB_USERNAME=speedtest_tracker
+            - DB_PASSWORD=password
+        volumes:
+            - /path/to/data:/config
+            - /path/to-custom-ssl-keys:/config/keys
+        depends_on:
+            - db
+    db:
+        image: mariadb:11
+        restart: always
+        environment:
+            - MYSQL_DATABASE=speedtest_tracker
+            - MYSQL_USER=speedtest_tracker
+            - MYSQL_PASSWORD=password
+            - MYSQL_RANDOM_ROOT_PASSWORD=true
+        volumes:
+            - speedtest-db:/var/lib/mysql
+        healthcheck:
+            test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+            interval: 5s
+            retries: 3
+            timeout: 5s
+volumes:
+  speedtest-db:
+
+{% endtab %} + +{% tab title="MySQL" %} +```yaml +services: + speedtest-tracker: + image: lscr.io/linuxserver/speedtest-tracker:latest + restart: unless-stopped + container_name: speedtest-tracker + ports: + - 8080:80 + - 8443:443 + environment: + - PUID= + - PGID= + - APP_KEY= # Required + - APP_URL= # Required + - DB_CONNECTION=mysql + - DB_HOST=db + - DB_PORT=3306 + - DB_DATABASE=speedtest_tracker + - DB_USERNAME=speedtest_tracker + - DB_PASSWORD=password + volumes: + - /path/to/data:/config + - /path/to-custom-ssl-keys:/config/keys + depends_on: + - db + db: + image: mysql:8 + restart: always + environment: + - MYSQL_DATABASE=speedtest_tracker + - MYSQL_USER=speedtest_tracker + - MYSQL_PASSWORD=password + - MYSQL_RANDOM_ROOT_PASSWORD=true + volumes: + - speedtest-db:/var/lib/mysql + healthcheck: + test: ["CMD", "mysqladmin", "ping", "-p${MYSQL_PASSWORD}"] + interval: 5s + retries: 5 + timeout: 5s +volumes: + speedtest-db: +``` +{% endtab %} + +{% tab title="Postgres" %} +```yaml +services: + speedtest-tracker: + image: lscr.io/linuxserver/speedtest-tracker:latest + restart: unless-stopped + container_name: speedtest-tracker + ports: + - 8080:80 + - 8443:443 + environment: + - PUID= + - PGID= + - APP_KEY= # Required + - APP_URL= # Required + - DB_CONNECTION=pgsql + - DB_HOST=db + - DB_PORT=5432 + - DB_DATABASE=speedtest_tracker + - DB_USERNAME=speedtest_tracker + - DB_PASSWORD=password + volumes: + - /path/to/data:/config + - /path/to-custom-ssl-keys:/config/keys + depends_on: + - db + db: + image: postgres:18 + restart: always + environment: + - POSTGRES_DB=speedtest_tracker + - POSTGRES_USER=speedtest_tracker + - POSTGRES_PASSWORD=password + - PGDATA=/var/lib/postgresql/data/ + volumes: + - speedtest-db:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"] + interval: 10s + retries: 5 + timeout: 5s +volumes: + speedtest-db: +``` +{% endtab %} +{% endtabs %} + +{% hint style="info" %} +If you would like to provide your own SSL keys, they must be named `cert.crt` (full chain) and `cert.key` (private key), and mounted in the container folder `/config/keys`. +{% endhint %} +{% endstep %} + +{% step %} +**Environment Variables** + +In order for the application to run smoothly, some environment variables need to be set. Check out the [Environment Variables](../environment-variables.md) section. Make sure all **required** variables are configured. +{% endstep %} + +{% step %} +**Configuration Variables (Optional)** + +You can set configuration variables to have automatic speedtest on an schedule. Check out the [Environment Variables](../environment-variables.md#speedtest) section on how to set the variables. Also see the [FAQ](../../help/faqs.md#speedtest) for tips effectively scheduling tests. + +{% hint style="info" %} +Complete overview of the Environment Variables for custom configuration can be found [here](../environment-variables.md). +{% endhint %} +{% endstep %} + +{% step %} +**Start the Container** + +You can now start the container accordingly the platform you are on. +{% endstep %} + +{% step %} +**First Login** + +During the start the container there is a default username and password created. Use the [default login](../../security/authentication.md#default-user-account) credentials to login to the application. You can [change the default user](../../security/authentication.md#change-account-details) after logging in. +{% endstep %} +{% endstepper %} diff --git a/getting-started/installation/using-docker.md b/getting-started/installation/using-docker.md new file mode 100644 index 0000000..b5ff34a --- /dev/null +++ b/getting-started/installation/using-docker.md @@ -0,0 +1,155 @@ +--- +description: >- + These instructions will run you through setting up Speedtest Tracker on a + Docker server using Docker run. +--- + +# Using Docker + +Setting up your environment with Docker Compose is the recommended way as it'll setup the application and a database for you. These steps will run you through setting up the application using Docker and Docker Compose. + +{% hint style="info" %} +Docker run commands assume you already have a database installed and configured. +{% endhint %} + +### Install with Docker Run + +{% stepper %} +{% step %} +**Generate an Application Key** + +Run the command below to generate a key, the key is required for [encryption](../../security/encryption.md). Copy this key including the `base64:` prefix and paste it as your `APP_KEY` value. + +```bash +echo -n 'base64:'; openssl rand -base64 32; +``` +{% endstep %} + +{% step %} +**Setting Up Docker** + +SQLite is fine for most installs but you can also use more traditional relational databases like MariaDB, MySQL and Postgres. + +{% hint style="info" %} +You will need to get your user's `PUID` and `PGID`, you can do this by running `id $user` on the host. + +[https://docs.linuxserver.io/general/understanding-puid-and-pgid/](https://docs.linuxserver.io/general/understanding-puid-and-pgid/) +{% endhint %} + +{% tabs %} +{% tab title="SQLite" %} +
docker run -d --name speedtest-tracker --restart unless-stopped \
+    -p 8080:80 \
+    -p 8443:443 \
+    -e PUID= \
+    -e PGID= \
+    -e APP_KEY= \
+    -e APP_URL= \
+    -e DB_CONNECTION=sqlite \
+    -v /path/to/data:/config \
+    -v /path/to-custom-ssl-keys:/config/keys \
+    lscr.io/linuxserver/speedtest-tracker:latest
+
+{% endtab %} + +{% tab title="MariaDB" %} +``` +docker run -d --name speedtest-tracker --restart unless-stopped \ + -p 8080:80 \ + -p 8443:443 \ + -e PUID= \ + -e PGID= \ + -e APP_KEY= \ + -e APP_URL= \ + -e DB_CONNECTION=mariadb \ + -e DB_HOST= \ + -e DB_PORT=3306 \ + -e DB_DATABASE=speedtest_tracker \ + -e DB_USERNAME= \ + -e DB_PASSWORD= \ + -v /path/to/data:/config \ + -v /path/to-custom-ssl-keys:/config/keys \ + lscr.io/linuxserver/speedtest-tracker:latest +``` +{% endtab %} + +{% tab title="MySQL" %} +``` +docker run -d --name speedtest-tracker --restart unless-stopped \ + -p 8080:80 \ + -p 8443:443 \ + -e PUID= \ + -e PGID= \ + -e APP_KEY= \ + -e APP_URL= \ + -e DB_CONNECTION=mysql \ + -e DB_HOST= \ + -e DB_PORT=3306 \ + -e DB_DATABASE=speedtest_tracker \ + -e DB_USERNAME= \ + -e DB_PASSWORD= \ + -v /path/to/data:/config \ + -v /path/to-custom-ssl-keys:/config/keys \ + lscr.io/linuxserver/speedtest-tracker:latest +``` +{% endtab %} + +{% tab title="Postgres" %} +``` +docker run -d --name speedtest-tracker --restart unless-stopped \ + -p 8080:80 \ + -p 8443:443 \ + -e PUID=1000 \ + -e PGID=1000 \ + -e APP_KEY= \ + -e APP_URL= \ + -e DB_CONNECTION=pgsql \ + -e DB_HOST= \ + -e DB_PORT=5432 \ + -e DB_DATABASE=speedtest_tracker \ + -e DB_USERNAME= \ + -e DB_PASSWORD= \ + -v /path/to/data:/config \ + -v /path/to-custom-ssl-keys:/config/keys \ + lscr.io/linuxserver/speedtest-tracker:latest +``` +{% endtab %} +{% endtabs %} + +{% hint style="info" %} +If you would like to provide your own SSL keys, they must be named `cert.crt` (full chain) and `cert.key` (private key), and mounted in the container folder `/config/keys`. +{% endhint %} +{% endstep %} + +{% step %} +**Environment Variables** + +In order for the application to run smoothly, some environment variables need to be set. Check out the [Environment Variables](../environment-variables.md) section. Make sure all **required** variables are configured. +{% endstep %} + +{% step %} +**Configuration Variables (Optional)** + +You can set configuration variables to have automatic speedtest on an schedule. Check out the [Environment Variables](../environment-variables.md#speedtest) section on how to set the variables. Also see the [FAQ](../../help/faqs.md#speedtest) for tips effectively scheduling tests. + +{% hint style="info" %} +Complete overview of the Environment Variables for custom configuration can be found [here](../environment-variables.md). +{% endhint %} +{% endstep %} + +{% step %} +**Start the Container** + +You can now start the container accordingly the platform you are on. +{% endstep %} + +{% step %} +**First Login** + +During the start the container there is a default username and password created. Use the [default login](../../security/authentication.md#default-user-account) credentials to login to the application. You can [change the default user](../../security/authentication.md#change-account-details) after logging in. +{% endstep %} +{% endstepper %} + +[^1]: Generate with: `echo -n 'base64:'; openssl rand -base64 32` + +[^2]: The URL where you'll access the app (e.g., `http://localhost:8080`) diff --git a/getting-started/installation/using-kubernetes.md b/getting-started/installation/using-kubernetes.md new file mode 100644 index 0000000..1b85f70 --- /dev/null +++ b/getting-started/installation/using-kubernetes.md @@ -0,0 +1,11 @@ +--- +description: >- + These instructions will run you through setting up Speedtest Tracker in a + Kubernetes cluster. +--- + +# Using Kubernetes + +### Community Manifests + +{% embed url="https://github.com/maximemoreillon/kubernetes-manifests/tree/master/speedtest-tracker" %} diff --git a/getting-started/installation/qnap.md b/getting-started/installation/using-qnap.md similarity index 73% rename from getting-started/installation/qnap.md rename to getting-started/installation/using-qnap.md index ac97185..4e1f36b 100644 --- a/getting-started/installation/qnap.md +++ b/getting-started/installation/using-qnap.md @@ -1,5 +1,7 @@ --- -description: Install Speedtest Tracker in a QNAP NAS using Container Station. +description: >- + These instructions will run you through setting up Speedtest Tracker on a QNAP + NAS using Container Station. --- # Using QNAP @@ -9,12 +11,16 @@ These instructions will run you through setting up the application on a QNAP NAS 1. Open **"Container Station"** and select **"Applications"** from the left-hand navigation menu. 2. Press the **"Create"** button. 3. Provide a name for the application. -4. Paste the below Docker Compose code into the text box, this is a modification of the MariaDB Docker Compose [install ](installation.md)instructions. +4. Paste the below Docker Compose code into the text box, this is a modification of the MariaDB Docker Compose [install ](using-docker-compose.md)instructions. 5. Click **"Validate"** to make sure there are no errors. 6. Click **"Create"** to deploy the application. ### Example Docker Compose +{% hint style="info" %} +A full list of released versions can be found [here](https://fleet.linuxserver.io/image?name=linuxserver/speedtest-tracker) +{% endhint %} + ```yaml version: '3.4' services: @@ -24,14 +30,19 @@ services: - 8080:80 - 8443:443 environment: - - PUID=1000 - - PGID=1000 - - DB_CONNECTION=mysql - - DB_HOST=192.168.1.4 + - PUID= + - PGID= + - DB_CONNECTION=mariadb + - DB_HOST=db - DB_PORT=3306 - DB_DATABASE=speedtest_tracker - DB_USERNAME=speedy - DB_PASSWORD=password + - APP_KEY= + - DATETIME_FORMAT= + - APP_TIMEZONE= + - SPEEDTEST_SCHEDULE= # Optional + - SPEEDTEST_SERVERS= # Optional volumes: - /path/to-data:/config - /path/to-custom-ssl-keys:/config/keys diff --git a/getting-started/installation/using-synology.md b/getting-started/installation/using-synology.md new file mode 100644 index 0000000..c08d71a --- /dev/null +++ b/getting-started/installation/using-synology.md @@ -0,0 +1,66 @@ +--- +description: >- + These instructions will run you through setting up Speedtest Tracker on a + Synology NAS using Container Manager. +--- + +# Using Synology + +{% hint style="warning" %} +The following directions are for the old "Docker" application, if you're using "Container Manager" you can follow the docker compose instructions in [using-docker-compose.md](using-docker-compose.md "mention"). +{% endhint %} + +### Install on a Synology NAS + +{% hint style="warning" %} +This guide assumes you know how to use the old "Docker" application. +{% endhint %} + +{% stepper %} +{% step %} +#### Download Image + +Open the Docker interface of your Synology Device, search for `linuxserver/speedtest-tracker` in the Registry and download it. +{% endstep %} + +{% step %} +#### Create Directory + +Create a local directory (i.e. `/volume1/docker/speedtest-tracker`) which later can be mapped to the docker container. +{% endstep %} + +{% step %} +#### Start Image + +Launch the image once the download is completed. +{% endstep %} + +{% step %} +#### Map Ports + +Map the ports to available ports. + +| Local Port | Container Port | +| ---------- | -------------- | +| 8443 | 443 | +| 8080 | 80 | + +{% hint style="info" %} +Make sure the ports you choose are not used by any other application or DSM service on your device and remember to adjust the Synology Firewall settings accordingly. +{% endhint %} +{% endstep %} + +{% step %} +#### Map Directory + +Map the directory you created earlier to the mount path `/config`. +{% endstep %} + +{% step %} +#### Finish + +Review your settings and click "done". + +You can now access Speedtest-Tracker via `http://YOUR_IP_ADDRESS:8080` or `https://YOUR_IP_ADDRESS:8443`. +{% endstep %} +{% endstepper %} diff --git a/getting-started/installation/unraid.md b/getting-started/installation/using-unraid.md similarity index 76% rename from getting-started/installation/unraid.md rename to getting-started/installation/using-unraid.md index 2d4b9d9..e02cbef 100644 --- a/getting-started/installation/unraid.md +++ b/getting-started/installation/using-unraid.md @@ -1,7 +1,7 @@ --- description: >- - These instructions will run you through setting up the application on a server - running Unraid OS. + These instructions will run you through setting up Speedtest Tracker on an + Unraid NAS using Community Applications. --- # Using Unraid diff --git a/help/error-messages.md b/help/error-messages.md index 183bc31..c16f48d 100644 --- a/help/error-messages.md +++ b/help/error-messages.md @@ -1,6 +1,82 @@ # Error Messages -Ookla's CLI can throw some common error messages. Below is a list with an explanation of what it means. +### Troubleshooting + +For all below errors there will be more information provided in the container logs. You can check the logs for more details by checking the container logs by running `docker logs speedtest-tracker`. + +or any other equivalent command for your setup. + +
+ +Enable Debugging + +By default `APP_DEBUG` is set to `false` in production to prevent verbose error outputs. To debug the issue follow the steps below. + +1. Set `APP_DEBUG=true` as a environment variable +2. Restart the container +3. Reproduce the error by visiting the page or performing the action that caused the error +4. View the output in the UI or in the logs to help resolve the issue, if you can not resolve it open an issue in the [GitHub](https://github.com/alexjustesen/speedtest-tracker/issues) repository +5. In the output the line that starts with `[timestamp] production.ERROR:` is the error the server ran into +6. Once the issue is resolved you can remove the `APP_DEBUG` environment variable + +
+ +### Application + +
+ +I'm getting a 500 | SERVER ERROR error + +The `500 | SERVER ERROR` is caused by either a bug or a misconfiguration. You must e[nable debugging](error-messages.md#enable-debugging) to determine the exact cause of the error. + +
+ +
+ +Unsupported cipher or incorrect key length. Supported ciphers are: aes-128-cbc, aes-256-cbc, aes-128-gcm, aes-256-gcm. + +This error is shown when the `APP_KEY` is not set or not set correctly. Make suer you set the `APP_KEY` as described in the [installation steps](../getting-started/installation/using-docker-compose.md#install-with-docker-compose). + +
+ +### Speedtest Process + +
+ +Failed to connected to hostname + +When a speedtest is being [processed](../other/speedtest-process.md) Speedtest Tracker will make a ICMP ping to [icanhazip.com](http://icanhazip.com) to check if there is an internet connection before starting the Speedtest + +**Possible reasons**: + +* There is a docker network problem or no internet connection. +* Some DNS blocks lists will block this domain, if you're getting errors and your server has access to the internet you'll need to add this to your allow lists. +* _Most_ Docker setups can send ICMP requests without needed elevated privileges on the host or in the container. That being said if your Docker user doesn't run with elevated permissions or doesn't belong to the Docker group you can get a failure on this step. To allow the user to send ICMP requests you need to add the permission to the container. + +**Configuration options** + +* Use available [Environment Variables](../getting-started/environment-variables.md#speed-tests) to change the endpoint to your liking + +
+ +
+ +Failed to fetch external IP address + +When the `SPEEDTEST_SKIP_IPS` environment variable is Speedtest Tracker will make a call to [http://icanhazip.com](http://icanhazip.com/) to get your external IP address. This is done check if your external IP address (WAN IP) should be skipped. + +**Possible reasons**: + +* There is a docker network problem or no internet connection. +* Some DNS blocks lists will block this domain, if you're getting errors and your server has access to the internet you'll need to add this to your allow lists. + +**Configuration options** + +* Use available [Environment Variables](../getting-started/environment-variables.md#speed-tests) to change the endpoint to your liking. :warning: Whatever service you choose needs to only return an IP address in the body of the response for this to work. + +
+ +### Ookla Related
@@ -22,6 +98,32 @@ This usually means the defined server is no longer available. Remove it from you Server Selection - Failed to find a working test server. (NoServers) -Not 100% sure what causes this exception yet but it's likely when the CLI can't locate a local server. You should specify a list of servers to see if that addresses the issue. +Not 100% sure what causes this exception yet but it's likely when the CLI can't locate a local server. You should specify a list of servers to see if that addresses the issue. + +
+ +
+ +Unable to retrieve Ookla servers, check internet connection and see logs. + +This errors is shown when we try to retrieve the Ookla server list when selecting an server wehn running an manual speedtest. We get the list from: [https://www.speedtest.net/api/js/servers](https://www.speedtest.net/api/js/servers). + +This error is useually caused by a docker network problem or no internet connection. You can check the [container logs](error-messages.md#troubleshooting) for more details. + +
+ +### InfluxDB + +
+ +Failed to write to InfluxDB + +When Speedtest Tracker fails to write data to InfluxDB this error is shown. The [container logs](error-messages.md#troubleshooting) will show more details on why it failed. + +**Possible reasons:** + +* Connectivity problem to influxdb +* Problem with authentication +* Specified bucket does not exist in InfluxDB
diff --git a/help/faqs.md b/help/faqs.md index 25d598b..91c3322 100644 --- a/help/faqs.md +++ b/help/faqs.md @@ -10,12 +10,7 @@ description: A running list of frequently ask questions and their answers. I get a warning on container start up that the APP_KEY is missing -As of `v0.12.0` the app key is generated on start-up and it is **OK to ignore this warning**. To set a persisted key follow the steps below - -1. Open the CLI of the Speedtest Docker container -2. Run `php artisan key:generate --show` -3. Add the generated string to your environment variables attached to `APP_KEY=generatedstringgoeshere` -4. Restart the container +You need a `APP_KEY` for the encryption. See the [installation docs](../getting-started/installation/) how to generate one. @@ -30,15 +25,11 @@ As of `v0.12.0` the app key is generated on start-up and it is **OK to ignore th -### Settings -
-Speedtest server - -#### Q: Why do only some servers have the server name in the list? +I'm getting duplicate message via Apprise -By default Ookla's CLI only returns the "closest" 20 servers. If the server you've selected isn't in that list Speedtest Tracker can label it. +By default when sending an notifications via Apprise we wait up to 30 seconds for Apprise to respond back with any message. Incase this 30 seconds is exceeded, we will retry 3 times. In case of any very slow Apprise processing this might cause duplicated notifications. Please check the [logs](error-messages.md#troubleshooting) to see the the timeout happend
@@ -46,43 +37,20 @@ By default Ookla's CLI only returns the "closest" 20 servers. If the server you'
-How do I set the display and schedule time zone? - -Your local time can be set in the UI under `Settings -> General -> Time zone`. - -
- -
- My display timestamps or scheduled tests aren't correct. -Speedtest Tracker assumes your application and database containers are set to `UTC` by default. +Speedtest Tracker assumes your application and database containers are set to `UTC` by default. If your database instance has your local time zone set it needs to **match** that set in `APP_TIMEZONE` and `DISPLAY_TIMEZONE` environment variables. -If your database instance runs with a local time zone set it needs to **match** that set in `Time zone` and `Database has time zone` needs to be enabled for the offset to be correctly displayed. +Once set restart the container.
-### Other +### Speedtest
-Cron schedule "from" a minute or hour +Scheduled tests give lower results then manual tests -Starting your cron schedule from a minute our hour can help avoid congestion on the network or a speedtest server. This [comment](https://github.com/alexjustesen/speedtest-tracker/issues/552#issuecomment-2028532010) on the issue can help you get the formatting right. - -
- -
- -I'm getting a 500 | SERVER ERROR error - -By default `APP_DEBUG` is set to `false` in production to prevent verbose error outputs. To debug the issue follow the steps below. - -1. Set `APP_DEBUG=true` as a environment variable -2. Restart the container -3. Reproduce the error by visiting the page or performing the action that caused the error -4. View the output in the UI or in the logs to help resolve the issue, if you can not resolve it open an issue in the [GitHub](https://github.com/alexjustesen/speedtest-tracker/issues) repository -5. In the output the line that starts with `[timestamp] production.ERROR:` is the error the server ran into -6. Once the issue is resolved you can remove the `APP_DEBUG` environment variable +Starting your cron schedule at an off-peak minute can help reduce network congestion or avoid overloading a speed test server. This [comment](https://github.com/alexjustesen/speedtest-tracker/issues/552#issuecomment-2028532010) on this issue can help you get the formatting right.
diff --git a/other/caching.md b/other/caching.md deleted file mode 100644 index 6da0d70..0000000 --- a/other/caching.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: >- - Speedtest Tracker supports multiple cache drivers, use the docs below to setup - your preferred handler. ---- - -# Caching - -## Drivers - -You can change your cache driver by setting the environment variable in your configuration file. To change the default driver pass `CACHE_DRIVER` as an environment variable. - -### File (default) - -{% hint style="info" %} -`v0.13.1` contains a change to `file` as the default driver to improve performance. -{% endhint %} - -This is the default cache driver and fine in most use cases, especially if the container runs on the same host system. - -### Database - -Using the database cache driver can be used if you're running multiple instances and want to share the cache. - -Change `CACHE_DRIVER` to `database` in your environment variables. - -### Redis - -Using Redis cache driver can also be used if you're running multiple instances or don't want to use the container's file system as the cache. - -Change `CACHE_DRIVER` to `redis` in your environment variables. diff --git a/other/commands.md b/other/commands.md index fb59c68..6f01af5 100644 --- a/other/commands.md +++ b/other/commands.md @@ -6,10 +6,7 @@ description: >- # Commands -Commands are intended to be run from within the CLI of the container and from the application's root directory. - -* In my build the root directory is located at: `/var/www/html` -* In LinuxServer's build the root directory is located at: `/app/www` +Commands are intended to be run from within the CLI of the container and from the application's root directory. The application directory is located at: `/app/www` When using the commands below they should be prefixed with `php artisan`, so the `about` command will look like `php artisan about`. @@ -23,10 +20,10 @@ Core commands exist at the framework level and might be extended to provide addi Application commands are built to extend Speedtest Tracker's functionality from the CLI. -
CommandDescription
app:installInstalls a fresh version of Speedtest Tracker. If you have an existing install this will delete all data.
app:reset-user-passwordCan be used to reset a user's password.
app:update-user-roleCan be used to change a user's role.
+
CommandDescription
app:ookla-list-serversGet a list of local Ookla speedtest servers.
app:user-change-roleChange the role for a user.
app:user-reset-passwordChange the password for a user.
### Maintenance commands Maintenance commands help fix issues that might crop up over time. -
CommandDescription
app:fix-result-statusesReviews the data payload of each result and corrects the status attribute based on Ookla's CLI response.
app:update-general-settingsUse to update General Settings from the CLI in case of an application error on that page.
+
CommandDescription
app:result-fix-statusesReviews the data payload of each result and corrects the status attribute.
diff --git a/other/community-projects.md b/other/community-projects.md new file mode 100644 index 0000000..a6f5745 --- /dev/null +++ b/other/community-projects.md @@ -0,0 +1,14 @@ +--- +description: >- + This page lists community projects that use SpeedTest Tracker as a base for + their own projects. If you have a project that you would like to share, please + submit a pull request to add it to this list. +--- + +# Community Projects + +## Projects + +* [SpeedtestTrackerBot](https://github.com/josephistired/SpeedtestTrackerBot) — SpeedtestTrackerBot is a lightweight Discord bot that integrates with the Speedtest Tracker API to provide real-time network performance data via slash commands like `/latest`, `/stats`, `/result`, and `/run`. It's easy to set up with Docker or systemd. +* Stream Deck - Use the API to show the most recent result on your Stream Deck. Shoutout to [MartynKeigher](https://github.com/MartynKeigher) on GitHub for [providing](https://github.com/alexjustesen/speedtest-tracker/issues/1191) these instructions. +* [Speedtest Tracker App (iOS)](https://apps.apple.com/us/app/speedtest-tracker-app/id6755368150) - Speedtest Tracker App is a native iOS client for Speedtest Tracker, which integrates with its API to allow you to perform actions or see stats straight from your phone. diff --git a/other/data-dictionary.md b/other/data-dictionary.md index 73f0519..623942c 100644 --- a/other/data-dictionary.md +++ b/other/data-dictionary.md @@ -4,4 +4,4 @@ #### Results -
FieldTypeDescription
idprimary key
servicestringService user to run the speedtest.
pingdoubleAs milliseconds
downloadunsigned big intAs bytes
uploadunsigned big intAs bytes
commentstextUser added comments.
datajsonThe raw response from the speedtest.
statusstring
  • Completed - a speedtest that ran successfully.
  • Failed - a speedtest that failed to run successfully.
  • Started - a speedtest that has been started but has not finished running.
scheduledbooleanWas the result scheduled.
created_attimestampWhen the record was created.
updated_attimestampWhen the record was last updated.
+
FieldTypeDescription
idprimary key
servicestringService user to run the speedtest.
pingdoubleAs milliseconds
downloadunsigned big intAs bytes
uploadunsigned big intAs bytes
commentstextUser added comments.
datajsonThe raw response from the speedtest.
benchmarksjsonCaptures the speedtest's benchmarks at run time.
healthybooleanIndicates if the speedtest was healthy compared to the benchmark.
statusstring
  • Completed - a speedtest that ran successfully.
  • Failed - a speedtest that failed to run successfully.
  • Started - a speedtest that has been started but has not finished running.
  • Skipped - a speedtest that was skipped. See message for more details.
scheduledbooleanWas the result scheduled.
created_attimestampWhen the record was created.
updated_attimestampWhen the record was last updated.
diff --git a/other/health-check.md b/other/health-check.md index 3abce67..a055bf0 100644 --- a/other/health-check.md +++ b/other/health-check.md @@ -11,10 +11,8 @@ curl APP_URL/api/healthcheck You can also add this to your Docker Compose file so the Docker service can monitor that the container has started successfully. ```yaml -version: '3.4' - healthcheck: - test: curl -fSs APP_URL/api/healthcheck || exit 1 + test: curl -fSs APP_URL/api/healthcheck | jq -r .message || exit 1 interval: 10s retries: 3 start_period: 30s @@ -24,5 +22,5 @@ healthcheck: ### Response ```json -{"message":"Speedtest Tracker is running!"} +Speedtest Tracker is running! ``` diff --git a/other/proxies.md b/other/proxies.md new file mode 100644 index 0000000..5fc9616 --- /dev/null +++ b/other/proxies.md @@ -0,0 +1,8 @@ +--- +description: Installation guides for when using Reverse Proxies +--- + +# Proxies + +``` +``` diff --git a/other/proxies/README.md b/other/proxies/README.md new file mode 100644 index 0000000..ea8a4dd --- /dev/null +++ b/other/proxies/README.md @@ -0,0 +1,10 @@ +--- +description: >- + Installation guides for when using Reverse Proxies. These configurations are + provided by the community. +--- + +# Proxies + +``` +``` diff --git a/other/proxies/cloudflare-tunnel-zero-trust.md b/other/proxies/cloudflare-tunnel-zero-trust.md new file mode 100644 index 0000000..b4d5aef --- /dev/null +++ b/other/proxies/cloudflare-tunnel-zero-trust.md @@ -0,0 +1,57 @@ +# Cloudflare Tunnel (Zero Trust) + +A [Cloudflare tunnel ](https://www.cloudflare.com/nl-nl/products/tunnel/)can be used as a reverse proxy in front of Speedtest Tracker when you want to expose the application publicly without exposing your IP address. + +### Cloudflare Tunnel Configuration + +* Update your `APP_URL` to the public URL you are going to use and restart the service. +* In the Cloudflare panel go to **Zero Trust** -> **Networks** -> **Tunnels** page. +* For the tunnel you want to add the Speedtest Tracker to click on **Edit** or add a new tunnel. +* Go to **Public Hostname.** +* Click on **Add a public hostname.** +* Fill in the following fields. + * **Subdomain:** The subdomain you want to access the Speedtest Tracker on. + * **Domain:** The domain you want to access the Speedtest Tracker on. + * **Type:** Connection type to the Speedtest Tracker (http/https) + * When choosing HTTPS you will need to disable the TLS verification under `Additional application settings -> TLS -> No TLS Verify` + * **URL:** The URL to access the Speedtest Tracker. This can be either the IP Address:Port or the container\_name:port. + +{% hint style="info" %} +When using the container\_name Cloudflare Tunnel and Speedtest Tracker need to be on the same Docker network. +{% endhint %} + +
+ +### Docker Configuration + +Docker-Compose: + +```yaml +services: + speedtest-tracker: + container_name: speedtest-tracker + environment: + - PUID=1000 + - PGID=1000 + - APP_KEY= + - DB_CONNECTION=sqlite + - SPEEDTEST_SCHEDULE= + - SPEEDTEST_SERVERS= + - PRUNE_RESULTS_OLDER_THAN= + - CHART_DATETIME_FORMAT= + - DATETIME_FORMAT= + - APP_TIMEZONE= + - APP_URL=https://speedtest.yourdomain.com # Change this to your domain name + - ASSET_URL=https://speedtest.yourdomain.com # Change this to your domain name + volumes: + - /path/to/data:/config + - /path/to-custom-ssl-keys:/config/keys + image: lscr.io/linuxserver/speedtest-tracker:latest + restart: unless-stopped +``` + +{% hint style="info" %} +Depending on your Cloudflare Tunnel configuration, you need to make sure the Speedtest Tracker and Cloudflare Tunnel are on the same docker network. +{% endhint %} + +
Added compose partDescription
APP_URLURL you want to access the WebGui on.
ASSET_URLURL used for loading all the needed assets. Need to be the same as the APP_URL.
diff --git a/other/proxies/nginx.md b/other/proxies/nginx.md new file mode 100644 index 0000000..15d8694 --- /dev/null +++ b/other/proxies/nginx.md @@ -0,0 +1,74 @@ +# Nginx + +[Nginx](https://nginx.org) can be used as a Reverse Proxy in front of Speedtest +Tracker to expose the Dashboard publicly with a trusted certificate. + +First, you will need to add the `APP_URL` and `ASSET_URL` environment variables +to your `docker-compose.yml`. + +```yaml +services: + speedtest-tracker: + container_name: speedtest-tracker + environment: + - PUID=1000 + - PGID=1000 + - APP_KEY= + - DB_CONNECTION=sqlite + - SPEEDTEST_SCHEDULE= + - SPEEDTEST_SERVERS= + - PRUNE_RESULTS_OLDER_THAN= + - CHART_DATETIME_FORMAT= + - DATETIME_FORMAT= + - APP_TIMEZONE= + # Change both below to the desired domain + - APP_URL=https://speedtest.yourdomain.com + - ASSET_URL=https://speedtest.yourdomain.com + volumes: + - /path/to/data:/config + - /path/to-custom-ssl-keys:/config/keys + image: lscr.io/linuxserver/speedtest-tracker:latest + restart: unless-stopped +``` + +Next, you will need to configure nginx to proxy to the Speedtest Tracker app. + +{% hint style="info" %} +Depending on how you generate your SSL certificates and how you configure your +Docker network, you may need to adjust the `ssl_` and `proxy_pass` values. +{% endhint %} + +```nginx +server { + listen 80; + server_name speedtest.yourdomain.com; + return 301 https://$host$request_uri; +} + +server { + listen 443 ssl; + server_name speedtest.yourdomain.com; + + ssl_certificate /etc/letsencrypt/live/speedtest.yourdomain.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/speedtest.yourdomain.com/privkey.pem; + + ssl_protocols TLSv1.2; + ssl_ciphers +'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA'; + ssl_prefer_server_ciphers on; + ssl_session_cache shared:SSL:10m; + ssl_session_timeout 10m; + ssl_dhparam /etc/ssl/certs/dhparam.pem; + + add_header Strict-Transport-Security "max-age=31536000;includeSubdomains"; + + location / { + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Server $host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + proxy_pass http://speedtest-container-host:80; + } +} +``` diff --git a/other/proxies/tailscale.md b/other/proxies/tailscale.md new file mode 100644 index 0000000..3d9bba1 --- /dev/null +++ b/other/proxies/tailscale.md @@ -0,0 +1,67 @@ +# Tailscale + +[Tailscale](https://tailscale.com) Mesh VPN service can be used as an sidecar container to access the Speedtest Tracker within your Tailnet on its own MagicDNS name. + +## Tailscale Auth key + +Generate an auth key for tailscale so the docker container can access your tailnet. + +1. Open the [**Keys**](https://login.tailscale.com/admin/settings/keys) page of the admin console. +2. Select **Generate auth key**. +3. Fill out the form fields to specify characteristics about the auth key, such as the description, whether its reusable, when it expires, and device settings. +4. Select **Generate key**. + +Save this Auth Key. We will need this later on. + +## Docker Configuration + +Docker-Compose: + +```yaml +services: + tailscale-speedtest: + image: tailscale/tailscale + container_name: tailscale_speedtest-tracker + hostname: speedtest + environment: + - TS_AUTHKEY= + - TS_STATE_DIR=/var/lib/tailscale + - TS_USERSPACE=false + volumes: + - ./tailscale-traefik/state:/var/lib/tailscale + - /dev/net/tun:/dev/net/tun + cap_add: + - net_admin + - sys_module + restart: unless-stopped + + speedtest-tracker: + container_name: speedtest-tracker-tailscale + depends_on: + - tailscale-speedtest + network_mode: service:tailscale-speedtest + environment: + - PUID=1000 + - PGID=1000 + - APP_KEY= + - DB_CONNECTION=sqlite + - SPEEDTEST_SCHEDULE= + - SPEEDTEST_SERVERS= + - PRUNE_RESULTS_OLDER_THAN= + - CHART_DATETIME_FORMAT= + - DATETIME_FORMAT= + - APP_TIMEZONE= + - APP_URL=https://speedtest.yourtailnet.ts.net # Change this to your MagicDNS name + - ASSET_URL=https://speedtest.yourtailnet.ts.net # Change this to your MagicDNS name + volumes: + - /path/to/data:/config + - /path/to-custom-ssl-keys:/config/keys + image: lscr.io/linuxserver/speedtest-tracker:latest + restart: unless-stopped +``` + +| Added compose part | Description | +| ------------------ | --------------------------------------------------------------------------------------- | +| `APP_URL` | URL you want to access the WebGui on. This will need to be the Tailscale Magic DNS name | +| `ASSET_URL` | URL used for loading all the needed assets. Need to be the same as the `APP_URL`. | +| `TS_AUTHKEY` | Auth key for Tailscale | diff --git a/other/proxies/traefik.md b/other/proxies/traefik.md new file mode 100644 index 0000000..16db0ee --- /dev/null +++ b/other/proxies/traefik.md @@ -0,0 +1,42 @@ +# Traefik + +[Traefik](https://traefik.io) can be used as a Reverse Proxy in front of Speedtest Tracker when you want to expose the Dashboard publicly with a trusted certificate. You will need at add the `APP_URL` environment and needed labels to the docker compose have Traefik apply the certificate and routing. + +Docker-Compose: + +```yaml +services: + speedtest-tracker: + container_name: speedtest-tracker + environment: + - PUID=1000 + - PGID=1000 + - APP_KEY= + - DB_CONNECTION=sqlite + - SPEEDTEST_SCHEDULE= + - SPEEDTEST_SERVERS= + - PRUNE_RESULTS_OLDER_THAN= + - CHART_DATETIME_FORMAT= + - DATETIME_FORMAT= + - APP_TIMEZONE= + - APP_URL=https://speedtest.yourdomain.com # Change this to your domain name + - ASSET_URL=https://speedtest.yourdomain.com # Change this to your domain name + volumes: + - /path/to/data:/config + - /path/to-custom-ssl-keys:/config/keys + labels: + - "traefik.enable=true" + - "traefik.http.routers.speedtest-tracker.rule=Host(`speedtest.yourdomain.com`)" + - "traefik.http.routers.speedtest-tracker.entrypoints=websecure" + - "traefik.http.routers.speedtest-tracker.tls=true" + - "traefik.http.routers.speedtest-tracker.tls.certresolver=yourresolver" + - "traefik.http.services.speedtest-tracker.loadbalancer.server.port=80" + image: lscr.io/linuxserver/speedtest-tracker:latest + restart: unless-stopped +``` + +{% hint style="info" %} +Depending on your Traefik configuration, you need to make sure the Speedtest Tracker and Traefik are on the same docker network. +{% endhint %} + +
Added compose partDescription
APP_URLURL you want to access the WebGui on.
ASSET_URLURL used for loading all the needed assets. Need to be the same as the APP_URL.
traefik.enable=trueExplicitly tell Traefik to expose this container
traefik.http.routers.speedtest-tracker.rule=Host(`speedtest.yourdomain.com`)The domain the service will respond to
traefik.http.routers.speedtest-tracker.entrypoints=websecureAllow request only from the predefined entry point
traefik.http.routers.speedtest-tracker.tls=trueWhen a TLS section is specified, it instructs Traefik that the current router is dedicated to HTTPS requests only
traefik.http.routers.speedtest-tracker.tls.certresolver=yourresolverExplicitly tell Traefik which Certificate provider to use matching your Traefik configuration
traefik.http.services.speedtest-tracker.loadbalancer.server.port=80Explicitly tell Traefik port to use to connect to the container
diff --git a/other/speedtest-process.md b/other/speedtest-process.md new file mode 100644 index 0000000..dfa6d87 --- /dev/null +++ b/other/speedtest-process.md @@ -0,0 +1,63 @@ +# Speedtest Process + +Speedtest Tracker uses the [Official Ookla CLI](https://www.speedtest.net/apps/cli) client to execute the speedtest. There a couple of stages the Speedtest Tracker goes through, below explains the process. + +{% stepper %} +{% step %} +**Waiting** + +The speedtest run request was created but has not been started. +{% endstep %} + +{% step %} +**Started** + +The speedtest process has been started by a queue worker. +{% endstep %} + +{% step %} +**Checking** + +The application checks for an internet connection by calling `https://icanhazip.com` . +{% endstep %} + +{% step %} +**Skipped \[Optional]** + +If you have the `SPEEDTEST_SKIP_IPS` the test will be marked as skipped as the IP returning during `Checking` matches your defined IP. +{% endstep %} + +{% step %} +**Running** + +The application runs the speedtest by simply running the speedtest command. This command runs the speedtest like another other speedtest and returns the result in json format so the application an easily process it. + +``` +speedtest -accept-license --accept-gdpr --format=json +``` + +Or when you have defined a server id: + +``` +speedtest -accept-license --accept-gdpr --format=json --server-id=YOURSERVERID +``` +{% endstep %} + +{% step %} +**Failed** + +If for various reasons the Ookla CLI returns an error, because the defined server was offline for example the tests is marked as failed. As well when the `Checking` stage fails when there is no internet. +{% endstep %} + +{% step %} +**Benchmarking** + +When you have thresholds set this step will evaluate the results against the threshold to determine if the test was healthy or not. +{% endstep %} + +{% step %} +**Completed** + +This is the end stage of the process when every step is completed the test is marked as such. +{% endstep %} +{% endstepper %} diff --git a/other/stream-deck.md b/other/stream-deck.md deleted file mode 100644 index 0700ed2..0000000 --- a/other/stream-deck.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -description: Use the API to show the most recent result on your Stream Deck. ---- - -# Stream Deck - -{% hint style="info" %} -Shoutout to [MartynKeigher](https://github.com/MartynKeigher) on GitHub for [providing](https://github.com/alexjustesen/speedtest-tracker/issues/1191) these instructions. -{% endhint %} - -### Required Plugin - -Download the "API Ninja" plugin from the Elgato Marketplace. - -
- -### Configure the Buttons - -1. Under the "BarRadier" plugin select "API Ninja" and drag it to an empty slot. -2. Request type should be set to `GET`. -3. API URL should be set to your application's app url and append `/api/speedtest/latest`. -4. Set the Content Type to `application/json`. -5. Set the Response Shown to `data.download` for download and `data.upload` for upload. -6. Check Parse/Format 'Response shown'. -7. Set the Format to `{0:N0}`. -8. Optionally you can add a Title Suffix: `\n(Mbps)` -9. Set the Response Type to `Text`. -10. Set Autorun every option to a refresh interval of your choice. -11. Optionally you can hide green success indicator. -12. Lastly duplicate the button and change the Response Shown to `data.download`. - -
diff --git a/security/authentication.md b/security/authentication.md index a01eb3e..27ef9a8 100644 --- a/security/authentication.md +++ b/security/authentication.md @@ -4,12 +4,41 @@ Speedtest Tracker uses Filament for the admin panel. During the install process
Login page

Login page

-### Default User Account +### Default Login Account -{% hint style="info" %} -As of `v0.11.0` you can add additional users and update the default user's name, email and password. -{% endhint %} +During the first start of the application a default admin account is created for you: | Username | Password | | ------------------- | ---------- | | `admin@example.com` | `password` | + +### Change Login Account + +#### Login Details + +You can update the login details of your account through the profile page. Every user can update these details for their own account. + +* In the top right corner click on the user logo next to the bell icon. +* Click on Profile +* Change the `Name`, `E-Mail Address` and `Password` to your liking. + +#### Change Account details + +As an Admin you can change the account details of other accounts. + +* On the right side menu click on `Users` +* Click on user account you want to change +* Change the `Name`, `E-Mail Address` ,`Password` and `Role` to your liking. + +### Create Login Account + +You can create additional user accounts. + +* On the right side menu click on `Users` +* Click on `New User` +* Fill in the `Name`, `E-Mail Address, Password` and `Password confirmation` to your liking. +* Choose the needed role for the user under `Role`. + +{% hint style="info" %} +The difference between the Roles can be found in the [Authorization](authorization.md) section. +{% endhint %} diff --git a/security/authorization.md b/security/authorization.md index ca1f3a4..d92192a 100644 --- a/security/authorization.md +++ b/security/authorization.md @@ -1,12 +1,8 @@ # Authorization -{% hint style="info" %} -Role based authorization introduced in `v0.12.0-beta.6` -{% endhint %} - ### Results -
UserAdmin
View any (list)truetrue
View (show)truetrue
Createtruetrue
Updatetruetrue
Delete any (bulk)falsetrue
Deletefalsetrue
+
UserAdmin
View any (list)truetrue
View (show)truetrue
Createfalsefalse
Updatetruetrue
Delete any (bulk)falsetrue
Deletefalsetrue
#### Notes @@ -27,10 +23,10 @@ Role based authorization introduced in `v0.12.0-beta.6` ### Other -
UserAdmin
Trigger a manual Speedtesttruetrue
+
UserAdmin
Manage API tokensfalsetrue
Trigger a manual Speedtesttruetrue
*** ### Settings -
UserAdmin
Generalfalsetrue
Data integrationsfalsetrue
Notificationsfalsetrue
Thresholdsfalsetrue
+
UserAdmin
Data integrationsfalsetrue
Notificationsfalsetrue
Thresholdsfalsetrue
diff --git a/security/encryption.md b/security/encryption.md new file mode 100644 index 0000000..3132152 --- /dev/null +++ b/security/encryption.md @@ -0,0 +1,11 @@ +# Encryption + +### Application Key + +An application key (`APP_KEY`) is used for encryption. It is a base64 encoded string that is used by Speedtest Tracker to encrypt and decrypt data, such as user sessions and other sensitive information and is required as part of the setup process. + +Run the command below to generate your `APP_KEY`. + +```bash +echo -n 'base64:'; openssl rand -base64 32; +``` diff --git a/settings/data-platforms/influxdb2.md b/settings/data-platforms/influxdb2.md index b710734..5438054 100644 --- a/settings/data-platforms/influxdb2.md +++ b/settings/data-platforms/influxdb2.md @@ -1,11 +1,26 @@ -# InfluxDB2 +# InfluxDB v2 -{% hint style="info" %} -At this time only InfluxDB2 is supported, InfluxDB(1) is planned -{% endhint %} - -

InfluxDB2 settings

+After every test the Speedtest Tracker can send the results to InfluxDB for long term storage or custom visualizations. ### Settings +To configure Speedtest Tracker to send results to InfluxDB, set the following settings. +
NameDefaultDescription
URLblankFQDN or IP address to the InfluxDB2 instance
OrgblankOrganization on which you created your bucket in
Bucketspeedtest-trackerThe name of the bucket you created in your org
TokenblankAPI token that has access to write to the org and bucket listed above
+ +

Influxdb v2 Settings

+ +If you have a history of results, you can use the `Export current results` feature to export all data to InfluxDB. + +### Grafana Dashboard + +You can use this community made Grafana Dashboard to visualize your data. + +{% embed url="https://github.com/masterwishx/Speedtest-Tracker-v2-InfluxDBv2" %} + +### Data pattern + +The Speedtest Tracker exports data in two categories: `Tag` and `Field`. Tags are used for filtering, while fields are used for displaying the data. + +
NameData Type
result_idStringTag
external_ipStringTag
ispStringTag
serviceStringTag
server_idStringTag
server_nameStringTag
server_countryStringTag
server_locationStringTag
healthyStringTag
statusStringTag
scheduledStringTag
downloadinitField
uploadinitField
pingfloatField
download_bitsintField
upload_bitsintField
download_jitterfloatField
upload_jitterfloatField
ping_jitterfloatField
download_latency_avgfloatField
download_latency_highfloatField
download_latency_lowfloatField
upload_latency_avgfloatField
upload_latency_highfloatField
upload_latency_lowfloatField
packet_lossfloatField
+ diff --git a/settings/data-platforms/prometheus.md b/settings/data-platforms/prometheus.md new file mode 100644 index 0000000..84be1cf --- /dev/null +++ b/settings/data-platforms/prometheus.md @@ -0,0 +1,35 @@ +# Prometheus + +After each test, Speedtest Tracker exposes the metrics for Prometheus to scrape. For long term storage or custom visualizations. + +### Allowed IPs + +You can configure the Prometheus endpoint so it’s only accessible from specific IP addresses or networks. This can include single IPs or entire CIDR ranges. + +
+ +### Grafana Dashboard + +You can use this community made Grafana Dashboard to visualize your data. + +{% embed url="https://github.com/CrazyWolf13/Speedtest-Tracker-Prometheus" %} + +### Data pattern + +Speedtest Tracker exports data in two categories: labels and metrics. Labels are used for filtering, while metrics are used for displaying data. + +
Name
app_namelabel
isplabel
server_idlabel
server_namelabel
server_countrylabel
server_locationlabel
healthylabel
statuslabel
scheduledlabel
download_bytesMetric
upload_bytesMetric
pingMetric
download_bitsMetric
upload_bitsMetric
download_jitterMetric
upload_jitterMetric
ping_jitterMetric
download_latency_avgMetric
download_latency_highMetric
download_latency_lowMetric
upload_latency_avgMetric
upload_latency_highMetric
upload_latency_lowMetric
packet_lossMetric
+ +### Prometheus Scrape Config + +Below is an example Prometheus scrape configuration: + +```yaml +scrape_configs: + - job_name: 'speedtest-tracker' + scrape_interval: 60s # Adjust to your set schedule + scrape_timeout: 10s + metrics_path: /prometheus + static_configs: + - targets: ['speedtest-tracker.local'] +``` diff --git a/settings/notifications/README.md b/settings/notifications/README.md index 4b774d2..68501e6 100644 --- a/settings/notifications/README.md +++ b/settings/notifications/README.md @@ -1,2 +1,5 @@ # Notifications +{% hint style="warning" %} +Database, Mail and Webhook notifications are considered "core" channels. We're currently working on integrating Apprise and all other notification channels should be considered deprecated. +{% endhint %} diff --git a/settings/notifications/apprise.md b/settings/notifications/apprise.md new file mode 100644 index 0000000..5dfd401 --- /dev/null +++ b/settings/notifications/apprise.md @@ -0,0 +1,33 @@ +# Apprise + +Apprise provides a unified notification channel that lets you send alerts to numerous services—like Discord, Pushover, and Ntfy as well as many additional platforms + +### Why Apprise + +Apprise allows the application to sent notifications to a wide variety of services. It let us focus on features instead of maintaining X number of notification channels. Essentially helping us cut down on maintenance/feature requests. + +### Apprise Server + +{% hint style="info" %} +We don't offer support on setting up Apprise, incase of any problems with the Apprise Container please reach out to the Apprise team. +{% endhint %} + +To use Apprise, you’ll need to set up your own Apprise instance. This container isn’t created automatically, so make sure to include it in your deployment. See the Apprise [Github Repo](https://github.com/caronc/apprise-api) for the setup instructions. On the notification page you will need to define the location of your Apprise instance. Make sure this instance is reachable for the Speedtest Tracker. + +### Notification Channels + +Notification channels are the formatted URLs used by Apprise to send notifications to various services. Refer to the [Apprise documentation](https://github.com/caronc/apprise?tab=readme-ov-file#supported-notifications) for a full list of supported channels and their required formats. You can add as many different channels as you wish. The notifications will be sent to all of them. + +### Tips and Tricks + +#### Format + +By default the format used for message is `markdown` This allows us to do some formatting on the message like bold text etc. + +#### Preview Images + +By default Apprise does not allow preview images for URLs. This is an default setting on the Apprise instance. Depending on the service used you can override this settings in the notification channel URL. Check the Apprise documentation to see if your service support this and how to set it. + +### Triggers + +
NameDescription
on every scheduled speedtest runOn each successful scheduled speedtest a notification will be send to the application.
on threshold failures for scheduled speedtestsOn any absolute threshold failure for scheduled speedtest a notification will be send to the application.
diff --git a/settings/notifications/database.md b/settings/notifications/database.md index a253512..e4f0348 100644 --- a/settings/notifications/database.md +++ b/settings/notifications/database.md @@ -6,4 +6,4 @@ Notifications sent to the database channel will show up under the 🔔 icon in t ### Triggers -
NameDescription
On completed speedtestOn each successful speedtest a notification will be send to the application.
On absolute threshold failureOn any absolute threshold failure a notification will be send to the application.
+
NameDescription
on every scheduled speedtest runOn each successful scheduled speedtest a notification will be send to the application.
on threshold failures for scheduled speedtestsOn any absolute threshold failure for scheduled speedtest a notification will be send to the application.
diff --git a/settings/notifications/mail.md b/settings/notifications/mail.md index a0c5af1..a8e1bbe 100644 --- a/settings/notifications/mail.md +++ b/settings/notifications/mail.md @@ -6,9 +6,9 @@ Notifications sent to the mail channel will be emailed to the list of recipients ### Setting Up SMTP -Speedtest Tracker uses SMTP mail protocol to send email messages, you can use any service that allows you to send emails via SMTP. +Speedtest Tracker uses SMTP mail protocol to send email messages, you can use any service that allows you to send emails via SMTP. -To configure the mail server settings you'll need to update the following variables in your `.env` file or add them to the environment variables passed into the container. When choosing mail encryption both `ssl` and `tls` protocols are supported and you'll want to check with your mail provider for which to use and which port. +To configure the mail server settings you'll need to update the following variables in your `.env` file or add them to the environment variables passed into the container. When choosing mail scheme both `ssl` and `tls` protocols are supported and you'll want to check with your mail provider for which to use and which port. {% hint style="warning" %} Make sure these are not set in both your `.env` file or your `docker-compose.yml` file as that can cause issues. @@ -16,40 +16,42 @@ Make sure these are not set in both your `.env` file or your `docker-compose.yml ``` MAIL_MAILER=smtp -MAIL_HOST=mailhog -MAIL_PORT=1025 -MAIL_USERNAME=null -MAIL_PASSWORD=null -MAIL_ENCRYPTION=null -MAIL_FROM_ADDRESS="hello@example.com" -MAIL_FROM_NAME="Speedtest Tracker" +MAIL_HOST= +MAIL_PORT= +MAIL_USERNAME= +MAIL_PASSWORD= +MAIL_FROM_ADDRESS= +MAIL_FROM_NAME= ``` -**GMAIL example:** +{% hint style="info" %} +`MAIL_SCHEME` is optional, only use it if you need to define `smtp` or `smtps` otherwise Laravel will determine the scheme based on the port provided. +{% endhint %} + +*** + +### Examples + +#### Gmail -Steps for creating an app password. -- Go to your Google Account -. -- Select Security. -- Under "How you sign in to Google," choose 2-Step Verification. -- Click on App passwords. -- Enter a name and generate a password. -- Remember to copy the password before closing; otherwise, you'll need to create another one. +1. Go to [https://myaccount.google.com/](https://myaccount.google.com/) and click on the "Security" tab. +2. Under the "How you sign in to Google" section, click on "2-Step Verification". +3. Click on "App passwords". +4. Enter a name for your app password and click "Create". Use this password for the `MAIL_PASSWORD` env variable in the example configuration below. ``` MAIL_MAILER=smtp MAIL_HOST=smtp.gmail.com MAIL_PORT=465 -MAIL_USERNAME=username@gmail.com +MAIL_USERNAME="username@gmail.com" MAIL_PASSWORD="password" -MAIL_ENCRYPTION=tls -MAIL_FROM_ADDRESS=username@gmail.com +MAIL_FROM_ADDRESS="username@gmail.com" MAIL_FROM_NAME="Speedtest Tracker" ``` ### Triggers -
NameDescription
On completed speedtestOn each successful speedtest a notification will be send to the application.
On absolute threshold failureOn any absolute threshold failure a notification will be send to the application.
+
NameDescription
on every scheduled speedtest runOn each successful scheduled speedtest a notification will be send to the application.
on threshold failures for scheduled speedtestsOn any absolute threshold failure for scheduled speedtest a notification will be send to the application.
### Recipients diff --git a/settings/notifications/telegram.md b/settings/notifications/telegram.md deleted file mode 100644 index b2e1bbe..0000000 --- a/settings/notifications/telegram.md +++ /dev/null @@ -1,22 +0,0 @@ -# Telegram - -Notifications sent to the Telegram channel will be sent to the list of recipients. - -

Telegram settings

- -### Setting Up Telegram - -To configure Telegram for notifications you'll need to have a [Telegram](https://telegram.org/) account and follow the directions below. - -1. Create a Telegram bot by starting a message with `@BotFather`. -2. Using the bot's token ID to add the following variable in your `.env` file in your mounted data directory. `TELEGRAM_BOT_TOKEN=putyourtokenhere` -3. Next you'll need your own chat ID (hint: it's not the bot ID), start a chat with `@Get_Id_Bot` and add that to your "Recipients" list and click "Save". -4. Start a chat with your bot your created in step 1 to start receiving notification from yout Telegram bot. - -### Triggers - -
NameDescription
On completed speedtestOn each successful speedtest a notification will be send to the application.
On absolute threshold failureOn any absolute threshold failure a notification will be send to the application.
- -### Recipients - -A recipient is any valid Telegram chat ID, you can add one or many recipients that will receive notifications based on the triggers selected. diff --git a/settings/notifications/webhook.md b/settings/notifications/webhook.md new file mode 100644 index 0000000..8bb7ab3 --- /dev/null +++ b/settings/notifications/webhook.md @@ -0,0 +1,70 @@ +# Webhook + +A webhook will send a JSON payload to a receiver of your choice + +

Webhook settings

+ +### Payload + +{% tabs %} +{% tab title="Threshold Failure " %} +```json +{ + "result_id": 14, + "site_name": "Speedtest Tracker", + "isp": "Speedy Communications", + "benchmarks": { + "download": { + "bar": "min", + "passed": false, + "type": "absolute", + "test_value": 1022, + "benchmark_value": 2000, + "unit": "mbps" + }, + "upload": { + "bar": "min", + "passed": false, + "type": "absolute", + "test_value": 1018, + "benchmark_value": 2000, + "unit": "mbps" + }, + "ping": { + "bar": "max", + "passed": false, + "type": "absolute", + "test_value": 3, + "benchmark_value": 1, + "unit": "ms" + } + }, + "speedtest_url": "https://www.speedtest.net/result/c/1433a2de-eb3c-4a0e-ab29-xxxxxx", + "url": "http://192.168.1.5/admin/results" +} +``` +{% endtab %} + +{% tab title="Completed test" %} +```json +{ + "result_id": 17, + "site_name": "Speedtest Tracker", + "server_name": "Speedtest", + "server_id": 52365, + "status": "completed", + "isp": "Speedy Communications", + "ping": 3, + "download": 1026, + "upload": 1012, + "packet_loss": 0, + "speedtest_url": "https://www.speedtest.net/result/c/288aa4aa-a52e-493c-8d60-xxxx", + "url": "http://192.168.1.5/admin/results" +} +``` +{% endtab %} +{% endtabs %} + +### Triggers + +
NameDescription
on every scheduled speedtest runOn each successful scheduled speedtest a notification will be send to the application.
on threshold failures for scheduled speedtestsOn any absolute threshold failure for scheduled speedtest a notification will be send to the application.