Skip to main content

Manage OpenRAG containers and services

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 with the automated installer script, uv, or uvx, you can use the Terminal User Interface (TUI) to manage your OpenRAG configuration and services.

For self-managed deployments, run Docker or Podman commands to manage your OpenRAG services.

Monitor services​

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

  • TUI Diagnostics menu: The TUI's Diagnostics menu (4) provides health monitoring for your container runtimes and monitoring of your OpenSearch instance.

  • Docling: See Stop, start, and inspect native services.

Stop and start containers​

In the TUI's Status menu (3), 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.

Stop, start, and inspect native services (Docling)​

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.

From the TUI's Status menu (3), click Native Services to do the following:

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

Upgrade services​

See Upgrade OpenRAG.

Reset containers (destructive)​

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.

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 before resetting your OpenRAG containers.

Factory Reset with the TUI​

warning

This is a destructive action that does the following:

  • Destroys all OpenRAG containers, volumes, and local images with docker compose down --volumes --remove-orphans --rmi local.
  • Prunes any additional container objects with docker system prune -f.
  • Deletes the contents of OpenRAG's config and ./opensearch-data directories.
  • Deletes the conversations.json file.

Destroyed containers and deleted data are lost and cannot be recovered after running this operation.

This operation doesn't remove the .env file or the contents of the ./openrag-documents directory.

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

  2. Repeat the setup process 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.

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

Docker
docker compose up --build --force-recreate --remove-orphans
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:

    Docker
    docker compose down --volumes --remove-orphans --rmi local
    docker system prune -f
    Podman
    podman compose down --volumes --remove-orphans --rmi local
    podman system prune -f

  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.

  4. Recreate the containers:

    Docker
    docker compose up -d
    Podman
    podman compose up -d

  5. Launch the OpenRAG app, and then repeat the application onboarding process.

See also​