Skip to content

Install and upgrade

Requirements

  • Docker Engine with the Docker Compose plugin
  • A few minutes for the application and its supporting services to download and start

Docker Compose creates and starts the application, PostgreSQL, and Redis. New installations use PostgreSQL automatically. Existing Kuzu installations require the migration wizard described below.

New installation with Docker Compose

git clone https://github.com/pickles4evaaaa/mybibliotheca.git
cd mybibliotheca
python3 scripts/setup_docker.py
docker compose up -d

That is all the configuration needed for a basic installation. The setup command creates a private .env file with the secure values the application and PostgreSQL need. You do not need to open or edit it. Keep it beside docker-compose.yml and do not share or commit it.

Open http://localhost:5054 and follow the setup page to create the administrator account. Your application files are stored in ./data; PostgreSQL stores its data in the postgres_data Docker volume. Keep both for backups and future upgrades.

To confirm that the services started, run docker compose ps. For startup help, see Troubleshooting.

For a server exposed to the internet, put the app behind a reverse proxy with HTTPS. HTTPS is required for browser camera access.

The production Compose file pulls the published pickles4evaaaa/mybibliotheca:3.0.0 image. Keep the image tag aligned with the release you intend to install.

Upgrade from Kuzu to PostgreSQL

Version 3.0.0 changes the primary database to PostgreSQL. An existing Kuzu database is preserved and remains active after the application upgrade. The upgrade does not migrate the library by itself. An administrator must complete the database migration wizard.

  1. Schedule a maintenance window and stop normal use. Back up the full data/ directory and PostgreSQL storage. Keep separate copies outside the server if possible.
  2. Update your Compose file to the 3.0.0 version. The new file adds PostgreSQL and the postgres_data volume. Keep your existing ./data:/app/data mount, .env secrets, and custom ports/proxy settings. Run python3 scripts/setup_docker.py to fill in missing required settings; it preserves existing non-empty values. If you already have an initialized PostgreSQL data volume, keep its original POSTGRES_PASSWORD because changing .env does not change the password stored in that database. Do not use docker compose down -v or remove any data. See the Compose update notes.
  3. Update the app to version 3.0.0 and start PostgreSQL and the app. Keep the original Kuzu files in data/kuzu:
git pull
docker compose pull
docker compose up -d
docker compose ps
  1. Sign in as an administrator and open Admin → Database Migration.
  2. Complete the wizard in order: create and verify the Kuzu backup, check PostgreSQL, then start the migration and verification. The PostgreSQL target must be empty of application data. If the wizard reports a problem, follow its instructions; do not manually truncate the database.
  3. Wait for the wizard to report PostgreSQL as active. Check users, books, reading history, covers, and integrations before normal use resumes.
  4. Keep the original Kuzu database and verified backups until you are satisfied with the migration.

After PostgreSQL accepts new writes, the retained Kuzu database is no longer a current rollback copy. Recover using a PostgreSQL backup. See Backups & restore and the detailed migration guide.

Environment essentials

The Docker setup command creates the required security and database settings automatically. For optional application settings, see .env.example; basic installations do not need any changes. Keep .env private. The Compose file connects to its bundled PostgreSQL service by default; custom POSTGRES_HOST, POSTGRES_DB, POSTGRES_USER, or POSTGRES_DSN values are only needed for a custom database deployment.

Routine upgrades

For an existing PostgreSQL installation, update the Compose file to the desired release tag, then pull and restart:

git pull
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 bibliotheca

Read release notes before each upgrade and keep current backups. Do not remove the postgres_data volume or data/ directory when replacing containers.

Run from source

For development only, use the supplied development Compose file, which includes PostgreSQL and Redis:

docker compose -f docker-compose.dev.yml up -d --build

Verify the installation

  • The application and PostgreSQL containers are healthy/running.
  • The setup or login page loads and an administrator can sign in.
  • A test book can be added by title or ISBN.
  • The book remains after docker compose restart.
  • A backup can be created and downloaded.