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=1to 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
dbvolume. 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_URLto the public address users reach it at. - User: kataba runs as the unprivileged user
nodein 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.