Skip to content

Install and upgrade

Requirements

  • Docker Engine and Docker Compose
  • A server with persistent storage for the data directory
  • A reverse proxy and HTTPS if you need camera scanning or remote access
  • Python 3.13+ only when running from source

Clone the repository and create the environment file:

git clone https://github.com/pickles4evaaaa/mybibliotheca.git
cd mybibliotheca
cp .env.example .env

Set unique values for SECRET_KEY and SECURITY_PASSWORD_SALT in .env, then start the application:

docker compose up -d --build
docker compose ps
docker compose logs -f bibliotheca

Open http://localhost:5054 and complete the first-time setup to create the administrator account.

Keep one worker

KuzuDB requires a single application worker. Keep WORKERS=1; do not scale the application horizontally against the same data directory.

The Compose configuration mounts ./data into /app/data. Keep that directory when replacing the container.

Environment essentials

SECRET_KEY=replace-with-a-long-random-value
SECURITY_PASSWORD_SALT=replace-with-another-long-random-value
KUZU_DB_PATH=/app/data/kuzu
GRAPH_DATABASE_ENABLED=true
WORKERS=1
TIMEZONE=UTC

Generate secrets with:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Never commit .env or share its secrets.

Upgrade checklist

  1. Create and download a fresh backup from Settings → Data & Import → Backup Manager.
  2. Record the current version and read the relevant release notes.
  3. Pull the new source or change the pinned image tag.
  4. Rebuild and restart:
docker compose up -d --build
  1. Check the logs for startup errors.
  2. Sign in and verify the library, a book detail page, reading logs, and the backup manager.

If the application does not start, do not delete data. See Troubleshooting and restore only after confirming which backup is valid.

Run from source

For development only:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python3 run.py

Use one worker when running Gunicorn as well:

gunicorn -w 1 -b 0.0.0.0:5054 run:app

Verify the installation

  • The container is running.
  • The setup or login page loads.
  • 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.