Docling Servers

This guide describes how to register a Docling server in AI Knowledge Fabric, start and stop it, and use it in your Topics and GraphRAG Topics. You find the screens under Admin → Docling Servers.

1. What Docling does

Docling reads documents like PDF, Word, PowerPoint or Excel files and turns them into text. A topic can only search text. So without Docling, a topic cannot read these files.

Docling works during upload. When you upload a PDF to a topic, the topic sends the file to its Docling server and stores the text it gets back. Docling also reads PDF or Office files that users attach to a chat question, if the topic allows such attachments.

You do not need Docling when:

  • you only upload plain text files, or

  • you only upload pictures. Pictures go to a vision model, not to Docling.

One Docling server can serve many topics. No Docling server exists after installation. You add one yourself.

2. Managed or external

When you add a server, you choose its Server Type:

Managed (deployed by this app) External (existing instance)

Who runs it

This app starts and stops a Docling container for you

You run it somewhere else

Which Docling

The version without a graphics card (docling-serve-cpu)

Whatever you installed

Start and stop in this app

Yes

No. Only a reachability check

Address

Filled in automatically

You enter host and port

Max Conversion Time

Set in this app

Set on the server itself

Good for

A quick start, test setups, one host

A server with a graphics card, a shared central server

A managed server needs Docker on the host of this app (or Kubernetes, see section 8). The first start downloads the Docling image. The image is several GB large, so the first start can take several minutes.

3. The Docling Servers list

Navigate to Admin → Docling Servers. The list shows every registered server:

Column Shows

Name

The name of the server

Endpoint

The host and port this app uses to reach the server

Type

Managed or External

Status

The current status, see Status values

The Search…​ field filters the list by name or host.

The buttons at the end of each row depend on the server type:

Button Tooltip Shown for Does

▶

Start

Managed

Starts the server. Disabled while it runs or while a start is in progress (tooltip Start already running)

■

Stop

Managed

Stops the server. Enabled while it is running or starting

⟳

Test if the server can be reached

External

Checks now whether the server answers, and updates the status

⚙

Settings

Both

Opens the detail page of the server

Add Docling Server opens the form for a new server. Add Docling Server, ▶, ■ and ⚙ are only shown to users who may manage servers, see section 9.

4. Add or edit a Docling server

Click Add Docling Server. To change an existing server, open its detail page (⚙) and click Edit on the Configuration tab. The page title is then Edit Docling Server.

Some fields depend on the server type:

Field Managed External What it does

Server Type

✔

✔

Managed or external, see section 2

Name

✔

✔

The name you see when a topic picks its Docling server

Host

–

✔ (required)

The host name or IP address topics use to reach the server

Port

✔ (Docker only)

✔ (required)

The port of the server

Max Conversion Time (minutes)

✔

–

How long the server works on one document before it stops

For a managed server the form shows this note instead of the Host field: "The address of a managed server is filled in automatically when it starts."

Click Save to store the server. You see Docling server saved. A new server then appears in the list. Cancel goes back to the list without saving.

Name

  • Only letters and are allowed. A space becomes while you type. Numbers and other special characters are refused.

  • At most 50 characters.

  • Every Docling server needs its own name. Upper and lower case count as the same name.

Host (external only)

Enter only the host name or IP address, for example docling.example.com or 10.0.0.12. Do not add http:// and do not add the port. The form does not check this. A wrong value only shows up later as Error in the status.

This app always connects to Docling over plain http://. The address must therefore answer plain HTTP.

With Docker, localhost is allowed: the app and the topic containers then use the Docker host instead. With Kubernetes, never enter localhost, see section 8.

Port

  • External server: the port the Docling server listens on. Usually 5001.

  • Managed server with Docker: the port on this machine where topics reach the server. The default is 5001. Keep it unless another program or another Docling server already uses it. Then the server cannot start. Two managed servers cannot have the same port. The form refuses this with Another managed Docling server already uses this port.

  • Managed server with Kubernetes: no Port field. The app chooses the address itself.

A changed port takes effect the next time the server starts. Topics that use the server need a restart too, because they learn the address when they start.

Max Conversion Time (minutes)

How long the Docling server itself works on one document before it stops. It applies to every topic that uses this server. Values from 1 to 120 are allowed. The default is 10 minutes.

  • Higher: large or scanned PDFs can finish, especially when pictures in them are described.

  • Lower: a stuck document blocks the server for a shorter time.

Each topic also has its own Docling timeout: how long the topic waits for an answer (default 5 minutes, set under Admin → LLM Configuration or per topic). A topic timeout longer than the server’s Max Conversion Time has no effect, because the server stops first. The topic forms warn you in that case.

