Speedtest Tracker v2

Speedtest Tracker runs scheduled Ookla Speedtest CLI checks, stores the results, and presents them in a web UI. Version 2 is a Go service with a Nuxt frontend; it is a rewrite of the previous Laravel/React application.

Ookla's EULA and privacy agreement must be accepted before the application will start.

Features

• Scheduled speed tests using a cron expression, plus on-demand runs from the UI or API.
• A static Nuxt web UI served by the Go application.
• SQLite and PostgresSQL database support
• Paginated results, latest-result, and time-series API endpoints.
• Generated OpenAPI schema and Swagger UI.
• Prometheus metrics, including a native histogram of Speedtest duration.
• OpenTelemetry tracing support.
• Optional OpenID Connect (OIDC) authentication.

Quick start with Docker Compose

Docker Compose is the recommended way to run v2. It starts the application, PostgreSQL, and Jaeger for local trace inspection.

Create a .env file beside docker-compose.yaml with a private runtime key:

RUNTIME_PSK=replace-with-the-output-of-openssl-rand-hex-32

For example:

openssl rand -hex 32

Then build and start the stack:

docker compose up --build -d

Open . The included PostgreSQL volume retains results between restarts. Jaeger's UI is available at .

To stop the stack without removing its data:

docker compose down

Configuration

Configuration is read from environment variables (and a local .env file when running the binary directly). See the full configuration reference, including result retention, scheduled tests, Healthchecks.io, and observability.

For optional OpenID Connect authentication setup, see Authentication.

Local development

The project uses mise to provision the backend tooling. The frontend has its own frontend/mise.toml for Node.js and pnpm.

mise install
cd frontend
mise install
mise exec -- pnpm install --frozen-lockfile
cd ..
mise run build-ui

Create a local .env file:

ACCEPT_EULA=true
RUNTIME_PSK=replace-with-a-random-value
APP_UI_DIR=frontend/.output/public
DB_DRIVER=sqlite
DB_URL=speedtest-tracker.db

Start the application and its development dependencies:

mise run serve

For iterative frontend development, run the Nuxt development server separately:

cd frontend
mise run ui

The frontend API base URL defaults to http://localhost:8080. Generate its TypeScript client from the running service with:

cd frontend
mise run client

Run backend tests with:

mise run test

Building the container image

The Dockerfile builds the Nuxt UI first, copies its static output to /ui, then builds the Go binary into a small non-root runtime image.

docker build -t speedtest-tracker:local .

The image expects a database and the configuration described above. Use the supplied Compose stack when you need a ready-to-run PostgreSQL deployment.

Notes on v2

This branch is a new implementation. The legacy Laravel/React configuration, authentication, notification, backup, and external-service integration instructions from v1 do not apply to v2.