---
title: Manage OpenRAG containers and services
slug: /manage-services
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialDockerComposeUp from '@site/docs/_partial-docker-compose-up.mdx';
import PartialDockerComposeDownAndPrune from '@site/docs/_partial-docker-compose-down-and-prune.mdx';
import PartialFactorResetWarning from '@site/docs/_partial-factory-reset-warning.mdx';

Service management is an essential part of maintaining your OpenRAG deployment.

Most OpenRAG services run in containers.
However, some services, like Docling, run directly on the local machine.

If you [installed OpenRAG](/install-options) with the automated installer script, `uv`, or `uvx`, you can use the [Terminal User Interface (TUI)](/tui) to manage your OpenRAG configuration and services.

For [self-managed deployments](/docker), run Docker or Podman commands to manage your OpenRAG services.

## Monitor services

<Tabs>
<TabItem value="TUI" label="TUI-managed services" default>

* **TUI Status menu**: In the **Status** menu (<kbd>3</kbd>), you can access streaming logs for all OpenRAG services.
Select the service you want to view, and then press <kbd>l</kbd>.
To copy the logs, click **Copy to Clipboard**.

* **TUI Diagnostics menu**: The TUI's **Diagnostics** menu (<kbd>4</kbd>) provides health monitoring for your container runtimes and monitoring of your OpenSearch instance.

* **Docling**: See [Stop, start, and inspect native services](#start-native-services).

</TabItem>
<TabItem value="env" label="Self-managed services">

* **Containers**: Get container logs with [`docker compose logs`](https://docs.docker.com/reference/cli/docker/compose/logs/) or [`podman logs`](https://docs.podman.io/en/latest/markdown/podman-logs.1.html).

* **Docling**: See [Stop, start, and inspect native services](#start-native-services).

</TabItem>
</Tabs>

## Stop and start containers

<Tabs>
<TabItem value="TUI" label="TUI-managed services" default>

In the TUI's **Status** menu (<kbd>3</kbd>), click **Stop Services** to stop all OpenRAG container-based services.
Then, click **Start All Services** to restart the OpenRAG containers.

When you click **Start All Services**, the following processes are triggered:

1. OpenRAG automatically detects your container runtime, and then checks if your machine has compatible GPU support by checking for `CUDA`, `NVIDIA_SMI`, and Docker/Podman runtime support. This check determines which Docker Compose file OpenRAG uses because there are separate Docker Compose files for GPU and CPU deployments.

2. OpenRAG pulls the OpenRAG container images with `docker compose pull` if any images are missing.

3. OpenRAG deploys the containers with `docker compose up -d`.

</TabItem>
<TabItem value="env" label="Self-managed services">

Use [`docker compose down`](https://docs.docker.com/reference/cli/docker/compose/down/) and [`docker compose up -d`](https://docs.docker.com/reference/cli/docker/compose/up/).

To stop or start individual containers, use targeted commands like `docker stop CONTAINER_ID` and `docker start CONTAINER_ID`.

</TabItem>
</Tabs>

## Stop, start, and inspect native services (Docling) {#start-native-services}

A _native service_ in OpenRAG is a service that runs locally on your machine, not within a container. For example, the `docling serve` process is an OpenRAG native service because this document processing service runs on your local machine, separate from the OpenRAG containers.

<Tabs>
<TabItem value="TUI" label="TUI-managed services" default>

From the TUI's **Status** menu (<kbd>3</kbd>), click **Native Services** to do the following:

* View the service's status, port, and process ID (PID).
* Stop, start, and restart native services.

</TabItem>
<TabItem value="env" label="Self-managed services">

Because the Docling service doesn't run in a container, you must start and stop it manually on the host machine:

* Stop `docling serve`:

   ```bash
   uv run python scripts/docling_ctl.py stop
   ```

* Start `docling serve`:

   ```bash
   uv run python scripts/docling_ctl.py start --port 5001
   ```

* Check that `docling serve` is running:

   ```bash
   uv run python scripts/docling_ctl.py status
   ```

   If `docling serve` is running, the output includes the status, address, and process ID (PID):

   ```text
   Status: running
   Endpoint: http://127.0.0.1:5001
   Docs: http://127.0.0.1:5001/docs
   PID: 27746
   ```

</TabItem>
</Tabs>

## Upgrade services

See [Upgrade OpenRAG](/upgrade).

## Reset containers (destructive) {#reset-containers}

Reset your OpenRAG deployment by recreating the containers and removing some related data.

To completely reset your OpenRAG deployment and delete all OpenRAG data, see [Reinstall OpenRAG](/reinstall).

### Export customized flows before resetting containers {#export-customized-flows-before-resetting-containers}

If you modified the built-in flows or created custom flows in your OpenRAG Langflow instance, and you want to preserve those changes, [export your flows](https://docs.langflow.org/concepts-flows-import) before resetting your OpenRAG containers.

### Factory Reset with the TUI

<PartialFactorResetWarning />

1. To destroy and recreate your OpenRAG containers, open the TUI's **Status** menu (<kbd>3</kbd>), and then click **Factory Reset**.

2. Repeat the [setup process](/install#setup) to restart the services and launch the OpenRAG app. Your OpenRAG passwords, OAuth credentials (if previously set), and onboarding configuration are restored from the `.env` file.

### Rebuild self-managed containers

This command destroys and recreates the containers. Data stored exclusively on the containers is lost, such as Langflow flows.

If you want to preserve customized flows, see [Export customized flows before resetting containers](#export-customized-flows-before-resetting-containers).

The `.env` file, `config` directory, `./openrag-documents` directory, `./opensearch-data` directory, and the `conversations.json` file are preserved.

```bash title="Docker"
docker compose up --build --force-recreate --remove-orphans
```

```bash title="Podman"
podman compose up --build --force-recreate --remove-orphans
```

### Destroy and recreate self-managed containers

Use separate commands to destroy and recreate the containers if you want to modify the configuration or delete other OpenRAG data before recreating the containers.

:::warning
These are destructive operations that reset your OpenRAG deployment to an initial state.
Destroyed containers and deleted data are lost and cannot be recovered after running this operation.
:::

1. Destroy the containers, volumes, and local images, and then remove (prune) any additional container objects:

   <PartialDockerComposeDownAndPrune />

2. Optional: Remove data that wasn't deleted by the previous commands:

   * OpenRAG's `.env` file
   * The contents of OpenRAG's `config` directory
   * The contents of the `./openrag-documents` directory
   * The contents of the `./opensearch-data` directory
   * The `conversations.json` file

3. If you deleted the `.env` file, prepare a new `.env` before redeploying the containers.
For more information, see [Deploy OpenRAG with self-managed services](/docker).

4. Recreate the containers:

   <PartialDockerComposeUp />

5. Launch the OpenRAG app, and then repeat the [application onboarding process](/docker#application-onboarding).

## See also

* [Uninstall OpenRAG](/uninstall)