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 uv or uvx, then you can use an OpenRAG terminal session 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 terminal session, select the Show status option to access information about all OpenRAG services, including container health, ports, and image versions.

For more information and options, you must start the terminal session with --tui, such as uv run openrag --tui. Then, click Status to access controls to stop, start, or restart individual services. 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​

In the terminal session, use the Start services and Stop services options to start or stop all OpenRAG services.

For fine-grained controls, you must start the terminal session with --tui, such as uv run openrag --tui. Then, click Status to access controls to stop, start, or restart individual services.

tip

A Docker or Podman VM must be running before you start OpenRAG unless you are running OpenRAG on a Linux-based VM, such as a Linux-based WSL image.

The container VM must have sufficient resources to run the OpenRAG containers. The minimum recommendation is 8 GB of RAM and at least 50 GB of free disk space.

For more information, see Troubleshoot OpenRAG.

How does the terminal session start the containers?

When you restart or start services in the terminal session, 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.

Alternatively, you can manually run the Docker/Podman commands to stop and start containers. Typically, this is only necessary if you don't want to use --tui or there is an error preventing the terminal session from managing the containers.

  • Stop all containers: docker compose down or podman compose down
  • Start all containers: docker compose up -d or podman compose up -d
  • Stop one container: docker stop CONTAINER_ID or podman stop CONTAINER_ID
  • Start one container: docker start CONTAINER_ID or podman start CONTAINER_ID

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.

In the terminal session, select the Show status option to view the status, port, and process ID (PID) for OpenRAG's native services. Native services are started and stopped when you use the Start services and Stop services options.

For more information and options, you must start the terminal session with --tui, such as uv run openrag --tui. Then, click Status to access controls to stop, start, or restart individual services. To view streaming logs, click the name of a service, 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. Exporting your flows is recommended because it creates backups of your flow customizations. Afterwards, you can reimport your flows or reference the exported flow JSON as needed.

  1. To destroy and recreate your OpenRAG containers, start the terminal session with --tui, such as uv run openrag --tui.

  2. Click Status in the TUI, and then click Factory Reset.

  3. Repeat the setup process to restart the services and launch the OpenRAG app. Your previous configuration, including credentials, are restored from the .env file.

  4. 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 terminal-managed services, you must start the terminal session with --tui, such as uv run openrag --tui. Then, use the 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​