Quick Start
Run BookReplay with Docker Compose and import your first Kindle highlights.
This guide takes you from an empty directory to a running BookReplay instance with your Kindle highlights in it. Each instance has one owner account, which you create during setup.
Before you start
You need:
- A Linux x86-64 (
linux/amd64) host. ARM64, including Raspberry Pi and native Apple Silicon, is not yet supported or tested. - Docker Engine with Docker Compose 2.24.4 or newer.
My Clippings.txtfrom your Kindle, found in itsdocumentsfolder.
BookReplay runs as one application container next to PostgreSQL 17. Compose starts both.
Build from source
The checked-in deployment files describe ghcr.io/loukag/bookreplay:v0.1.0
as a planned first release. Use the source-build path unless you have confirmed
that your selected release image is published and accessible.
Install
Get the files
Clone the repository and run every later command from inside it:
git clone https://github.com/BookReplay/BookReplay.git
cd BookReplayConfigure the instance
Create your .env and restrict it to your user:
cp .env.example .env
chmod 600 .envGenerate two separate secrets by running this command twice:
openssl rand -hex 32Edit .env and set:
| Variable | Value |
|---|---|
POSTGRES_PASSWORD | The first generated value. |
SETUP_SECRET | The second generated value. Registration is disabled without it. |
BOOKREPLAY_IMAGE | The published version you chose, or an immutable image@sha256:… digest. Not needed when building from source. |
OPEN_LIBRARY_CONTACT_EMAIL | Optional. Your contact address for Open Library requests. |
Leave the ${POSTGRES_PASSWORD} reference in DATABASE_URL as it is. Compose expands it for you.
Start BookReplay
docker compose -f compose.yaml -f compose.dev.yaml up -d --build --wait
docker compose -f compose.yaml -f compose.dev.yaml logs --tail=50 bookreplayPass both -f arguments to every later docker compose command on this stack. The development override also exposes PostgreSQL on 127.0.0.1:5432.
up -d --wait returns once the database migrations have run and the application answers its health check.
Open the app
Go to http://localhost:2665.
Compose publishes BookReplay only on the host's loopback interface. If it runs on a remote server, open an SSH tunnel from your own computer and use the same URL:
ssh -N -L 2665:127.0.0.1:2665 user@your-serverCreate the owner account
Register with your setup secret, a name, an email address, and a password of 12 to 128 bytes. Then log in.
Registration stays closed once an owner exists. Remove SETUP_SECRET from .env and recreate the application to remove the secret from the running container. For a source-built stack:
docker compose -f compose.yaml -f compose.dev.yaml up -d --force-recreate bookreplayFor a published-image installation, omit both -f arguments.
Import your highlights
Open Import, select My Clippings.txt (up to 16 MiB), and import it. Your highlights appear in the library, grouped by book.
Covers and book details are filled in from Open Library in the background, so they can take a moment to appear. This needs outbound internet access.
You can import the same file again whenever you have new highlights. Only the new ones are added, and edits made in BookReplay are preserved. The result shows the number imported and any duplicates skipped. Choose Start revision to begin reviewing.
Check that your data persists
docker compose -f compose.yaml -f compose.dev.yaml restartFor a published-image installation, use docker compose restart. When the app is back, refresh the library and confirm your highlights are still there.
Keep your data safe
Your library lives in the Docker volume bookreplay_postgres_data with the default Compose project name. Stopping, restarting, or replacing containers keeps it. Keep the project name stable to reuse the same volume.
For a source-built stack:
docker compose -f compose.yaml -f compose.dev.yaml stop
docker compose -f compose.yaml -f compose.dev.yaml start
docker compose -f compose.yaml -f compose.dev.yaml down
docker compose -f compose.yaml -f compose.dev.yaml up -d --build --waitThese commands stop, resume, remove, and recreate containers respectively, while keeping the database volume. Omit both -f arguments and --build when using a published image.
`down -v` deletes your library
docker compose down -v removes the database volume and everything in it.
Take a backup first.
Changing POSTGRES_PASSWORD in .env does not change the password of a database that already exists. Do not delete the volume to fix a credential mismatch.
Next steps
- Use your library: learn about editing, book identification, reviews, and daily progress.
- Configure the instance: see metadata, privacy, and browser access settings.
- Access from other devices: follow the HTTPS setup and owner recovery guide. The supplied operator guide advises against using the development Compose override for public deployments.
- Keep your library safe: follow Backups and upgrades.