Introduction

Hobbyboard turns folders of photos, sketches, and screenshots into a searchable archive with semantic search, enriched tags, and beautiful boards — all on your own machine.

Quick Start

Get up and running in seconds. Select your platform below:

brew tap aravindhsampath/tap
brew install hobbyboard
hobbyboard
# Open http://localhost:9625

curl -O https://raw.githubusercontent.com/aravindhsampath/hobbyboard/main/docker-compose.yml
docker compose up -d
# Open http://localhost:9625

curl -O https://raw.githubusercontent.com/aravindhsampath/hobbyboard/main/docker-compose.yml
docker compose up -d
# Open http://localhost:9625

curl -O https://raw.githubusercontent.com/aravindhsampath/hobbyboard/main/docker-compose.yml
docker compose up -d
# Open http://localhost:9625

Installation Options

Hobbyboard offers flexibility for every type of user. Other installation options are listed below.

1. Package Managers (Recommended)

Use your OS package manager (brew, yum, apt, pacman). Example with Homebrew:

brew tap aravindhsampath/tap
brew install hobbyboard

2. Docker Compose

Easiest container setup via compose.

curl -O https://raw.githubusercontent.com/aravindhsampath/hobbyboard/main/docker-compose.yml
docker compose up -d
# Open http://localhost:9625

3. Docker Image Direct

Run the official image without compose:

docker run -d \
    --name hobbyboard \
    -p 9625:9625 \
    -v hb-config:/app/config \
    -v hb-data:/app/dist \
    -v ./raw_images:/app/raw_images \
    --add-host=host.docker.internal:host-gateway \
    ghcr.io/aravindhsampath/hobbyboard:latest
# Open http://localhost:9625

4. Pre-built Binaries

Download the latest release for your OS. Note: Requires ffmpeg and libheif to be installed on your system.

5. Build from Source (Cargo)

For developers who want the latest changes. Requires Rust toolchain.

git clone https://github.com/aravindhsampath/hobbyboard.git
cd hobbyboard
cargo build --release
./target/release/hobbyboard serve

Configuration

Hobbyboard is configured via a hobbyboard.toml file. On first launch, a default file is created in your working directory.

Most knobs you want to turn live here. Customize away.

Configuration Reference

Notes on AI Configuration

Vision models are configured via [ai].vision_model. You can customize [ai].prompt_analysis for domain-specific indexing.

Embedding models run locally via fastembed-rs and are set via [ai].embedding_model.

Technical Design

This section explains the end-to-end architecture for engineers who want to understand, self-host, or adapt Hobbyboard. Everything runs in a single binary — no external services required.

System Architecture

• Single binary: Axum web server + SQLite + USearch vector index + fastembed-rs embeddings. No external services required.
• Frontend: Vanilla JS/CSS/HTML embedded in the binary via rust-embed. Zero build tools needed.
• AI: Vision analysis via Ollama (local), OpenAI, or Gemini. Text embeddings are always generated locally by fastembed-rs — no API calls for search.

Control Flow & Auto-Dispatch

Running hobbyboard with no subcommand triggers auto-dispatch based on system state:

Explicit subcommands (setup, init, build, serve, export, auth reset) bypass auto-dispatch and run directly.

First Run & Onboarding

1. Run hobbyboard → no config found → onboarding web UI starts on port 9625.
2. Wizard checks dependencies (ffmpeg, libheif codecs).
3. User configures: AI provider, media source path, password, embedding model.
4. Wizard writes hobbyboard.toml + .env (API keys, password hash, signing key).
5. Triggers init (creates SQLite DB + USearch index) then build (processes media).
6. Process restarts via exec() → auto-dispatch detects config + DB → normal serve mode.

Build Pipeline (Image Lifecycle)

The build command runs a 3-phase pipeline orchestrated by src/ops/library.rs:

• Item ID: First 16 chars of the SHA-256 hash of the file content. Same content = same ID (deduplication).
• Supported formats: jpg, jpeg, png, webp, heic, avif (images); mp4, mov, webm, m4v (videos).
• Thumbnails: 4 WebP size variants stored under dist/images/{thumb,sm,md,lg}/.
• Video: Transcoded to MP4 via ffmpeg; frame thumbnails extracted for the grid view.
• AI output: Structured JSON — title, caption (dense description), tags[] (10–12 keywords), ocr (visible text or null).

Search & Retrieval

Search is hybrid: semantic vectors + full-text, fused with configurable weights.

• Vector search: USearch HNSW index with cosine similarity. Embeddings are generated locally by fastembed-rs — no API calls at query time.
• Text search: SQLite FTS5 with BM25 ranking across title, caption, auto_tags, ocr_text, manual_tags, and user_notes.
• Score fusion: combined = (vec_score × vector_weight) + (fts_score × fts_weight). Default: 30% vector, 70% FTS. Tune via [search] in the config.
• "More like this": The /api/similar/{id} endpoint returns cosine-nearest neighbors from the USearch index.

Data Model

All structured data lives in a single SQLite database (dist/data/hobbyboard.db, WAL mode). The USearch vector index (dist/data/vectors.usearch) is an on-disk cache — SQLite is the source of truth for embeddings.

Directory Layout

In Docker, these map to named volumes: hb-config (hobbyboard.toml + .env) and hb-data (dist/). The HB_CONFIG_DIR, HB_DIST_DIR, and HB_RAW_MEDIA_DIR env vars override default paths.

Operational Invariants

• Embedding model lock: On serve startup, the app checks that system_info.embedding_model matches the config. Mismatches are fatal — you must build --refresh to re-embed with a new model.
• Content-addressed identity: Item IDs are derived from file content (SHA-256), so the same file always gets the same ID regardless of filename or location.
• SQLite is source of truth: The USearch .usearch file is a cache rebuilt from the vector_keys table on each build. Delete it and the next build recreates it.

Failure Modes

• Missing ffmpeg: Video transcoding is skipped; build continues with image-only processing.
• Missing libheif: HEIC/AVIF decoding fails for those formats; other image formats still process.
• AI provider unreachable: Vision analysis fails for that item; item metadata is not created. Retryable on next build.
• Embedding model mismatch: Server refuses to start. Fix by running build --refresh with the correct model configured.
• Refresh build: AI metadata is reset; manual tags and notes are preserved but may reference items not yet re-processed.

Key Dependencies

Usage & Workflow

Hobbyboard operates in two modes: the CLI (for management and builds) and the Web UI (for browsing, searching, and organizing).

CLI Reference

The binary is a single-command orchestrator. All subcommands share the same config and storage.

Core Workflow

Or just run hobbyboard with no arguments — auto-dispatch handles the right action based on system state.

1. Setup Wizard

hobbyboard setup

• What it does: Launches an interactive web UI (port 9625) that walks you through AI provider selection, media path, password, and embedding model.
• Dependency check: Verifies ffmpeg and libheif (heif-info/heif-enc) are available.
• Output: Writes hobbyboard.toml and .env with your settings.

2. Library Initialization

hobbyboard init

• SQLite: Creates dist/data/hobbyboard.db with all tables and the FTS5 index.
• USearch: Initializes the HNSW vector index file at dist/data/vectors.usearch with the correct dimensions for your embedding model.
• Idempotent: Safe to run multiple times; won't overwrite existing data.

3. Build (Ingestion & Indexing)

hobbyboard build [--refresh] [--deep]

• --refresh: Wipes AI-generated metadata (descriptions, tags, embeddings) but preserves user data (manual tags, boards, notes). Use when changing AI provider or prompt.
• --deep: Full SHA-256 re-hash of every file to detect content changes that didn't update filesystem timestamps.

Pipeline stages:

1. Scan: Walk directory, hash files (SHA-256), diff against DB, skip unchanged.
2. Process (parallel): Generate 4 WebP thumbnail variants (480/960/1920/3840px), transcode video to MP4, apply EXIF orientation.
3. AI Analysis (serial): Send media to vision LLM, embed caption via fastembed-rs, store metadata + vector.

4. Serve

hobbyboard serve [--port 9625] [--ui-path ./frontend]

• Default port: 9625
• Frontend: Served from the embedded binary (via rust-embed), or from a local directory if --ui-path is set (useful for UI development).
• Auth: Password-based login with Argon2 hashing. Sessions use JWT cookies (hb_session) or Bearer tokens for API access.
• Search: Hybrid vector + FTS5 queries with configurable weights.

5. Other Commands

Environment Variables (.env)

Secrets and overrides are stored in .env (loaded automatically from HB_CONFIG_DIR or CWD):

Logs

Logs are written to both stdout and dist/logs/hobbyboard.log (rotating, max 50 MB). In Docker:

docker compose logs -f hobbyboard

Troubleshooting

Code Map

For engineers adapting Hobbyboard or contributing. The codebase is ~12,700 lines of Rust + ~1,400 lines of frontend JavaScript.