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.