Docker Installation

"Zero to Hero. ⚡ Just Like That"
As the Muses sing it, so can you do it! Get the JockeyBox-server running on your hardware in no time!

Prerequisites

You'll need Docker Engine and Docker Compose. Quick sanity check:

Terminalbash

docker --version
# Docker version 24.0.x or higher

docker compose version
# Docker Compose version v2.x.x

Note

If either of those fails, get Docker sorted first. Troubleshooting Docker installs is a rabbit hole I won't go down here — the official docs are your best bet.

Create a Directory

Pick a spot for your config and data. Doesn't really matter where — just be consistent.

Terminalbash

mkdir -p ~/jockeybox
cd ~/jockeybox

Docker Compose File

Create a docker-compose.yml in that directory. This is the whole stack — the API, the database, and optionally pgAdmin if you want a visual way to poke around the DB.

docker-compose.ymlyaml

# JockeyBox Self-Hosted Server
# https://jockey-box.app/setup/docker
#
# Usage:  docker compose up -d
#
# ⚠ Change all default passwords before starting.

services:

  jockeybox-api:
    image: ghcr.io/sunbrolynk/jockeybox-server:latest
    container_name: jockeybox-api
    restart: unless-stopped
    ports:
      - "16399:16399"
    environment:
      - DATABASE_URL=postgresql://jockeybox:changeme@jockeybox-db:5432/jockeybox
      - SECRET_KEY=change-this-to-a-random-string
      - ALLOWED_ORIGINS=*
      - TZ=America/Denver
    depends_on:
      jockeybox-db:
        condition: service_healthy
    networks:
      - jockeybox

  jockeybox-db:
    image: postgres:16-alpine
    container_name: jockeybox-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=jockeybox
      - POSTGRES_PASSWORD=changeme
      - POSTGRES_DB=jockeybox
    volumes:
      - jockeybox-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U jockeybox"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - jockeybox

  jockeybox-pgadmin:  # Optional — remove this whole block if you don't need it
    image: dpage/pgadmin4:latest
    container_name: jockeybox-pgadmin
    restart: unless-stopped
    ports:
      - "5050:80"
    environment:
      - PGADMIN_DEFAULT_EMAIL=admin@jockey-box.app
      - PGADMIN_DEFAULT_PASSWORD=changeme
    depends_on:
      - jockeybox-db
    networks:
      - jockeybox

volumes:
  jockeybox-data:

networks:
  jockeybox:
    driver: bridge

Change the defaults

Seriously — swap out every changeme before you start anything. Generate a good secret key with: openssl rand -hex 32

Environment File (optional)

If you'd rather not have passwords sitting in your compose file, use a .env file in the same directory instead:

.envenv

# Database
POSTGRES_USER=jockeybox
POSTGRES_PASSWORD=your-secure-password-here
POSTGRES_DB=jockeybox

# API
SECRET_KEY=your-random-secret-key
ALLOWED_ORIGINS=*
TZ=America/Denver

# pgAdmin (optional)
PGADMIN_DEFAULT_EMAIL=admin@jockey-box.app
PGADMIN_DEFAULT_PASSWORD=your-pgadmin-password

Then swap the hardcoded values in docker-compose.yml for ${VARIABLE_NAME} references. There's an example on GitHub if you want to see the full thing.

Fire It Up

Terminalbash

# Pull the images
docker compose pull

# Start everything
docker compose up -d

# Make sure it's all running
docker compose ps

You should see three containers up and healthy:

Output

NAME               IMAGE                                   STATUS          PORTS
jockeybox-api      ghcr.io/sunbrolynk/jockeybox-server     Up (healthy)    0.0.0.0:16399->16399/tcp
jockeybox-db       postgres:16-alpine                       Up (healthy)    5432/tcp
jockeybox-pgadmin  dpage/pgadmin4:latest                    Up              0.0.0.0:5050->80/tcp

Verify It's Working

Hit these in a browser:

http://localhost:16399 — should return a health check response

http://localhost:16399/docs — interactive Swagger docs for the API

http://localhost:5050 — pgAdmin (if you kept it in the stack)

Connecting from your phone

Swap localhost for your server's LAN IP — something like 192.168.1.100:16399. If you need access outside your network, you'll want a reverse proxy. That's covered in Configuration.

Logs

Terminalbash

# Everything
docker compose logs

# Follow in real time
docker compose logs -f

# Just the API
docker compose logs jockeybox-api

Stopping

Terminalbash

# Stop (keeps your data)
docker compose down

# Stop and NUKE all data (don't do this unless you mean it)
docker compose down -v

Heads up

The -v flag wipes the database volume. Everything — vehicles, records, fuel logs, achievements — gone forever. Back up first.

← Previous Overview Next → Configuration