Skip to content

Running with Docker

kataba is published as a Docker image on Docker Hub, mikognn/kataba, for linux/amd64 and linux/arm64:

Tag Points to
1.3.0 exactly this release; each release has its own tag
latest the latest release

Pin a release, such as 1.3.0, rather than latest, so that an update happens when you choose to update.

The image contains kataba only. It needs a MariaDB database and Authentik; the Compose setup brings the database along.

With Docker Compose

The example setup in docker/ of kataba's repository runs kataba together with MariaDB; Authentik stays external. As it comes, compose.yaml builds the image from the checked-out source:

git clone https://git.mike-ochmann.de/MassiveDynamic/kataba.git
cd kataba/docker
git checkout v1.3.0      # the release to run
cp .env.example .env     # then fill in the values
docker compose up -d --build

To use the published image instead, which needs only compose.yaml and .env.example on the server, replace the build: section of the kataba service with image: mikognn/kataba:1.3.0, and start it with docker compose up -d.

docker/.env holds the values from the configuration: the Authentik application, AUTH_URL and AUTH_SECRET, plus the database's:

Variable What it is Default
DB_NAME The name of the MariaDB database kataba
DB_USER The database user kataba
DB_PASSWORD The database user's password; required
KATABA_PORT The port on the host that kataba listens on 3000

Compose assembles DATABASE_URL from them. MariaDB creates the database and its user only on its first start, so changing DB_NAME, DB_USER or DB_PASSWORD later needs a new, empty db volume. Use only letters, digits, - and _ in them: they end up in a URL.

With docker run

With a MariaDB of your own, run the image directly and pass the configuration as environment variables:

docker run -d --name kataba -p 3000:3000 \
  -v kataba-uploads:/data/uploads \
  -e DATABASE_URL="mysql://kataba:secret@db-host:3306/kataba" \
  -e AUTH_URL="https://kataba.example.com" \
  -e AUTH_SECRET="…" \
  -e AUTH_AUTHENTIK_ID="…" -e AUTH_AUTHENTIK_SECRET="…" \
  -e AUTH_AUTHENTIK_ISSUER="https://authentik.example.com/application/o/kataba/" \
  mikognn/kataba:1.3.0

What to know about the container

  • Migrations: the container applies pending database migrations on every start, so a new, empty database gets its tables on the first one, and an update needs nothing more than the new image. Set KATABA_SKIP_MIGRATIONS=1 to start without migrating.
  • Uploads: images and attachments are stored in /data/uploads, a volume. Keep it on a named volume or a directory of the host, never in the container, and give it room to grow.
  • Data: in the Compose setup, the database lives in the db volume. Back up both volumes, or download a backup from kataba.
  • Port and proxy: kataba listens on port 3000 in the container. Put a reverse proxy that terminates TLS in front of it, and set AUTH_URL to the public address users reach it at.
  • User: kataba runs as the unprivileged user node in the container.
  • Building the image yourself, from a checkout of the release: docker build -t kataba . in the repository's root.

Docker is for running kataba. To work on kataba's code, see Development in the README.