How to Install Docker and Run Pacefinder

When Docker is the right choice

Docker packages the Pacefinder listener and all its dependencies into a single image, so you can run it on any machine without installing Python or managing versions. It's the best fit for an always-on box — a home server, a NAS, or a Raspberry Pi sitting next to your wheel — because the container can restart automatically and stays isolated from the rest of the system.

Step 1: Install Docker

macOS

Download Docker Desktop for Mac from docker.com/products/docker-desktop. Pick the build that matches your chip — Apple silicon for M1/M2/M3/M4 Macs, or Intel for older models. Open the downloaded .dmg, drag Docker to Applications, then launch it. Docker is ready when the whale icon in the menu bar stops animating.

Windows

Download Docker Desktop for Windows from the same page. The installer enables the WSL 2 backend automatically on Windows 10 and 11. After installing, launch Docker Desktop and wait for the whale icon in the system tray to settle. You may be prompted to install a WSL 2 kernel update — follow the link the installer provides.

Linux

Install Docker Engine using the official convenience script, then add your user to the docker group so you don't need sudo for every command:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker "$USER"
# log out and back in for the group change to take effect

Step 2: Verify Docker is working

Open a terminal and confirm the client and daemon are both responding:

docker --version
docker run --rm hello-world

If docker --version prints a version number and hello-world downloads and prints its welcome message, you're ready. If you instead see command not found: docker, Docker isn't installed or Docker Desktop isn't running — launch it and try again.

Step 3: Run Pacefinder

Pull and run the Pacefinder image from GitHub Container Registry. It's multi-arch, so the same command works on Intel, AMD, and ARM hosts:

docker run --rm \
  -p 5300:5300/udp -p 8000:8000 \
  -v "$(pwd)/data:/data" \
  ghcr.io/estetika101/pacefinder:latest

What each flag does:

• -p 5300:5300/udp — publishes the UDP telemetry port. The /udp suffix is required; telemetry will not arrive without it.
• -p 8000:8000 — publishes the dashboard. Open http://localhost:8000 once the container is up.
• -v "$(pwd)/data:/data" — stores your sessions in a data folder in the current directory so they survive container restarts.

To keep Pacefinder running in the background and restart it after a reboot, drop --rm and add -d --restart unless-stopped.

Updating to a new release

Pull the newest image and recreate the container. If you pinned a version tag, bump it to the new release first:

docker pull ghcr.io/estetika101/pacefinder:latest

Troubleshooting

command not found: docker

Docker isn't installed, or Docker Desktop is installed but not launched. On macOS and Windows, open Docker Desktop and wait for the whale icon to settle. On Linux, start the service with sudo systemctl start docker.

permission denied while trying to connect to the Docker daemon (Linux)

Your user isn't in the docker group yet. Run sudo usermod -aG docker "$USER", then log out and back in.

port is already allocated

Something else is using port 8000 or 5300. Stop the other process, or remap the dashboard to a free port — for example -p 8080:8000, then open http://localhost:8080.

What to do next

With the container running, the last step is to send it telemetry. Point your game's UDP Data Out at the host machine's IP address on port 5300, and Pacefinder will start logging the moment you hit the track.