Getting Started

Getting started

Start with a shelf, a folder or one title you know well. You can grow your library gradually and use physical cataloging, local files or connected services independently.

1. Open Downloads. Choose the full Linux / Docker ZIP for native Linux, the small Docker setup ZIP for a prebuilt image on Linux Intel/AMD, or the Windows x64 ZIP. Windows remains the separate experimental older download; it does not include the current Linux/Docker features. The application includes the built interface; source archives are for developers.
2. Verify and extract the installation package, keeping its files together. Follow its START-HERE.md and platform guide. First-download publisher trust requires independent confirmation of the signing-key fingerprint; a checksum alone does not establish the publisher. The Updates guide explains the verifier.
3. Follow ZIP installation or the Docker quick start. For Linux's setup wizard, choose direct or home-network access. To recover an existing library, follow Recovery before creating a fresh installation.
4. Open the appropriate address. Claim the first local owner profile using the recovery key read privately on the server. Keep the key for password recovery; normal sign-in uses your username and password.
5. Complete the setup screens. Add one physical item, index a configured source folder, or deliberately connect Plex/Jellyfin. Selecting a source category in setup does not connect that service or start an import. Allow time for the optional starter reference databases on first startup.
6. Open the title, review its details and sources, and save any correction. Add it to a collection if you want a shelf or group. Configure a backup destination before adding more work you want to protect.

Choose where to begin

• Your physical collection: add a title or scan a barcode, review the edition and record the copy's format and location. You can catalog a shelf without connecting a media server or adding files.
• Files on a drive: configure a readable folder on the server, index it and review the matches. Linked files stay where they are. For a large library, preview bulk matching before confirming links.
• An existing media server: add your Plex/Jellyfin connection and sync its catalog. Connected titles can sit alongside physical copies and local files in the same library.

Read Using your library for those workflows and Organizing collections for grouping titles and recording activity.

Use the exact Linux, current Docker or Windows guide for commands. Source folders must already be mounted and readable by the service account. A backup destination must be separately writable. Indexing and linking do not copy or rename original files.

For Docker, the user and host-folder example shows how to use your own UID/GID and a dedicated data bind folder. Keep personal settings in .env and compose.override.yaml, beside compose.yaml. Update an existing installation with its current user and storage first; changing a mount does not move your library.

With Portainer, Dockhand or another manager, use the Compose file URL, or repository https://github.com/blankboxcode/blankbox-community, branch main, path deploy/docker-image/compose.yaml. It pulls the public image and has no build step. Keep an existing stack's project and storage settings; Portainer Web editor deployment has been checked; see Docker and Portainer for the walkthrough. Other managers may handle updates differently. For an existing library, use the checked updater to retain its user and paired recovery snapshot.

If a step fails, retain the extracted package and existing data, record the step and a redacted error, and use Setup help. Do not delete a library to retry installation.

For an existing library, follow Updating Blank Box. For password recovery or optional identity-provider sign-in, see Accounts and Sign-in.