📚 How to install & use BookBinder

BookBinder helps you catalogue every book in your home using your phone camera and Claude AI. Choose your install method below, then follow the cataloguing steps.

Install Docker Desktop

Download and install Docker Desktop from docker.com — it's free.

Mac: download the .dmg, drag to Applications, launch it
Windows: download the installer, run it, restart if asked
Linux: follow the instructions at docs.docker.com/engine/install

When Docker starts up, it will offer to create an account — you don't need one.
Look for the small 'Skip' link in the top right of that screen

Wait until Docker Desktop shows "Docker is running" before continuing.

Download and unzip BookBinder

Download BookBinder from the download page and unzip it into a permanent folder — somewhere like Documents/BookBinder/ rather than Downloads, as Docker needs to find it each time you start.

💡 If you see a folder called {app,docker,docs} inside after unzipping, just delete it — it's a harmless artefact of the zip process.

Start BookBinder

🍎 Mac shortcut: double-click mac/Start BookBinder.command in the bookbinder folder — it starts BookBinder and opens your browser automatically. No Terminal needed. Also download the Mac Launcher zip for a proper .app option via Platypus.

⚠️ Important — Mac .app users: wherever you put BookBinder Launcher.app when you first double-click it, that's where BookBinder will be installed. Choose a permanent location — such as your Applications folder or Documents — before running it for the first time. Moving it afterwards requires stopping Docker and restarting from the new location.

Windows / Linux — or if you prefer the command line on Mac — open a Terminal or Command Prompt, navigate to the bookbinder folder, and run:

docker compose up -d

Docker sets everything up automatically — database included. When it's done, open your browser and go to:

http://localhost:8585

phpMyAdmin is also available at http://localhost:8586 for importing your book SQL.

⏱ The first run takes a minute or two to download. Every start after that is instant.

Set your editor password

Open app/config.php in any text editor and find this line:

define('BB_EDIT_PASS_HASH', password_hash('bookbinder', PASSWORD_DEFAULT));

Replace bookbinder with your chosen password. Anyone can browse your catalogue — only someone with this password can edit it.

Photograph, zip and upload to Claude

See Cataloguing your books below — it's the same for everyone.

Import the SQL Claude generates

Option A — phpMyAdmin (included)

phpMyAdmin is included — go to http://localhost:8586, select the bookbinder database, click the SQL tab, paste and click Go.

Option B — Command line

docker exec -i bookbinder_db mysql -u bookbinder -pbookbinder123 bookbinder << 'EOF'
-- paste your SQL here
EOF

✅ The SQL uses INSERT IGNORE — safe to re-run as many times as you like. Duplicates are silently skipped.

Requirements

A web server running PHP 7.4+
A MySQL or MariaDB database
Access to phpMyAdmin or similar

Upload the app files

Download BookBinder from the download page and unzip it. Upload the contents of the app/ folder to your web server — either to a subdirectory (e.g. yourdomain.com/bookbinder/) or the root.

Make sure the uploads/bookcases/ folder exists and is writable. In your hosting file manager or via FTP, set its permissions to 755 (or 775 if uploads still fail).

Create the database tables

In phpMyAdmin, select your database, click the SQL tab, and paste the contents of docker/init.sql from the zip. This creates the books and bookcases tables.

💡 You can use an existing database — BookBinder's tables won't interfere with other apps.

Edit config.php

Open app/config.php and set your database credentials:

$host = 'your-db-host';
$db   = 'your-database-name';
$user = 'your-db-username';
$pass = 'your-db-password';

Also set your editor password — replace bookbinder with your own:

define('BB_EDIT_PASS_HASH', password_hash('bookbinder', PASSWORD_DEFAULT));

💡 If you get a "No such file or directory" database error, add ;port=3306 to the DSN line in config.php — some shared hosts need an explicit TCP port.

Photograph, zip and upload to Claude

See Cataloguing your books below — it's the same for everyone.

Import the SQL Claude generates

In phpMyAdmin, select your database, click the SQL tab, paste the SQL from Claude and click Go.

✅ The SQL uses INSERT IGNORE — safe to re-run as many times as you like.