A change takes effect the next time the server starts.

External server: this field does not exist, because this app cannot change the settings of a server it does not run. Set the time limit on the server itself. In docling-serve this is the setting DOCLING_SERVE_MAX_SYNC_WAIT (in seconds).

Validation messages

Message Meaning

Server type is required

Choose Managed or External

Name is required

The name is empty

Name may only contain letters; numbers and special characters are not allowed

Remove numbers and special characters

Name must not exceed 50 characters

Shorten the name

A Docling server with this name already exists

Choose another name

Host is required

An external server needs a host

Port is required

Enter a port

Another managed Docling server already uses this port

Choose a free port

Max conversion time is required

Enter a time for the managed server

5. Starting and stopping a managed server

You start and stop a managed server in the list, with ▶ and ■. You need a valid license to start a server, see License.

What you see during a start

After you click ▶, a message says:

Starting "name". If the Docling image is not on this host yet it is downloaded first, which can take several minutes.

While the start runs, the Status cell shows Starting…​, a moving progress bar, the current step with the elapsed time (for example Creating the container · 0:12), and the hint "First start downloads the Docling image and can take several minutes." The list updates itself every two seconds. You can leave the page and come back, or open it in another browser tab. The start goes on and the step is still shown.

The steps with Docker are:

  1. Preparing…

  2. Downloading the Docling image (several GB) — only if the image is not on the host yet

  3. Creating the container

  4. Starting the container

  5. Waiting for the Docling server to answer

The steps with Kubernetes are:

  1. Preparing…

  2. Applying Kubernetes resources

  3. Waiting for the pod (pulling the image if the node lacks it)

  4. Waiting for the Docling server to answer

The server is only Running when it really answers. Starting the container is not enough. With Docker the app waits up to about 90 seconds for that answer after the container started. With Kubernetes, see Start time.

At the end you see one of these messages:

Message Meaning

"name" is running.

The server answers and topics can use it

"name" could not be started. It may still be downloading, or it could not start. The application log shows the details. Then try again.

The status is now Error

Failed to start "name": …

The start was refused, for example without a license. The reason follows the colon

A second click on ▶ does not start a second copy. The button is disabled while a start runs.

Stopping

■ stops the server. The status becomes Stopped.

  • Docker: the container is removed. The downloaded model files stay, so the next start is faster.

  • Kubernetes: the server’s workload is removed. Its address and its storage stay.

If the stop fails, the status becomes Error. With Kubernetes you also see Failed to stop "name": … with the reason.

Status values

Status Managed server External server

Created

Saved, never started

Saved, never checked

Starting…​

A start is in progress

–

Running

The server answered at the last check

The server answered at the last check

Stopped

Stopped in this app

–

Error

The start failed, the stop failed, or the server did not answer at the last check

The server did not answer at the last check

Status check when you open the list

Each time you open the list, the app checks every server that shows Running or Starting…​:

  • It answers → Running.

  • It does not answer → Error.

A server that this app is starting right now is not checked. So a long start is not turned into Error by this check. A server that shows Starting…​ after a restart of this app is checked like a running one.

The check does not cover servers in Error. They stay in Error until you act:

  • External server: click ⟳ (Test if the server can be reached).

  • Managed server: click ▶ again. With Docker, a container that already runs is kept, and the start only waits for its answer before it shows Running.

6. The detail page

Click ⚙ in the list to open the detail page. Back returns to the list. The page has two tabs.

Configuration

Shows the stored settings read-only: Name, Server Type, Host, Port and Base URL. The Base URL is the full address topics use to reach Docling. It is built from host and port. Edit opens the form from section 4.

For a managed server, Host and Port show the stored values. With Docker the host is localhost. With Kubernetes the address inside the cluster appears after the first start.

Actions

Docker Compose or Kubernetes YAML (managed servers only). Download docker-compose.yml or Download Kubernetes YAML gives you the file this app uses to run the server, with the current settings. Use it to check the settings, or to run the server by hand.

Danger Zone removes the server:

Server type Button What happens

Managed, Docker

Stop & Delete Docling Server

Stops the server, deletes its storage (its downloaded model files — a new server downloads them again) and removes it from this app

Managed, Kubernetes

Stop & Delete Docling Server

Stops the server, deletes everything it uses in the cluster and removes it from this app

External

Remove from Catalog

Removes the server from this app. The server itself keeps running where it is

A dialog asks you to confirm with Delete or Remove. This cannot be undone.

A server that topics still use cannot be deleted. Instead of the button, the Danger Zone then says:

