Installing

Install PostgreSQL 16 or newer and create a user and database for Kribble:

sudo apt install postgresql
sudo -u postgres psql -c "CREATE USER kribble WITH PASSWORD '<db-password>';"
sudo -u postgres createdb kribble -O kribble

Kribble creates and updates its tables itself when it starts.

Install Meilisearch v1.12 or newer and run it as a service, listening on localhost only. Generate a master key with openssl rand -hex 32 and use it in place of <meili-master-key>. You also put it in config.toml later.

curl -L https://install.meilisearch.com | sh
sudo mv ./meilisearch /usr/local/bin/
sudo useradd --system --shell /usr/sbin/nologin --create-home --home-dir /var/lib/meilisearch meilisearch
sudo mkdir -p /var/lib/meilisearch/data
sudo chown -R meilisearch:meilisearch /var/lib/meilisearch

sudo tee /etc/systemd/system/meilisearch.service > /dev/null <<'EOF'
[Unit]
Description=Meilisearch
After=network.target

[Service]
User=meilisearch
Group=meilisearch
WorkingDirectory=/var/lib/meilisearch
ExecStart=/usr/local/bin/meilisearch --db-path /var/lib/meilisearch/data --env production --master-key <meili-master-key> --http-addr 127.0.0.1:7700
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now meilisearch
curl http://127.0.0.1:7700/health   # {"status":"available"}

Redis is only needed if you will run more than one kribble-web process. Keep it on localhost:

sudo apt install redis-server
sudo sed -i 's/^bind .*/bind 127.0.0.1 -::1/' /etc/redis/redis.conf
sudo systemctl restart redis-server
redis-cli ping   # PONG

For PDF export, install Chromium (Debian: chromium) or Google Chrome. Kribble finds chromium, chromium-browser, google-chrome and google-chrome-stable on PATH or in /usr/bin. Anything else needs [pdfgen].chrome_path.

The fonts PDFs are set in (Inter, JetBrains Mono for code, and Fraunces and IBM Plex Mono for templates made in the PDF designer) are built into Kribble. Chromium uses the server's own fonts only for characters those lack, such as Chinese or Japanese, and for the designer's Serif (system) and Sans (system). Install a font package such as fonts-noto if those print as empty boxes.

Copy the tarball to the server, unpack it and run install.sh:

tar xzf kribble-linux-amd64.tar.gz
sudo bash install.sh

The installer:

• creates the system user kribble with home /opt/kribble

• copies kribble-web and kribble-builder to /opt/kribble/

• replaces /opt/kribble/downloads/ with the tarball's downloads/

• creates /opt/kribble/config.toml from config.toml.example if it doesn't exist yet, owned by kribble with mode 600

• writes /etc/systemd/system/kribble-web.service and kribble-builder.service if they don't exist yet. Existing units are left alone.

• starts both services only if config.toml already has a postgres:// DSN

INSTALL_DIR changes the install location (default /opt/kribble). KRIBBLE_WEB_BIN and KRIBBLE_BUILDER_BIN point the installer at binaries in another place. KRIBBLE_PORT and BUILDER_PORT set the ports in a new config.toml; after that, change [server].port and [builder].port there.

Open /opt/kribble/config.toml and set at least the following. Generate each secret with openssl rand -hex 32.

[server]
frontend_url = "https://kribble.example.com"   # used in emails and site links

[security]
jwt_secret     = "<64 hex characters>"
refresh_secret = "<another 64 hex characters>"

[database]
dsn = "postgres://kribble:<db-password>@localhost:5432/kribble?sslmode=disable"

[meili]
host = "http://127.0.0.1:7700"
key  = "<meili-master-key>"

[storage]
backend = "disk"
dir     = "/opt/kribble/data"

[storage.s3]
# Also used by the disk backend: where public sites load their assets from.
public_bucket_url = "https://kribble.example.com/files-public"

For S3 storage, set backend = "s3" and fill in [storage.s3] instead. Configuration lists every setting.

sudo systemctl enable --now kribble-web kribble-builder
systemctl status kribble-web kribble-builder
curl -i http://127.0.0.1:8080/healthz    # 200
curl -i http://127.0.0.1:8081/healthz    # 200, the builder

If a service doesn't start, journalctl -u kribble-web -n 50 shows the reason. See Troubleshooting.

Configure nginx or Caddy as described under Reverse proxy below, then open https://kribble.example.com.

The release does not include a Docker image. Build it from a checkout of the repository, at the commit you want to run:

docker build -f deploy/Dockerfile -t kribble:latest --build-arg VERSION=$(git describe --tags --always) .

The image contains kribble-web, kribble-builder and the kribble CLI for every platform, in /app/downloads. It does not contain the editor extensions or the desktop apps.

To move the image to a server without building it there:

docker save kribble:latest | gzip > kribble-docker.tar.gz
# on the server:
docker load < kribble-docker.tar.gz

On the server, put docker-compose.yml (from the tarball or deploy/) and config.toml.example in a directory, for example /opt/kribble-docker, and create config.toml from the example:

cp config.toml.example config.toml
chmod 600 config.toml

Docker Compose reads .env next to docker-compose.yml to fill in the database password, the Meilisearch key and the published port. Kribble itself never reads this file, so the same values go into config.toml in the next step.

cat > .env <<'EOF'
POSTGRES_USER=kribble
POSTGRES_PASSWORD=<db-password>
POSTGRES_DB=kribble
MEILI_KEY=<meili-master-key>
KRIBBLE_PORT=8080
EOF
chmod 600 .env

KRIBBLE_PORT is the host port. Inside the container, Kribble always listens on 8080, so leave [server].port at its default.

Inside the Compose network, the services are reached by their service names:

[server]
frontend_url = "https://kribble.example.com"

[security]
jwt_secret     = "<64 hex characters>"
refresh_secret = "<another 64 hex characters>"

[database]
dsn = "postgres://kribble:<db-password>@db:5432/kribble?sslmode=disable"

[meili]
host = "http://meilisearch:7700"
key  = "<meili-master-key>"

[storage]
backend = "disk"
dir     = "/app/data"

[storage.s3]
public_bucket_url = "https://kribble.example.com/files-public"

# Only if you run several kribble-web replicas:
# [redis]
# url = "redis://redis:6379/0"

docker compose up -d
docker compose ps
docker compose logs -f kribble-web

All services have restart: unless-stopped, so they come back after a reboot as long as Docker starts at boot.