Kitodo.Production 4.0 on Ubuntu 24.04 on Azure User Guide

Overview

Kitodo.Production is the open source production module of the Kitodo suite, used by libraries and archives to plan, control and track the digitization of books, journals, manuscripts, printed music and other materials. It coordinates scanning, metadata capture, quality control and export across configurable production workflows, and provides a web interface for projects, processes and a structured METS/MODS metadata editor. Install the cloudimg image and you have your own private digitization production server ready on first boot. The image installs Kitodo.Production 4.0.0 from the official release WAR on Apache Tomcat 10 under OpenJDK 21, backed by a MariaDB database and an OpenSearch search backend (via HibernateSearch). Tomcat and OpenSearch are bound to the loopback interface and Kitodo is fronted by nginx on port 80, alongside an unauthenticated health endpoint. A unique administrator password is generated on the first boot of every VM by rotating Kitodo's well known default testAdmin / test credential, and the seeded demo accounts are deactivated, so no VM ever ships with a known credential. Backed by 24/7 cloudimg support.

What is included:

• Kitodo.Production 4.0.0 deployed from the official release WAR on Apache Tomcat 10 under OpenJDK 21
• MariaDB database (schema imported from the official Kitodo 4.0.0 SQL dump) bound to the loopback interface
• OpenSearch 2.19.6 (Apache-2.0) as the HibernateSearch search backend, bound to the loopback interface
• Tomcat bound to 127.0.0.1:8080, fronted by nginx on port 80 proxying /kitodo
• Port 80 serving an unauthenticated /healthz endpoint for load balancer probes
• A unique testAdmin account password rotated on first boot from Kitodo's default testAdmin / test, recorded in a root only file
• The seeded demo user accounts deactivated so no known credential is login-able
• mariadb, opensearch, tomcat10 and nginx as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_D2s_v4 (2 vCPU / 8 GiB RAM) is a sensible starting point because the image runs three JVM-backed services (Tomcat, OpenSearch and MariaDB); size up for heavier production workloads and larger collections. NSG inbound: allow 22/tcp from your management network and 80/tcp (and 443/tcp if you add TLS) for the web interface. Kitodo is served over plain HTTP by default, so for production put your own domain and a trusted certificate in front of it (see Maintenance).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Kitodo.Production by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Then Review + create then Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name kitodo \
  --image <marketplace-image-urn> \
  --size Standard_D2s_v4 \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

After the VM is created, open port 80 so you can reach the web interface:

az vm open-port --resource-group <your-rg> --name kitodo --port 80 --priority 900

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

The first boot rotates the administrator password and prints a summary to the message of the day, so your first SSH session shows the web interface URL and where the credentials file lives.

Step 4 - Confirm the services are running

Kitodo runs on Tomcat behind nginx, backed by MariaDB and OpenSearch. Confirm all four services are active, that Tomcat and OpenSearch are bound to the loopback interface, and that the health endpoint answers:

systemctl is-active mariadb.service opensearch.service tomcat10.service nginx.service
ss -tlnp | grep -E '127.0.0.1:8080|127.0.0.1:9200|:80 '
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/healthz

Step 5 - Retrieve your admin password and confirm the default is rotated

The per VM testAdmin password is written to a root only file at /root/kitodo-credentials.txt (mode 0600). The well known default testAdmin / test credential is rotated away on first boot, and the seeded demo accounts are deactivated:

sudo cat /root/kitodo-credentials.txt

Step 6 - Sign in to the Kitodo web interface

Open http://<vm-public-ip>/kitodo/ in your browser. You are redirected to the Kitodo sign-in page. Sign in as testAdmin with the password from the credentials file.

Step 7 - Explore the desktop

After signing in you land on the Kitodo desktop, which summarizes your tasks, processes and projects and shows database statistics. A worked "Example Project" ships with the image so you can see the layout immediately.

Step 8 - Manage projects, workflows and rulesets

The Projects area is where you configure the building blocks of a digitization workflow: projects, production templates, workflows, dockets, rulesets, import configurations and mapping files. Use it to adapt the shipped example to your own material and metadata rules.

Maintenance

• Add a domain and TLS. Kitodo is served over plain HTTP on port 80 by default. For production, point a DNS name at the VM and terminate TLS in front of it (for example with a certificate from your own CA or Let's Encrypt via a reverse proxy or the Azure Application Gateway). Never expose the plain HTTP endpoint to the public internet for real collections.
• Database and search backend. MariaDB (database kitodo) and OpenSearch are both bound to the loopback interface and are reachable only by Kitodo on the VM. Back up the MariaDB kitodo database regularly; the search index can be rebuilt from the database via Kitodo's indexing page if needed.
• Configuration. Kitodo's rulesets, OPAC configuration, XSLT and other config live under /usr/local/kitodo. The web application is deployed at /var/lib/tomcat10/webapps/kitodo##4.0.0.
• Users. The shipped image has a single active administrator (testAdmin) with the per VM password. Create additional users and roles from the Users area of the web interface; the seeded demo accounts are deactivated and can be re-enabled from there if you want the example users.
• Security updates. The image ships fully patched with unattended-upgrades enabled, so OS security updates continue on your VM.

Support

Every cloudimg image is backed by 24/7 support. If you need help deploying or operating Kitodo.Production, contact cloudimg support.