Still used by n topic(s): names. Choose another Docling server in these topics first, then you can delete this one.

GraphRAG Topics appear in that list with (GraphRAG) after their name. Choose another Docling server in these topics, or remove Docling from them, then delete the server.

7. Using a Docling server in a topic

Topics and GraphRAG Topics pick their Docling server in their own forms. In the wizards, the Docling section appears only when the topic can receive PDF or Office files: when Binary documents is one of the file types, or when binary documents are allowed as chat attachments. Then a Docling server is required.

Where Fields

Topic wizard, step 2 (Model Strategy), section Files

Docling Server, Timeout (min), Docling Settings (advanced)

Topic detail, Configuration tab

Docling Server, Docling Settings (advanced)

GraphRAG wizard, step 2 (Data Ingestion) — also in edit mode

Docling Server, Timeout (min), Docling Settings (advanced)

In the wizards, the picker shows each server as name · host:port. It lists every registered server, whatever its status. Make sure the server is Running before you upload documents.

  • Docling Server: the server the topic sends its documents to. A topic learns the address when it starts. After you change the server of a running topic, restart the topic.

  • Timeout (min): how long the topic waits for one whole document. Empty uses the default from Admin → LLM Configuration. See Max Conversion Time for how it works together with the server’s limit.

  • Docling Settings (advanced): optional settings for how Docling reads the files of this topic, for example text recognition in scans (OCR), its languages, or tables. They are sent with every upload, so a change applies to the next upload. No restart is needed. Files already uploaded stay as they are until you upload them again. The template switches nothing on, so Docling keeps the settings of its server.

More about the topic forms:

Pictures inside documents. A topic can let a vision model describe the pictures inside a PDF. Docling then calls that model. A managed server is already set up to allow this. On an external docling-serve, allow it yourself with the setting DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true.

8. Kubernetes

When this app runs in Kubernetes, a managed Docling server works a little differently. See also the Kubernetes installation guide.

  • A start creates a Deployment and a Service named docling-server-<id>, and a volume docling-server-cache-<id> for the downloaded model files. See What the app creates in the cluster.

  • The form has no Host and no Port field for a managed server. On start, the app sets the address inside the cluster by itself. Start a new managed server once before topics use it, because the address exists only after the first start.

  • Stop removes the Deployment. The Service and the volume stay.

  • Stop & Delete Docling Server also removes the Service and the volume.

  • CPU and memory of a managed server are set by the administrator of this app, see CPU and memory. Large PDFs need more memory.

  • An external server must have an address that pods can reach. Never use localhost, see Reaching AI servers and Docling.

9. Permissions

Permission Allows

SERVER_VIEW (View Servers)

See Admin → Docling Servers and the list. Check external servers with ⟳

SERVER_MANAGE (Manage Servers)

Add, edit, start, stop and delete Docling servers. Shows Add Docling Server, ▶, ■, ⚙ and the delete button

The form for adding and editing needs SERVER_MANAGE. Starting a server also needs a valid license. See Roles and Permissions.

10. Troubleshooting

Symptom Cause and fix

The first start stays in Downloading the Docling image (several GB) for minutes

Normal on a new host. The image is several GB. Wait, the step changes when the download is done

Start ends with "name" could not be started

Read the application log. If the server was only slow to answer, click ▶ again. A port that another program uses also stops the start: choose another Port

Failed to start "name": There is no valid license.

Enter a license key under Admin → License

Another managed Docling server already uses this port

Each managed server needs its own port. Choose a free one, for example 5002

External server shows Error

The app cannot reach it. Check host and port, and that the server answers plain HTTP. Do not write http:// or the port into the Host field. Then click ⟳

External server stays Created

It was never checked. Click ⟳

A server shows Error, but you fixed the problem

Errors are not re-checked automatically. Click ⟳ (external) or ▶ (managed)

Upload of a long or scanned PDF fails

The topic timeout or the server’s Max Conversion Time is too short. Raise the server limit first, then the topic timeout. A Docling without a graphics card is slow on scans

The topic form warns that the server "itself stops after n min"

The topic timeout is longer than the server’s Max Conversion Time. Raise the limit on the server

Uploads fail after you changed the port of a managed server

Topics learn the address when they start. Restart the topics that use this server

Kubernetes: topic uploads fail although the managed Docling server was never started

The address is set on the first start. Start the Docling server, then restart the topic

No Stop & Delete Docling Server button, only "Still used by …"

Topics still use the server. Choose another Docling server in them first

No buttons in the list, no Add Docling Server

Your role has only SERVER_VIEW. Ask an administrator for SERVER_MANAGE

Related