yaris-obd/server

yaris-obd remote server

A small Flask + Postgres API that receives trip/GPS log batches and dashcam video files uploaded by the Pi (see the repo root readme.md and PLAN.md for the overall project). Designed to run as a docker-compose stack on an unraid server (or any Docker host).

What it does

• GET /health — unauthenticated liveness check.
• POST /api/v1/tracking/batch — bulk-insert a batch of GPS/trip points.
• POST /api/v1/dashcam/upload — upload one dashcam video file (multipart, content-addressed by sha256 so retries/duplicates are safe).

Both upload endpoints require two headers: X-Device-Name and X-Api-Key (see Registering a device below). Postgres is not published to the LAN — only the api container talks to it, over the internal compose network.

Deploying on unraid

1. Get the code onto the unraid box (same repo as the Pi, just the server/ sub-folder matters here):

   ssh root@<unraid-ip>
   mkdir -p /mnt/user/app/git && cd /mnt/user/app/git
   git clone [email protected]:quoije/yaris-obd.git
   cd yaris-obd/server
   

2. Copy the env template and fill in a real Postgres password:

   cp .env.example .env
   nano .env   # set POSTGRES_PASSWORD, and DATA_DIR if you want data on the array
   

   Recommended DATA_DIR for unraid: /mnt/user/appdata/yaris-obd-server (keeps Postgres data + dashcam files on the array, backed up like your other appdata).
3. Build and start the stack:

   docker compose up -d --build
   

   This is also importable into unraid's Compose Manager plugin if you'd rather manage start/stop/updates from the Unraid UI.
4. Confirm it's healthy:

   docker compose ps
   curl http://localhost:8098/health
   

Registering a device and getting an API key

Run this once per device (e.g. once for the Pi) after the stack is up:

docker compose exec api python3 scripts/create_device.py yaris-2013

This prints a one-time API key — copy the YARIS_UPLOAD_DEVICE_NAME / YARIS_UPLOAD_API_KEY values into the Pi's upload-client config. Only the key's sha256 hash is stored server-side; the raw key is never shown again (re-run the script with the same device name to rotate/replace the key).

Exposing it outside the LAN

Two options, either works with this API unchanged:

• Cloudflare Tunnel (already running on this unraid box): add a public hostname rule in the Cloudflare dashboard pointing at http://<unraid-lan-ip>:8098 (or http://api:8098 if you point the tunnel at the api container directly on the compose network). Good for small tracking-data batches; large dashcam uploads may hit the tunnel's per-request size limit.
• Router port-forward (fallback if needed): forward an external port to <unraid-lan-ip>:8098 and let your router/firewall (e.g. Unifi) handle the security side. No changes needed here either way.

For large dashcam uploads from home, consider adding a local DNS override/rewrite (e.g. in AdGuard Home, same trick used for yaris.local on the Pi) so the hostname resolves directly to the unraid LAN IP while on the home network, bypassing the tunnel entirely for big transfers.

Toggling dashcam uploads off

The Pi's web UI has a setting to pause dashcam file uploads while keeping GPS/trip log uploads running — no server-side change needed, the Pi simply stops calling /api/v1/dashcam/upload while the toggle is off.

Local development / testing without unraid

cd server
cp .env.example .env   # edit POSTGRES_PASSWORD
docker compose up --build
curl http://localhost:8098/health