# Speedtest Tracker (LinuxServer.io) – Installation Runbook

## Purpose
Deploy **Speedtest Tracker** using the **LinuxServer.io Docker image** to automatically track internet performance over time using Ookla Speedtest.

This runbook covers:
- Application key requirements
- Docker Compose configuration
- Initial access and login
- Validation checks

---

## 1. Prerequisites

- Docker and Docker Compose installed
- A persistent storage location available on the host
- LAN access to the host
- Known timezone (e.g. `Pacific/Auckland`)

---

## 2. Application Key (APP_KEY)

⚠️ **Mandatory** – the container will refuse to start without an application key.

The LinuxServer.io image **does not generate an APP_KEY automatically**.  
A valid key **must be generated externally** and provided via environment variables **before the container starts**.

### Important notes
- The key must be in `base64:` format
- The key must remain stable for the lifetime of the deployment
- Regenerating the key later will invalidate encrypted data

---

## 3. Create Docker Compose File

Create or edit `docker-compose.yml`:

```
services:
  speedtest-tracker:
    image: lscr.io/linuxserver/speedtest-tracker:latest
    container_name: speedtest-tracker
    restart: unless-stopped
    ports:
      - "8765:80"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Pacific/Auckland
      - DISPLAY_TIMEZONE=Pacific/Auckland
      - APP_KEY=base64:REDACTED
      - APP_URL=http://192.168.50.253:8765
      - DB_CONNECTION=sqlite
      - SPEEDTEST_SCHEDULE=0 * * * *
    volumes:
      - /mnt/storage01/docker/speedtest-tracker:/config
```

## 4. Prepare Persistent Storage

Ensure the host directory exists and is owned by the configured PUID/PGID.

```
bash
mkdir -p /mnt/storage01/docker/speedtest-tracker
chown -R 1000:1000 /mnt/storage01/docker/speedtest-tracker
```

## 5. Start the Container

Start the service using Docker Compose:

```
bash
docker compose up -d
```

## 6.  Access the site 

```
http://<IP_ADDRESS>:8765
```

## 7.  Initial Login

The LinuxServer.io image includes a pre-seeded default administrator account.
Use the following credentials to log in for the first time:

```
Email:    admin@example.com
Password: password
```

## 8.  User Account

Now go create a new user, made it an administrator.
Logout as admin, and sign in with newly create account.
Change the admin again to a user account, delete the guest account.


## FIN