Cataloguing your books

These steps are the same whether you used Docker or a manual install.

Take photos of your bookcase shelves

For best results:

One shelf per photo — don't try to capture the whole bookcase in one shot
Straight on — stand directly in front of the shelf, not at an angle
Good light — natural daylight or overhead; avoid flash glare on spines
Fill the frame — get close enough that spine text is readable
One wide-angle overview shot per bookcase too — useful for the bookcase card photo

📱 Tip: 3–5 close-up shelf shots per bookcase, then one overview. iPhone or Android both work fine.

Zip the photos for each bookcase

Group each bookcase's photos into a folder and zip it. Name it clearly:

bcase1_lounge_main.zip
bcase2_hall_by_stairs.zip
bcase3_study.zip

Mac: select photos → right-click → Compress.
Windows: select photos → right-click → Send to → Compressed folder.

💡 You can do multiple bookcases at once — just zip them separately and upload together.

Open a new chat with Claude

Go to claude.ai and start a new chat. Paste this prompt:

I'm cataloguing my home library using BookBinder. I'll upload zipped photos of each bookcase and I need you to:

1. Read all the book spines in the photos
2. Generate SQL INSERT statements in this format:

INSERT IGNORE INTO books (title, author, category, sub_category, bookcase, shelf, location_name, notes) VALUES
('Title Here', 'Author Name', 'Category', 'Sub-category or NULL', BOOKCASE_NUMBER, SHELF_NUMBER, 'Room Name', 'any notes');

Rules:
- category should be one of: Fiction, Non-Fiction, Sailing, Medical, TEFL, Reference, Gardening, Cookery, Art, Music, Humour, Games, Sport, Motoring, Health, Poetry, Nature, Travel, DIY, Magazines
- sub_category for Medical: Anatomy, Osteopathy, Homeopathy, Nutrition, Physiotherapy, Orthopaedics, Clinical, Alternative Health
- shelf numbers count from top (1=top shelf)
- bookcase number is the number I give you with each upload
- Use NULL for unknown authors
- Flag unclear titles with 'Title unclear - check' in notes

After each bookcase, output the complete SQL block ready to paste into phpMyAdmin.

Ready — I'll upload bookcase 1 now.

Upload your zip files to Claude

Drag your zip files into the Claude chat. Tell Claude which bookcase number each one is and what room it's in:

These are bookcases 1, 2 and 3.
Bookcase 1 = Lounge
Bookcase 2 = Hall by stairs
Bookcase 3 = Study

Claude reads the spines and generates the SQL for each bookcase.

💡 If a title is hard to read, Claude flags it in the notes column so you can check later.

Add bookcase photos (optional but lovely)

Log in and go to the Bookcases page. Upload your overview shot for each bookcase — it appears on the bookcase card so you can see at a glance where a book lives.

Browse, search and tidy up

On the Browse page you can:

Search by title or author
Filter by bookcase or category using the sidebar
Expand categories with a ▶ arrow to filter by sub-category
Edit any book inline with the ✏️ button (log in first)
Add books manually with the + Add Book button
Mark books as lent out and record who has them

💡 Books flagged as 'Title unclear' are worth a quick follow-up photo to Claude — a clearer shot of just that shelf usually does it.

Tips for a good catalogue session

Do one room at a time — it's less overwhelming
Keep a consistent bookcase numbering scheme from the start
Note the room name in the zip filename — you'll thank yourself later
If you have a very large collection, Claude can process 3–4 bookcases per chat before hitting image limits — just start a new chat and paste the setup prompt again
Magazines are best catalogued as bundles: one entry with a date range in notes (e.g. Yachting Monthly, bundle 2011–2017)
Medical and TEFL books benefit most from sub-categories — worth the extra few seconds
Updating BookBinder (easiest method — Mac & Windows) — open Docker Desktop, click the 🗑 dustbin next to each BookBinder container to remove them. Then double-click BookBinder Launcher.app (Mac) or run docker compose up -d from the bookbinder folder (Windows) to reinstall. Your data is preserved unless you also delete the volume.

· · · Guide and helper with screenshots - how we did it · ·