GearBox/README.md

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)

Docker Compose (recommended)

Create a docker-compose.yml:

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:

docker compose up -d

GearBox will be available at http://localhost:3000.

Docker

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

docker compose pull
docker compose up -d

Database migrations run automatically on startup.

Tech Stack

• Runtime & Package Manager: Bun
• Frontend: React 19, Vite, TanStack Router, TanStack Query, Tailwind CSS v4, Zustand
• Backend: Hono, Drizzle ORM, SQLite (bun:sqlite)

Local Development Setup

Prerequisites

You must have Bun installed on your machine. Docker is not required for local development.

Installation

1. Install all dependencies:

   bun install
   

2. Initialize the local SQLite database (gearbox.db):

   bun run db:push
   

3. Start the development servers:

   bun run dev
   

   This single command will start both the Vite frontend server (port 5173) and the Hono backend server (port 3000) concurrently.

Open http://localhost:5173 in your browser to view the app.

Additional Commands

• bun run build — Build the production assets into dist/client/
• bun test — Run the test suite
• bun run lint — Check formatting and lint rules using Biome
• bun run db:generate — Generate Drizzle migrations after making schema changes