📚 How to install & use ShelfMate

ShelfMate catalogues your books, vinyl records and CDs 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 ShelfMate

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

Start ShelfMate

🍎 Mac — easiest: download the Mac Launcher and double-click ShelfMate Launcher.app — it starts ShelfMate and opens your browser automatically. No Terminal needed.

⚠️ Mac users: wherever you put ShelfMate Launcher.app when you first double-click it, that's where ShelfMate will be installed. Choose a permanent location — such as your Applications folder or Documents — before running it for the first time.

🪟 Windows — easiest: unzip the ShelfMate download, then right-click Install ShelfMate.bat and choose Run as administrator. A progress window will guide you through — it asks where to install (defaults to Documents) and opens your browser when ready.

Managing via Docker Desktop

After installation, open Docker Desktop and you'll see your software listed with Start and Stop buttons. You can start and stop from there at any time (or just quit Docker to stop).

Linux / command line: navigate to the shelfmate folder and run:

docker compose up -d

Then open http://localhost:8585 in your browser.

phpMyAdmin is also available at http://localhost:8586 if you ever need direct database access.

💡 First run only: the browser opens automatically but you may see an empty page — the database is initialising in the background. Wait 20–30 seconds and refresh. Every start after that is instant.

🔁 Next time: make sure Docker Desktop is open (launch it and wait for "Docker is running" if it's not), then double-click ShelfMate Launcher.app (Mac) or start.bat (Windows) again — that's all you need to do.

Set your editor password

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

define('SM_EDIT_PASS_HASH', password_hash('shelfmate', PASSWORD_DEFAULT));

Replace shelfmate 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 collection below — it's the same for everyone.

Import the SQL Claude generates

Log in to edit (default password is 'shelfmate' change in config as above if required), then go to Import SQL in the top menu. Paste the SQL from Claude, or upload it as a .sql file — check the preview, then confirm.

✅ Uses INSERT IGNORE — safe to re-run as many times as you like. Import runs as a single transaction, so a mistake can't leave your catalogue half-updated.

Requirements

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

Upload the app files

Purchase and download ShelfMate from the download page and unzip it.

Create a folder for ShelfMate on your server — e.g. shelfmate/ — and upload the contents of the app/ folder into it (not the app/ folder itself). Your ShelfMate site will then be at https://yourdomain.com/shelfmate/.

Make sure the uploads/bookcases/ folder exists and is writable. 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 — ShelfMate'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 shelfmate with your own:

define('SM_EDIT_PASS_HASH', password_hash('shelfmate', PASSWORD_DEFAULT));

💡 If you get a "No such file or directory" database error, add ;port=3306 to the DSN line in config.php.

Photograph, zip and upload to Claude

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

You're live

Open your browser and go to the folder you uploaded ShelfMate to — e.g. https://yourdomain.com/shelfmate/. No further startup steps are needed; your web server runs ShelfMate continuously, just like any other website.

Import the SQL Claude generates

Log in as editor, then go to Import SQL in the top menu. Paste the SQL from Claude, or upload it as a .sql file — check the preview, then confirm.

✅ Uses INSERT IGNORE — safe to re-run as many times as you like. Import runs as a single transaction, so a mistake can't leave your catalogue half-updated.

Already using BookBinder? Upgrade in minutes

Your entire catalogue moves across — no re-photographing, no re-typing.

Export from BookBinder

In BookBinder, log in as editor, then go to Export SQL in the top menu and download your catalogue as a .sql file.

💡 Running an older BookBinder without Export SQL? In phpMyAdmin, export the books and bookcases tables as data-only SQL with "INSERT IGNORE statements" checked.

Import into ShelfMate

Log in to ShelfMate as editor, then go to Import SQL in the top menu. Upload your .sql file (or paste its contents), check the preview, and confirm.

✅ Done — your full catalogue is in ShelfMate. No phpMyAdmin needed on the ShelfMate side, whether you're running Docker or shared hosting.

Bookcase photos

Photos don't transfer with the SQL — copy the contents of your BookBinder install's uploads/bookcases/ folder into ShelfMate's uploads/bookcases/ folder. Filenames match up, so your bookcase photos appear automatically.

After import: your catalogue carries across including any genre assignments. The new ShelfMate fields — condition, wishlist, purchase value and last read/played — will be blank to start with. Fill them in gradually using the inline ✏️ edit, or use Batch Edit to set condition or genre across a whole selection at once.

Errors about duplicate entries during import are harmless — entries that already existed are just skipped. Your data is fine.

Cataloguing your collection

These steps are the same whether you used Docker or a manual install. ShelfMate handles books, vinyl LPs and CDs equally well.

Take photos of your shelves and stacks

For best results:

One shelf per photo — don't try to capture everything in one shot
Straight on — stand directly in front, 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 — useful for the bookcase card photo
See also How to photograph your shelves opens in new tab

📱 Works for books, LP spines and CD stacks equally well. Claude can even read upside-down spines. iPhone or Android both work fine.

Zip the photos for each location

Group each bookcase or CD/LP stack's photos into a folder and zip it. Name it clearly:

bcase1_lounge_main.zip
lounge_lps_classical.zip
office_cds.zip

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

💡 You can do multiple stacks 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 collection using ShelfMate. I'll upload zipped photos of each bookcase, LP stack or CD stack and I need you to:

1. Read all the spines in the photos (books, LPs and CDs)
2. Generate SQL INSERT statements in this format:

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

Rules:
- category: Fiction, Non-Fiction, Music, Classical, Medical, Sailing, TEFL, Reference, Gardening, Cookery, Art, Humour, Games, Sport, Health, Poetry, Nature, Travel, DIY, Magazines
- sub_category for Music: CD or LP
- genre: for music use Jazz, Classical, Blues, Folk, Rock, Soul, Country, World etc. For fiction use Literary, Crime, Historical etc.
- shelf numbers count from top (1=top shelf), 0 = stacked flat
- bookcase number is the number I give you with each upload
- Use NULL for unknown authors/artists
- Flag unclear titles with 'Title unclear - check' in notes

After each stack, output the complete SQL block ready to paste into ShelfMate's Import SQL page.

Ready — I'll upload bookcase 1 now.

Now you can login to ShelfMate and import the SQL that Claude produces or paste it in (choose Import SQL top right after logging in)

Upload your zip files to Claude

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

These are bookcases 1, 2 and 3.
Bookcase 1 = Lounge main bookcase (books)
Bookcase 2 = Lounge LP stack by the hifi (vinyl records)
Bookcase 3 = Office CD rack (CDs)

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

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

Add location photos (optional but lovely)

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

Browse, search and tidy up

On the Browse page you can:

Search by title or author/artist
Filter by bookcase or category using the sidebar
Expand categories with a ▶ arrow to filter by sub-category or genre
Sort by any column — including Genre
Edit any item inline with the ✏️ button (log in first)
Add items manually with the + Add Book button
Mark items as lent out with the borrower's name
Wishlist items you want to find
Export your catalogue or wishlist to CSV
🎲 Random pick — browse by category for something to read or listen to tonight

💡 Items flagged as 'Title unclear' are worth a quick follow-up photo to Claude — a clearer close-up usually does it.

Organising your music collection by genre

Genre is one of ShelfMate's most powerful features for music collectors — here's the best way to use it.

Ask Claude to assign genres when cataloguing

The setup prompt above already includes genre. When uploading a stack of jazz LPs, tell Claude:

This is bookcase 7 — my jazz LP collection.
Please set genre = 'Jazz' for all of these unless you can identify a different genre from the spine.

Claude will set Jazz as the default and override where it recognises something different (Classical, Blues etc.).

💡 Works equally well for book genre — "this is my literary fiction shelf, set genre = Literary Fiction unless clearly otherwise."

Batch assign genres after import

Already imported without genres? Use the Batch Edit panel in the Browse page — no need to edit each item individually.

Filter the list — e.g. click Music in the sidebar, then LP under sub-category
Narrow further if needed — e.g. filter to a specific LP bookcase
Click ⚙ Batch edit this selection to expand the panel
Set field: Genre, To value: Classical (or Jazz, Blues, Folk etc.)
Click Apply to all N books and confirm

⚡ This is the fastest way to genre-tag a large collection. Filter to your Classical LP bookcase, batch set genre to Classical in one click — done. Repeat for each genre/location combination.

Browse and sort by genre

Once genres are assigned:

Click the Genre column header to sort your whole catalogue by genre — all your Classical together, all your Jazz together
Click the ▶ arrow next to Music in the sidebar to expand genre sub-filters
Click a genre in the sidebar to filter to just those items
Combine with category filter — e.g. Music → LP → Jazz for just jazz vinyl

💡 Genre works for books too — sort by genre to find all your Literary Fiction, or filter to Crime for a rainy afternoon.

Condition grading for vinyl

For vinyl collectors, the Condition field supports standard grades: Mint, NM, VG+, VG, Good, Fair, Poor.

You can add condition when editing any record inline (✏️ button), or set it during the Add Item form. Use the Purchase value field alongside condition for insurance records.

💡 Batch edit can also set condition across a selection — useful if you've just acquired a collection and want to mark it all as VG to start.

ShelfMate extras

A few features worth knowing about.

★

Wishlist

Mark any item as Wishlist status — either when adding manually or via the inline edit ✏️. Wishlist items appear in the sidebar with a count, styled differently in the browse list so they stand out.

Export your wishlist to CSV — useful to take to record fairs, second-hand bookshops or car boot sales.

★

Export to CSV

Go to the Export page (top nav). Filter by bookcase, category or wishlist, then download a CSV that opens in Excel, Numbers or Google Sheets.

Useful for insurance schedules, sharing your catalogue, or keeping an offline backup.

★

🎲 Random pick

Click 🎲 Random in the top nav. Filter by category if you want (Fiction only, Music only), then click the button — ShelfMate picks something at random from your shelves. Shows title, artist/author, location and condition. Hit it again if you're not feeling it.

💡 Great for breaking the "what shall I listen to tonight?" deadlock when you have 300 LPs to choose from.

Tips & things to know

Do one room at a time — it's less overwhelming
Keep a consistent bookcase numbering scheme from the start
Note the content in the zip filename — lounge_lps_jazz.zip is more helpful than bookcase7.zip
For large collections, Claude can process 3–4 bookcases per chat before hitting image limits — just start a new chat and paste the setup prompt again
Magazines and periodicals are best as bundles: one entry with a date range in notes (e.g. Yachting Monthly, bundle 2011–2017)
For LPs: photograph each stack from both sides if possible — some spines read left-to-right, some right-to-left
Genre batch edit works best when you organise your stacks by genre first — one zip per genre makes the batch assignment trivial
Use the Wishlist before record fairs — add everything you're looking for, export to CSV, take your phone or a printout
Log in to edit — click Log in in the top right and enter your editor password to access editing, batch edit and bookcase management
Updating ShelfMate (easiest method — Mac & Windows) — open Docker Desktop, click the 🗑 dustbin next to each ShelfMate container to remove them. Then double-click ShelfMate Launcher.app (Mac) or run docker compose up -d from the shelfmate folder (Windows) to reinstall. Your data is preserved unless you also delete the volume.
Updating files (Docker install) — find your ShelfMate folder on your computer (e.g. Documents/ShelfMate/) and replace files directly in the app/ subfolder. Changes take effect immediately — no Docker restart needed
Updating files (Mac .app install) — right-click ShelfMate Launcher.app → Show Package Contents → navigate to Contents/Resources/shelfmate/app/ to replace files

· · · shelfmate-guide and helper with screenshots - how we did it · ·