Skip to content

Configuration

What kataba needs from its server is configured with environment variables: in the file .env in kataba's directory when it runs with Node.js, or in the container's environment with Docker. A change takes effect when kataba is restarted.

Everything else, such as the instance's name, its accent colour or how long users stay signed in, is a setting that admins change in kataba itself.

Environment variables

Variable What it is
DATABASE_URL The MariaDB connection string, e.g. mysql://kataba:secret@localhost:3306/kataba. Required.
UPLOAD_DIR The directory for uploaded images, their variants and attachments, e.g. ./uploads. It must not lie in kataba's public/ directory, so that kataba alone decides who may see a file. Required; the Docker image sets it to /data/uploads.
AUTH_URL The public address of the instance, as users reach it through the reverse proxy, e.g. https://kataba.example.com. Sign-in redirects back to it, and printed guides name it in their attribution line.
AUTH_SECRET The secret that signs the sessions and encrypts the SMTP password of the email settings. Generate it with npx auth secret or openssl rand -base64 33. Required; changing it signs everyone out, and the SMTP password has to be entered again.
AUTH_AUTHENTIK_ID The client ID of the Authentik application, see Sign-in and roles. Required.
AUTH_AUTHENTIK_SECRET The client secret of the Authentik application. Required.
AUTH_AUTHENTIK_ISSUER The issuer URL of the Authentik application, e.g. https://authentik.example.com/application/o/kataba/. Required.
KATABA_ADMIN_GROUP The Authentik group whose members become admins, see Groups and roles. .env.example and the Compose setup preset kataba-admins.
KATABA_AUTHOR_GROUP The Authentik group whose members become authors. .env.example and the Compose setup preset kataba-authors.
PORT The port kataba listens on. Default 3000.

The Docker image adds one of its own:

Variable What it is
KATABA_SKIP_MIGRATIONS 1 starts the container without applying pending database migrations first.

The Compose setup assembles DATABASE_URL from DB_NAME, DB_USER and DB_PASSWORD and maps KATABA_PORT on the host to kataba's port.

Reverse proxy and rate limits

Guests may report problems too. To keep spam out, kataba allows each guest address five reports in fifteen minutes, and each signed-in user the same. It takes a guest's address from the X-Forwarded-For header, the last address in it, which the reverse proxy in front of kataba appends (nginx with $proxy_add_x_forwarded_for, Caddy and Traefik by default); else from X-Real-IP. Without either, all guests share one limit. The count lives in kataba's memory and starts over when kataba restarts.