Skip to content

Complete Beginners Guide

Jump to bottom
deucebucket edited this page Jan 8, 2026 · 5 revisions

Complete Beginner's Guide

Never used GitHub or Docker before? This guide is for you.

From "I found this project" to "my audiobooks are organized" - no prior technical knowledge required.

What You're Looking At

You found this project on GitHub. GitHub is just a website where people share code - like a recipe website, but for software. You don't need to understand the code, just download and run it.

Library Manager is a web app that runs on your computer (or NAS). Once running, you access it through your browser like any website.

Choose Your Installation Method

Method Difficulty Best For
Docker (recommended) Easy Windows, Mac, Linux, NAS (UnRaid, Synology) - simplest updates
Direct Python Medium Any OS - if you're comfortable with command line

If you're not sure, use Docker. It works on Windows, Mac, and Linux, and updates are just one command.

Option 1: Docker Installation (Recommended)

What is Docker?

Docker is like a shipping container for software. Everything the app needs is packed inside, so it "just works" without you installing a bunch of stuff.

Step 1: Install Docker

On Windows:

  1. Download Docker Desktop
  2. Run the installer
  3. Restart your computer when prompted
  4. Open Docker Desktop and let it start up

On Mac:

  1. Download Docker Desktop
  2. Drag to Applications folder
  3. Open Docker Desktop

On Linux:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in

On Synology:

  1. Open Package Center
  2. Search for "Container Manager" (or "Docker" on older DSM)
  3. Install it

On UnRaid:

  • Docker is built-in, you're good to go!

Step 2: Create the App Folder

Create a folder where Library Manager will store its settings:

  • Windows: C:\docker\library-manager
  • Mac/Linux: ~/docker/library-manager
  • Synology: /volume1/docker/library-manager

Step 3: Run the Container

Example (Windows) - run this in PowerShell or Command Prompt:

docker run -d --name library-manager --restart unless-stopped -p 5757:5757 -v "D:\Audiobooks:/audiobooks" -v "C:\docker\library-manager:/data" ghcr.io/deucebucket/library-manager:latest

Windows tip: Press Win + X then click "Terminal" or "PowerShell". Paste the command (right-click to paste), but change D:\Audiobooks to your actual audiobook folder.

Example (Linux/Mac):

docker run -d --name library-manager --restart unless-stopped -p 5757:5757 -v "/mnt/media/audiobooks:/audiobooks" -v "$HOME/docker/library-manager:/data" ghcr.io/deucebucket/library-manager:latest

Replace:

  • /mnt/media/audiobooks or D:\Audiobooks with where your audiobooks actually are
  • The config folder with the one you created in Step 2

Step 4: Open the App

Open your browser and go to: http://localhost:5757

Option 2: Direct Python Installation

Step 1: Install Python

Windows:

  1. Go to python.org/downloads
  2. Download Python 3.10 or newer
  3. Important: Check "Add Python to PATH" during installation

Mac:

brew install python3

Linux (Ubuntu/Debian):

sudo apt update && sudo apt install python3 python3-pip python3-venv git

Step 2: Download the App

Easiest way (no git needed):

  1. Go to the releases page
  2. Download the "Source code (zip)" file
  3. Extract it to a folder (e.g., C:\library-manager on Windows)
  4. Open a terminal in that folder:
    • Windows: Open the folder in File Explorer, click the address bar, type cmd, press Enter
    • Mac/Linux: Right-click in folder → "Open Terminal"

Or with git:

git clone https://github.com/deucebucket/library-manager.git
cd library-manager

Step 3: Install Requirements

pip install -r requirements.txt

On some systems you may need pip3 instead of pip.

Step 4: Run the App

python app.py

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

The Setup Wizard

When you first open Library Manager, you'll see a setup wizard. Here's what each step does:

Step 1: Welcome

Welcome

Shows the 3-step process: Scan → Identify → Fix. Click "Get Started".

Step 2: Library Paths

Library Paths

Tell it where your audiobooks are:

  • Docker users: Enter /audiobooks (this maps to your real folder from the docker command)
  • Direct install: Enter the actual path like /mnt/audiobooks or D:\Audiobooks

You can add multiple paths if your books are in different places.

Step 3: Media Type

Media Type

What are you organizing?

  • Audiobooks Only - MP3, M4B, audio files (default)
  • Ebooks Only - EPUB, PDF, MOBI files
  • Both - Manage everything together

Step 4: AI Provider

AI Provider

How should it identify your books? All cloud options need a free API key.

  • Google Gemini (Recommended) - Fast, accurate, 1,500 free requests/day
  • OpenRouter - Access to many AI models, lower rate limits on free tier
  • Ollama (Local) - Runs AI on your own computer, no API key needed

Getting API Keys:

Step 5: Safety Settings

Safety Settings

How hands-on do you want to be?

  • Auto-Fix Mode - OFF = you approve every change, ON = auto-fix obvious stuff
  • Trust the Process - ON = also fix moderate-confidence matches

Tip: Start with both OFF until you trust the results.

Step 6: Review & Start

Review

Confirm your choices and click "Start Scanning!"

Using the App

After the wizard, you'll see the Dashboard. Here's the typical workflow:

  1. Library page → Your scanned books appear here
  2. Process Queue → Click this to have AI identify messy folder names
  3. Pending tab → Review suggested fixes
  4. Apply → Accept fixes you agree with

That's it! Repeat as you add new books.

Getting an API Key

You need a free API key to use the AI features. Here's how to get one:

Google Gemini (Recommended - 1,500 free requests/day)

  1. Go to aistudio.google.com
  2. Sign in with your Google account
  3. Click "Get API Key" in the left sidebar
  4. Click "Create API Key"
  5. Copy the key and paste it in the setup wizard (or Settings → AI Setup)

OpenRouter (Alternative)

  1. Go to openrouter.ai
  2. Create an account
  3. Go to Keys
  4. Click "Create Key"
  5. Copy the key and paste it in the setup wizard (or Settings → AI Setup)

Updating the App

Docker:

docker pull ghcr.io/deucebucket/library-manager:latest
docker stop library-manager
docker rm library-manager
# Run the docker run command again from Step 3

Direct Python:

cd library-manager
git pull
pip install -r requirements.txt
# Restart the app

Common Questions

Where are my settings saved?

  • Docker: In the /data folder you mounted
  • Direct install: In the same folder as the app

Can I access it from my phone? Yes! Use your computer's IP instead of localhost: http://192.168.1.xxx:5757

Port 5757 is already in use? Change the port in the docker command: -p 5758:5757

The wizard didn't appear? It only shows for fresh installs. Go to Settings to change configuration.

Getting Help

Clone this wiki locally