From 628907bb206d3cabda8a6b0b0f4a1794e924ed5a Mon Sep 17 00:00:00 2001
From: Jean-Luc Makiola <business@jeanlucmakiola.de>
Date: Sun, 15 Mar 2026 21:53:29 +0100
Subject: [PATCH] docs: add user-facing README and update compose for
 production

Add README with Docker setup instructions for self-hosting. Update
docker-compose.yml to use the pre-built registry image instead of
local build, and add a healthcheck against /api/health.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md          | 81 ++++++++++++++++++++++++++++++++++++++++++++++
 docker-compose.yml |  8 ++++-
 2 files changed, 88 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 8e01772..7ae8f51 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,83 @@
 # GearBox
 
+A single-user web app for managing gear collections (bikepacking, sim racing, etc.), tracking weight and price, and planning purchases through research threads.
+
+## Features
+
+- Organize gear into categories with custom icons
+- Track weight and price for every item
+- Create setups (packing lists) from your collection with automatic weight/cost totals
+- Research threads for comparing candidates before buying
+- Image uploads for items and candidates
+
+## Quick Start
+
+### Docker Compose (recommended)
+
+Create a `docker-compose.yml`:
+
+```yaml
+services:
+  gearbox:
+    image: gitea.jeanlucmakiola.de/makiolaj/gearbox:latest
+    container_name: gearbox
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_PATH=./data/gearbox.db
+    volumes:
+      - gearbox-data:/app/data
+      - gearbox-uploads:/app/uploads
+    healthcheck:
+      test: ["CMD", "bun", "-e", "fetch('http://localhost:3000/api/health').then(r=>r.ok?process.exit(0):process.exit(1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 10s
+      retries: 3
+    restart: unless-stopped
+
+volumes:
+  gearbox-data:
+  gearbox-uploads:
+```
+
+Then run:
+
+```bash
+docker compose up -d
+```
+
+GearBox will be available at `http://localhost:3000`.
+
+### Docker
+
+```bash
+docker run -d \
+  --name gearbox \
+  -p 3000:3000 \
+  -e NODE_ENV=production \
+  -e DATABASE_PATH=./data/gearbox.db \
+  -v gearbox-data:/app/data \
+  -v gearbox-uploads:/app/uploads \
+  --restart unless-stopped \
+  gitea.jeanlucmakiola.de/makiolaj/gearbox:latest
+```
+
+## Data
+
+All data is stored in two Docker volumes:
+
+- **gearbox-data** -- SQLite database
+- **gearbox-uploads** -- uploaded images
+
+Back up these volumes to preserve your data.
+
+## Updating
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+Database migrations run automatically on startup.
diff --git a/docker-compose.yml b/docker-compose.yml
index 5c1e704..bafc3dc 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,6 +1,6 @@
 services:
   gearbox:
-    build: .
+    image: gitea.jeanlucmakiola.de/makiolaj/gearbox:latest
     container_name: gearbox
     ports:
       - "3000:3000"
@@ -10,6 +10,12 @@ services:
     volumes:
       - gearbox-data:/app/data
       - gearbox-uploads:/app/uploads
+    healthcheck:
+      test: ["CMD", "bun", "-e", "fetch('http://localhost:3000/api/health').then(r=>r.ok?process.exit(0):process.exit(1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 10s
+      retries: 3
     restart: unless-stopped
 
 volumes: