Configuration

Tuning things to your liking, getting remote access set up, and pointing the app at your server.

Environment Variables

Everything is configured via environment variables. Most of the defaults are fine — the only two you absolutely must set are DATABASE_URL and SECRET_KEY.

Variable	Default	What it does
`DATABASE_URL`	—	PostgreSQL connection string (required)
`SECRET_KEY`	—	Random string used to sign auth tokens (required)
`ALLOWED_ORIGINS`	`*`	CORS origins. Use `*` for local testing, your actual domain in production
`TZ`	`UTC`	Timezone — affects reminders and log timestamps
`PORT`	`16399`	Port the API listens on inside the container
`LOG_LEVEL`	`info`	How chatty the logs are: `debug`, `info`, `warn`, `error`
`MAX_VEHICLES`	`50`	Vehicle limit per account (raise or lower as you see fit)
`MAX_UPLOAD_SIZE`	`10MB`	Max size for receipt photo uploads
`ENABLE_REGISTRATION`	`true`	Set to `false` once you've created your accounts to lock it down
`BACKUP_SCHEDULE`	`0 3 * * *`	Cron expression for automatic backups
`COMMUNITY_CATALOG`	`true`	Send/receive parts data to/from the community catalog

Community Catalog

The COMMUNITY_CATALOG flag controls whether your server participates in the shared parts database. Users can also toggle this per-device in the app settings. Only part names, numbers, pricing, and vehicle fitment (year/make/model) are shared — never personal info.

Reverse Proxy

If you want to access JockeyBox from outside your home network — or just want HTTPS — throw a reverse proxy in front of it. Here are configs for the usual suspects.

Nginx Proxy Manager

Probably the easiest option if you're already running it. Add a proxy host:

Setting	Value
Domain	`jockeybox.yourdomain.com`
Forward Hostname	`jockeybox-api` or your server's IP
Forward Port	`16399`
SSL	Let's Encrypt, force SSL
Websockets	Enabled

Nginx (manual config)

nginx.confnginx

server {
    listen 443 ssl;
    server_name jockeybox.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/jockeybox.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/jockeybox.yourdomain.com/privkey.pem;

    location / {
        proxy_pass         http://127.0.0.1:16399;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

Caddy

Caddy handles SSL automatically — shortest config of the bunch.

Caddyfilecaddy

jockeybox.yourdomain.com {
    reverse_proxy localhost:16399
}

SWAG (Secure Web Application Gateway)

If you're running SWAG from LinuxServer.io, drop this into your proxy-confs directory:

jockeybox.subdomain.confnginx

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name jockeybox.*;

    include /config/nginx/ssl.conf;
    include /config/nginx/proxy.conf;
    include /config/nginx/resolver.conf;

    set $upstream_app jockeybox-api;
    set $upstream_port 16399;
    set $upstream_proto http;

    location / {
        include /config/nginx/proxy.conf;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }
}

SWAG networking

With bridge networking, the JockeyBox stack and SWAG need to share a Docker network for SWAG to resolve jockeybox-api. If you're using network_mode: host on everything, skip the container name and point SWAG at localhost:16399 instead.

Traefik (labels)

If you manage routing through Docker labels, add these to the jockeybox-api service in your docker-compose.yml:

docker-compose.yml (labels)yaml

jockeybox-api:
    image: ghcr.io/sunbrolynk/jockeybox-server:latest
    # ... other config ...
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.jockeybox.rule=Host(`jockeybox.yourdomain.com`)"
      - "traefik.http.routers.jockeybox.entrypoints=websecure"
      - "traefik.http.routers.jockeybox.tls.certresolver=letsencrypt"
      - "traefik.http.services.jockeybox.loadbalancer.server.port=16399"
    networks:
      - jockeybox
      - traefik  # whatever your Traefik network is called

Traefik (file provider)

If you keep your routing config in files instead of labels, add a dynamic config file:

jockeybox.ymlyaml

http:
  routers:
    jockeybox:
      rule: "Host(`jockeybox.yourdomain.com`)"
      entryPoints:
        - websecure
      service: jockeybox
      tls:
        certResolver: letsencrypt

  services:
    jockeybox:
      loadBalancer:
        servers:
          - url: "http://<server-ip>:16399"

Make sure this file is in a directory Traefik is watching via the file provider in your static config. Replace <server-ip> with your server's actual IP — or the Docker service name if Traefik shares a network with the stack.

Don't forget

Once you're behind a reverse proxy, change ALLOWED_ORIGINS from * to your actual domain — e.g. https://jockeybox.yourdomain.com.

Connecting the App

With the server running, open the JockeyBox app on your phone:

Go to Settings → Server
Pick "Self-Hosted"
Enter your server URL — something like http://192.168.1.100:16399 on your LAN, or https://jockeybox.yourdomain.com if you set up a reverse proxy
Create an account (the credentials live on your server, not mine)
That's it — you're tracking

Want to share with family? Point their phones at the same server URL. Everyone gets their own account, shared vehicles are managed in the app.

pgAdmin

If you left pgAdmin in the compose file, hit http://<your-server-ip>:5050 and add a server connection:

Setting	Value
Host	`jockeybox-db`
Port	`5432`
Database	`jockeybox`
Username	`jockeybox`
Password	Whatever you set `POSTGRES_PASSWORD` to

Why jockeybox-db and not my server IP?

With the default bridge networking, pgAdmin runs inside the same Docker network as the database, so it resolves jockeybox-db automatically. The database port (5432) isn't exposed to the host in this setup, so <server-ip>:5432 won't work unless you explicitly map it in your compose file.

Using host networking?

If you run your containers with network_mode: host, Docker's internal DNS doesn't apply — all containers share the host's network stack directly. In that case, use localhost or your server's IP as the host in pgAdmin (and everywhere else), and ports are bound on the host as-is. The same goes for reverse proxy configs — point them at localhost:16399 instead of the container name.

← Previous Docker Installation Next → Updating & Backups