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 and view logs​

In the TUI, click Status to access diagnostics and controls for all OpenRAG services, including container health, ports, and image versions.

To view streaming logs, click the name of a service, and then press l.

For the Docling native service, see Stop, start, and inspect native services.

Stop and start containers​

On the TUI's Status page, you can stop, start, and restart OpenRAG's container-based services.

When you click Restart or Start 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.

On the TUI's Status page, you can stop, start, restart, and inspect OpenRAG's native services.

The Native Services section lists the status, port, and process ID (PID) for each native service.

To manage a native service, click the service's name, and then click Stop, Start or Restart.

To view the logs for a native service, click the service's name, and then press l.

Upgrade services​

See Upgrade OpenRAG.

Reset containers (destructive)​

warning

This is a destructive operation that does the following:

  • Destroys all OpenRAG containers, volumes, and local images.
  • Prunes any additional container objects.
  • Deletes the contents of the ~/.openrag directory except for OpenRAG's .env file and the /documents subdirectory.

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

Use these steps to reset your OpenRAG deployment by recreating the containers and deleting all data in the ~/.openrag directory except for the .env file and the /documents subdirectory.

This restores your OpenRAG deployment to a near-initial state while preserving your configuration (in .env) and uploaded documents (in /documents). Your documents are reingested into a fresh OpenSearch index after the reset.

To reset your OpenRAG deployment and delete all OpenRAG data, see Reinstall OpenRAG.

  1. If you modified the built-in flows or created custom flows in your OpenRAG Langflow instance, export your flows before starting this process. Although OpenRAG can preserve changes to the built-in flows, it doesn't preserve user-created flows. As a general best practice, exporting your flows is recommended to create backups of your customizations. Afterwards, you can reimport your flows or reference the exported flow JSON as needed.

  1. To destroy and recreate your OpenRAG containers, click Status in the TUI, 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.

  3. If you exported customized flows, import your flows into Langflow after completing the onboarding process.

Prune images​

Use image pruning to free up disk space by removing unused OpenRAG container images.

For TUI-managed services, use the TUI's Prune Images option to clean up your OpenRAG container images. You can choose to prune unused images only or all images. If you prune all images, the OpenRAG services are stopped, all images are pruned, and then the required images are pulled the next time you start the OpenRAG services.

For self-managed services, use docker image prune or podman image prune to remove unused images.

See also​