Skip to main content

Docling Serve (docling)

Document conversion service (PDF, Office, HTML, images with OCR) used by the knowledge base ingestion (EAI_DOCLING_URL).

Generated from catalog/services/docling.yaml: do not edit by hand.

Summary​

Version1.38.2
Useinstall and configure, configure and connect
Layerfunctional (AI catalog)
CategoryAI serving
Installation methodspython, podman
External connectionno
Sandbox onlyno

Licence​

SPDX identifierMIT
Licence policycore licence (MIT or Apache-2.0)
Licence exception-
Platform componentdocling

Packages and artifacts​

A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.

KindPackageVersionLicenceDetails
container imagequay.io/docling-project/docling-serve-cpuv1.38.2MITimage key docling, used by docling-serve, digest sha256:7a480a1604fa3b42efeddc7db9527690d9f9bc903226136013e2bfe6b1a4dfb0
Python packagedocling-serve1.38.2MITinterpreters, in order of preference python3.12, python3.11, python3.10

Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.

Supported systems and architectures​

MethodOperating systemsArchitectures
pythonRHEL family (dnf), Debian family (apt), Arch Linux (pacman)x86_64, aarch64 (not restricted by the descriptor)
podmanRHEL family (dnf), Debian family (apt), Arch Linux (pacman)x86_64, aarch64 (not restricted by the descriptor)

Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.

Prerequisites​

Host​

  • at least 4096 MB of memory (warning, memory).

Network and ports​

ComponentPort namePortOpened in the host firewall
docling-serveapi5001/tcpyes

Services and connections needed​

This service has no dependency.

Installation methods and modes​

MethodDefaultWhat the method uses
pythonyesa Python virtual environment holding the Python packages of the descriptor
podman-the container images of the descriptor, run by Podman under systemd

Components​

ComponentKindInstallation methodsPorts
Docling server (docling-serve)masterpython, podman5001/tcp

Single server (standalone) (default)​

One conversion server.

What the mode deploys:

ComponentPlacement
docling-servemin 1, max 1

Replicated (replicated)​

Several stateless servers behind the load balancer.

What the mode deploys:

ComponentPlacement
docling-servemin 2, recommended 2

Install this service​

The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.

  1. Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.

  2. Choose the service. On the Service step, select Docling Serve. The card shows the licence MIT. Pick the Method among python, podman (default python).

  3. Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: standalone (default), replicated. Each mode deploys the components listed in Installation methods and modes.

  4. Bindings. This service has no dependency: the Bindings step has nothing to bind.

  5. Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.

  6. Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.

  7. Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.

Connect an existing service​

Schemeshttps, http
Default port5001
Authenticationoptional
Health check/health
Authentication methodFieldsDescription
api_keyapi_keyKey of DOCLING_SERVE_API_KEY, sent in the X-Api-Key header.
none-Without DOCLING_SERVE_API_KEY the conversion API is open to anyone who reaches it.

Official documentation: https://github.com/docling-project/docling-serve/blob/main/docs/configuration.md

High availability​

Clusterreplicas (replication)
High availabilityexternal (external)
Failoverload balancer (load-balancer)
Replicationnone (none)
Quorumnone (none)
Discoverynone (none)
Entry pointload balancer (load-balancer)
Official documentationhttps://github.com/docling-project/docling-serve/blob/main/docs/deployment.md

Topology per mode​

ModesHighest catalog levelDistributionQuorum componentFault domainsDescription
standalonestandalone (standalone)single (single)-1One instance, no fault tolerance.
replicatedha (ha)active-active (active-active)-2Stateless replicas behind the load balancer (HAProxy and keepalived).

Notes​

  • The catalog mode runs the local engine in every server: a conversion in progress is lost with its server and an asynchronous task is only known by the server that received it. The distributed RQ engine (Redis and OCR workers) of the official documentation is not deployed by this mode.

Configuration parameters​

Network​

ParameterTypeDefaultAllowed valuesRequiredSecretRestartDescription
API port (port)port5001-nonoyesPort of the conversion API.
TLS (tls_enabled)boolfalse-nonoyesServe the API and the web console in HTTPS with a certificate of the Manager CA (uvicorn options --ssl-certfile and --ssl-keyfile of docling-serve run, UVICORN_SSL_CERTFILE and UVICORN_SSL_KEYFILE in the container); the health checks and the links then use https.

Processing​

ParameterTypeDefaultAllowed valuesRequiredSecretRestartDescription
Workers (workers)int2min 1, max 32nonoyesConversion workers of the server. (recommended clamp(floor(host.cpu_count / 4), 1, 8))
Maximum pages (max_pages)int1000min 1, max 100000nononoPages converted at most per document.
Web interface (enable_ui)booltrue-nononoServe the web console /ui (DOCLING_SERVE_ENABLE_UI): a static bundle of the package that calls the public API with the same policies.

Security​

ParameterTypeDefaultAllowed valuesRequiredSecretRestartDescription
API key (api_key)passwordgenerated-noyesyesKey every request of the conversion API must carry in the X-Api-Key header (DOCLING_SERVE_API_KEY), generated at the installation and given to the consumers through the api endpoint (EAI_DOCLING_API_KEY); the /health probe stays open.

Endpoints​

EndpointSchemeComponentPortPathTLS parameterBinding parametersBinding secretsProvisioning command
apihttpdocling-serve5001 (port)-tls_enabled-api_key-

Client configuration files​

Files rendered for the client configuration download:

  • docling.env (client.env.j2)

Commands​

CommandComponentTargetDescription
Recent logs (logs)docling-servechosen hostLast lines of the server journal.

Health checks​

Liveness (per instance)​

ComponentCheckDetails
docling-serveHTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.ip or '127.0.0.1' }}:{{ config.port }}/healthExpected 200; 60 retries; interval 2 s; timeout 5 s

Preflight checks​

CheckTypeMeaningSeverityComponents
memorymemory_mb {"min": 4096}at least 4096 MB of memorywarningevery component
api_port_freeport_free {"param": "port"}port 5001 free on the hostblockingevery component

Uninstall​

Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.

  • Web console: {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/ui
  • API documentation: {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/docs

Upstream documentation​