From 1b642b9efeb9299ab98809381707447be9bb03cb Mon Sep 17 00:00:00 2001 From: aimurphy Date: Tue, 2 Dec 2025 16:00:15 +0000 Subject: [PATCH] deploy: ef2014f82e2a418f7185e022618e675685764372 --- 404.html | 2 +- agents/index.html | 2 +- ...20ffe.bef0ec8d.js => af920ffe.140c3203.js} | 2 +- ...78f0a.d456318f.js => c8078f0a.f1c0e5b8.js} | 2 +- assets/js/d0314b07.788dda5b.js | 1 - assets/js/d0314b07.7b0b4caa.js | 1 + assets/js/eb5b356a.5256f349.js | 1 + assets/js/eb5b356a.5a0abd05.js | 1 - ...n.ce59c02b.js => runtime~main.e45e845e.js} | 2 +- chat/index.html | 2 +- docker/index.html | 2 +- index.html | 2 +- ingestion/index.html | 2 +- install/index.html | 138 ++++++++++-------- knowledge-filters/index.html | 2 +- knowledge/index.html | 2 +- quickstart/index.html | 4 +- reference/configuration/index.html | 4 +- support/troubleshoot/index.html | 13 +- 19 files changed, 102 insertions(+), 83 deletions(-) rename assets/js/{af920ffe.bef0ec8d.js => af920ffe.140c3203.js} (57%) rename assets/js/{c8078f0a.d456318f.js => c8078f0a.f1c0e5b8.js} (84%) delete mode 100644 assets/js/d0314b07.788dda5b.js create mode 100644 assets/js/d0314b07.7b0b4caa.js create mode 100644 assets/js/eb5b356a.5256f349.js delete mode 100644 assets/js/eb5b356a.5a0abd05.js rename assets/js/{runtime~main.ce59c02b.js => runtime~main.e45e845e.js} (93%) diff --git a/404.html b/404.html index 82be08b0..55c365dd 100644 --- a/404.html +++ b/404.html @@ -4,7 +4,7 @@ OpenRAG - + diff --git a/agents/index.html b/agents/index.html index 9949e269..3047cceb 100644 --- a/agents/index.html +++ b/agents/index.html @@ -4,7 +4,7 @@ Use Langflow in OpenRAG | OpenRAG - + diff --git a/assets/js/af920ffe.bef0ec8d.js b/assets/js/af920ffe.140c3203.js similarity index 57% rename from assets/js/af920ffe.bef0ec8d.js rename to assets/js/af920ffe.140c3203.js index d8d15712..a32f7756 100644 --- a/assets/js/af920ffe.bef0ec8d.js +++ b/assets/js/af920ffe.140c3203.js @@ -1 +1 @@ -"use strict";(self.webpackChunkopenrag_docs=self.webpackChunkopenrag_docs||[]).push([[98],{1260:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>h,contentTitle:()=>d,default:()=>x,frontMatter:()=>c,metadata:()=>t,toc:()=>u});const t=JSON.parse('{"id":"get-started/quickstart","title":"Quickstart","description":"Use this quickstart to install OpenRAG, and then try some of OpenRAG\'s core features.","source":"@site/docs/get-started/quickstart.mdx","sourceDirName":"get-started","slug":"/quickstart","permalink":"/quickstart","draft":false,"unlisted":false,"editUrl":"https://github.com/openrag/openrag/tree/main/docs/docs/get-started/quickstart.mdx","tags":[],"version":"current","frontMatter":{"title":"Quickstart","slug":"/quickstart"},"sidebar":"tutorialSidebar","previous":{"title":"About OpenRAG","permalink":"/"},"next":{"title":"Install OpenRAG with TUI","permalink":"/install"}}');var i=s(4848),r=s(8453),o=s(1610),a=(s(1470),s(9365),s(3862)),l=s(7224);const c={title:"Quickstart",slug:"/quickstart"},d=void 0,h={},u=[{value:"Prerequisites",id:"prerequisites",level:2},...a.RM,{value:"Install OpenRAG",id:"install-openrag",level:2},{value:"Load and chat with documents",id:"chat-with-documents",level:2},{value:"Change the language model and chat settings",id:"change-components",level:2},{value:"Integrate OpenRAG into an application",id:"integrate-openrag-into-an-application",level:2},...l.RM,{value:"Next steps",id:"next-steps",level:2}];function p(e){const n={a:"a",code:"code",h2:"h2",img:"img",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components},{Details:t}=n;return t||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.p,{children:"Use this quickstart to install OpenRAG, and then try some of OpenRAG's core features."}),"\n",(0,i.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,i.jsx)(n.p,{children:"This quickstart requires the following:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["An ",(0,i.jsx)(n.a,{href:"https://platform.openai.com/api-keys",children:"OpenAI API key"}),".\nThis quickstart uses OpenAI for simplicity.\nFor other providers, see the complete ",(0,i.jsx)(n.a,{href:"/install",children:"installation guide"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.a,{href:"https://www.python.org/downloads/release/python-3100/",children:"Python"})," version 3.13 or later."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Microsoft Windows only: To run OpenRAG on Windows, you must use the Windows Subsystem for Linux (WSL)."}),"\n",(0,i.jsxs)(t,{children:[(0,i.jsx)("summary",{children:"Install WSL for OpenRAG"}),(0,i.jsx)(a.Ay,{})]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"install-openrag",children:"Install OpenRAG"}),"\n",(0,i.jsx)(n.p,{children:"For this quickstart, install OpenRAG with the automatic installer script and basic setup:"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Create a directory to store the OpenRAG configuration files, and then change to that directory:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"mkdir openrag-workspace\ncd openrag-workspace\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.a,{href:"https://docs.openr.ag/files/run_openrag_with_prereqs.sh",children:"Download the OpenRAG install script"}),", move it to your OpenRAG directory, and then run it:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"bash run_openrag_with_prereqs.sh\n"})}),"\n",(0,i.jsxs)(n.p,{children:["This script installs OpenRAG and its dependencies, including Docker or Podman, and it creates a ",(0,i.jsx)(n.code,{children:".env"})," file and ",(0,i.jsx)(n.code,{children:"docker-compose"})," files in the current working directory.\nYou might be prompted to install certain dependencies if they aren't already present in your environment.\nThis process can take a few minutes.\nOnce the environment is ready, OpenRAG starts."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Basic Setup"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Create passwords for your OpenRAG installation's OpenSearch and Langflow services. You can click ",(0,i.jsx)(n.strong,{children:"Generate Passwords"})," to automatically generate passwords."]}),"\n",(0,i.jsxs)(n.p,{children:["The OpenSearch password is required. The Langflow admin password is optional.\nIf you don't generate a Langflow admin password, Langflow runs in ",(0,i.jsx)(n.a,{href:"https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login",children:"autologin mode"})," with no password required."]}),"\n",(0,i.jsxs)(n.p,{children:["Your passwords are saved in the ",(0,i.jsx)(n.code,{children:".env"})," file that is used to start OpenRAG.\nYou can find this file in your OpenRAG installation directory."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Save Configuration"}),", and then click ",(0,i.jsx)(n.strong,{children:"Start All Services"}),"."]}),"\n",(0,i.jsx)(n.p,{children:"Wait a few minutes while the startup process pulls and runs the necessary container images.\nProceed when you see the following messages in the terminal user interface (TUI):"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"Services started successfully\nCommand completed successfully\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To open the OpenRAG application, go to the TUI main menu, and then click ",(0,i.jsx)(n.strong,{children:"Open App"}),".\nAlternatively, in your browser, navigate to ",(0,i.jsx)(n.code,{children:"localhost:3000"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Select the ",(0,i.jsx)(n.strong,{children:"OpenAI"})," model provider, enter your OpenAI API key, and then click ",(0,i.jsx)(n.strong,{children:"Complete"}),"."]}),"\n",(0,i.jsx)(n.p,{children:"For this quickstart, you can use the default options for the model settings."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click through the overview slides for a brief introduction to OpenRAG and basic setup, or click ",(0,i.jsx)(o.A,{name:"ArrowRight","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Skip overview"}),".\nYou can complete this quickstart without going through the overview."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"chat-with-documents",children:"Load and chat with documents"}),"\n",(0,i.jsxs)(n.p,{children:["Use the ",(0,i.jsxs)(n.a,{href:"/chat",children:["OpenRAG ",(0,i.jsx)(n.strong,{children:"Chat"})]})," to explore the documents in your OpenRAG database using natural language queries.\nSome documents are included by default to get you started, and you can load your own documents."]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["In OpenRAG, click ",(0,i.jsx)(o.A,{name:"MessageSquare","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Chat"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["For this quickstart, ask the agent what documents are available.\nFor example: ",(0,i.jsx)(n.code,{children:"What documents are available to you?"})]}),"\n",(0,i.jsx)(n.p,{children:"The agent responds with a summary of OpenRAG's default documents."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To verify the agent's response, click ",(0,i.jsx)(o.A,{name:"Library","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Knowledge"})," to view the documents stored in the OpenRAG OpenSearch vector database.\nYou can click a document to view the chunks of the document as they are stored in the database."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Add Knowledge"})," to add your own documents to your OpenRAG knowledge base."]}),"\n",(0,i.jsxs)(n.p,{children:["For this quickstart, use either the ",(0,i.jsx)(o.A,{name:"File","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"File"})," or ",(0,i.jsx)(o.A,{name:"Folder","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Folder"})," upload options to load documents from your local machine.\n",(0,i.jsx)(n.strong,{children:"Folder"})," uploads an entire directory.\nThe default directory is the ",(0,i.jsx)(n.code,{children:"/openrag-documents"})," subdirectory in your OpenRAG installation directory."]}),"\n",(0,i.jsxs)(n.p,{children:["For information about the cloud storage provider options, see ",(0,i.jsx)(n.a,{href:"/ingestion#oauth-ingestion",children:"Ingest files with OAuth connectors"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Return to the ",(0,i.jsx)(n.strong,{children:"Chat"})," window, and then ask a question related to the documents that you just uploaded."]}),"\n",(0,i.jsx)(n.p,{children:"If the agent's response doesn't seem to reference your documents correctly, try the following:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(o.A,{name:"Gear","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Function Call: search_documents (tool_call)"})," to view the log of tool calls made by the agent. This is helpful for troubleshooting because it shows you how the agent used particular tools."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(o.A,{name:"Library","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Knowledge"})," to confirm that the documents are present in the OpenRAG OpenSearch vector database, and then click each document to see how the document was chunked.\nIf a document was chunked improperly, you might need to tweak the ingestion or modify and reupload the document."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(o.A,{name:"Settings2","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Settings"})," to modify the knowledge ingestion settings."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["For more information, see ",(0,i.jsx)(n.a,{href:"/knowledge",children:"Configure knowledge"})," and ",(0,i.jsx)(n.a,{href:"/ingestion",children:"Ingest knowledge"}),"."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"change-components",children:"Change the language model and chat settings"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To change the knowledge ingestion settings, agent behavior, or language model, click ",(0,i.jsx)(o.A,{name:"Settings2","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Settings"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.strong,{children:"Settings"})," page provides quick access to commonly used parameters like the ",(0,i.jsx)(n.strong,{children:"Language model"})," and ",(0,i.jsx)(n.strong,{children:"Agent Instructions"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["For greater insight into the underlying ",(0,i.jsx)(n.a,{href:"/agents",children:"Langflow flow"})," that drives the OpenRAG chat, click ",(0,i.jsx)(n.strong,{children:"Edit in Langflow"})," and then click ",(0,i.jsx)(n.strong,{children:"Proceed"})," to launch the Langflow visual editor in a new browser window."]}),"\n",(0,i.jsxs)(n.p,{children:["If Langflow requests login information, enter the ",(0,i.jsx)(n.code,{children:"LANGFLOW_SUPERUSER"})," and ",(0,i.jsx)(n.code,{children:"LANGFLOW_SUPERUSER_PASSWORD"})," from the ",(0,i.jsx)(n.code,{children:".env"})," file in your OpenRAG installation directory."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.strong,{children:"OpenRAG OpenSearch Agent"})," flow opens in a new browser window."]}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.img,{alt:"OpenRAG OpenSearch Agent flow",src:s(3982).A+"",width:"4084",height:"2176"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["For this quickstart, try changing the model.\nClick the ",(0,i.jsx)(n.strong,{children:"Language Model"})," component, and then change the ",(0,i.jsx)(n.strong,{children:"Model Name"})," to a different OpenAI model."]}),"\n",(0,i.jsxs)(n.p,{children:["After you edit a built-in flow, you can click ",(0,i.jsx)(n.strong,{children:"Restore flow"})," on the ",(0,i.jsx)(n.strong,{children:"Settings"})," page to revert the flow to its original state when you first installed OpenRAG."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Press ",(0,i.jsx)("kbd",{children:"Command"}),"+",(0,i.jsx)("kbd",{children:"S"})," (",(0,i.jsx)("kbd",{children:"Ctrl"}),"+",(0,i.jsx)("kbd",{children:"S"}),") to save your changes."]}),"\n",(0,i.jsx)(n.p,{children:"You can close the Langflow browser window, or leave it open if you want to continue experimenting with the flow editor."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Switch to your OpenRAG browser window, and then click ",(0,i.jsx)(o.A,{name:"Plus","aria-hidden":"true"})," in the ",(0,i.jsx)(n.strong,{children:"Conversations"})," tab to start a new conversation.\nThis ensures that the chat doesn't persist any context from the previous conversation with the original model."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Ask the same question you asked in ",(0,i.jsx)(n.a,{href:"#chat-with-documents",children:"Load and chat with documents"})," to see how the response differs from the original model."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"integrate-openrag-into-an-application",children:"Integrate OpenRAG into an application"}),"\n",(0,i.jsxs)(n.p,{children:["Langflow in OpenRAG includes pre-built flows that you can integrate into your applications using the ",(0,i.jsx)(n.a,{href:"https://docs.langflow.org/api-reference-api-examples",children:"Langflow API"}),".\nYou can use these flows as-is or modify them to better suit your needs, as demonstrated in ",(0,i.jsx)(n.a,{href:"#change-components",children:"Change the language model and chat settings"}),"."]}),"\n",(0,i.jsx)(n.p,{children:"You can send and receive requests with the Langflow API using Python, TypeScript, or curl."}),"\n",(0,i.jsx)(l.Ay,{}),"\n",(0,i.jsx)(n.h2,{id:"next-steps",children:"Next steps"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Reinstall OpenRAG with your preferred settings"}),": This quickstart used a minimal setup to demonstrate OpenRAG's core functionality.\nIt is recommended that you reinstall OpenRAG with your preferred configuration because some settings are immutable after initial setup.\nFor all installation options, see ",(0,i.jsx)(n.a,{href:"/install",children:"Install OpenRAG with TUI"})," and ",(0,i.jsx)(n.a,{href:"/docker",children:"Install OpenRAG with containers"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Learn more about OpenRAG"}),": Explore OpenRAG and the OpenRAG documentation to learn more about its features and functionality."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Learn more about Langflow"}),": For a deep dive on the Langflow API and visual editor, see the ",(0,i.jsx)(n.a,{href:"https://docs.langflow.org/",children:"Langflow documentation"}),"."]}),"\n"]}),"\n"]})]})}function x(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(p,{...e})}):p(e)}},3862:(e,n,s)=>{s.d(n,{Ay:()=>a,RM:()=>r});var t=s(4848),i=s(8453);const r=[];function o(e){const n={a:"a",admonition:"admonition",code:"code",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",...(0,i.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install",children:"Install WSL"})," with the Ubuntu distribution using WSL 2:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-powershell",children:"wsl --install -d Ubuntu\n"})}),"\n",(0,t.jsxs)(n.p,{children:["For new installations, the ",(0,t.jsx)(n.code,{children:"wsl --install"})," command uses WSL 2 and Ubuntu by default."]}),"\n",(0,t.jsxs)(n.p,{children:["For existing WSL installations, you can ",(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install#change-the-default-linux-distribution-installed",children:"change the distribution"})," and ",(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install#upgrade-version-from-wsl-1-to-wsl-2",children:"check the WSL version"}),"."]}),"\n",(0,t.jsx)(n.admonition,{title:"Known limitation",type:"warning",children:(0,t.jsx)(n.p,{children:"OpenRAG isn't compatible with nested virtualization, which can cause networking issues.\nDon't install OpenRAG on a WSL distribution that is installed inside a Windows VM.\nInstead, install OpenRAG on your base OS or a non-nested Linux VM."})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install#ways-to-run-multiple-linux-distributions-with-wsl",children:"Start your WSL Ubuntu distribution"})," if it doesn't start automatically."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-your-linux-username-and-password",children:"Set up a username and password for your WSL distribution"}),"."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers",children:"Install Docker Desktop for Windows with WSL 2"}),". When you reach the Docker Desktop ",(0,t.jsx)(n.strong,{children:"WSL integration"})," settings, make sure your Ubuntu distribution is enabled, and then click ",(0,t.jsx)(n.strong,{children:"Apply & Restart"})," to enable Docker support in WSL."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:"Install and run OpenRAG from within your WSL Ubuntu distribution."}),"\n"]}),"\n"]}),"\n",(0,t.jsx)("br",{}),"\n",(0,t.jsxs)(n.p,{children:["If you encounter issues with port forwarding or the Windows Firewall, you might need to adjust the ",(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall",children:"Hyper-V firewall settings"})," to allow communication between your WSL distribution and the Windows host. For more troubleshooting advice for networking issues, see ",(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#common-issues",children:"Troubleshooting WSL common issues"}),"."]})]})}function a(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(o,{...e})}):o(e)}},3982:(e,n,s)=>{s.d(n,{A:()=>t});const t=s.p+"assets/images/opensearch-agent-flow-f3b279e02425cd043002eb7749067108.png"},7224:(e,n,s)=>{s.d(n,{Ay:()=>d,RM:()=>l});var t=s(4848),i=s(8453),r=s(1610),o=s(1470),a=s(9365);const l=[];function c(e){const n={a:"a",code:"code",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:["Open the ",(0,t.jsx)(n.strong,{children:"OpenRAG OpenSearch Agent"})," flow in the Langflow visual editor: From the ",(0,t.jsx)(n.strong,{children:"Chat"})," window, click ",(0,t.jsx)(r.A,{name:"Settings2","aria-hidden":"true"})," ",(0,t.jsx)(n.strong,{children:"Settings"}),", click ",(0,t.jsx)(n.strong,{children:"Edit in Langflow"}),", and then click ",(0,t.jsx)(n.strong,{children:"Proceed"}),"."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:["Create a ",(0,t.jsx)(n.a,{href:"https://docs.langflow.org/api-keys-and-authentication",children:"Langflow API key"}),", which is a user-specific token required to send requests to the Langflow server.\nThis key doesn't grant access to OpenRAG."]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["In the Langflow visual editor, click your user icon in the header, and then select ",(0,t.jsx)(n.strong,{children:"Settings"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:["Click ",(0,t.jsx)(n.strong,{children:"Langflow API Keys"}),", and then click ",(0,t.jsx)(r.A,{name:"Plus","aria-hidden":"true"})," ",(0,t.jsx)(n.strong,{children:"Add New"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:["Name your key, and then click ",(0,t.jsx)(n.strong,{children:"Create API Key"}),"."]}),"\n",(0,t.jsx)(n.li,{children:"Copy the API key and store it securely."}),"\n",(0,t.jsxs)(n.li,{children:["Exit the Langflow ",(0,t.jsx)(n.strong,{children:"Settings"})," page to return to the visual editor."]}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:["Click ",(0,t.jsx)(n.strong,{children:"Share"}),", and then select ",(0,t.jsx)(n.strong,{children:"API access"})," to get pregenerated code snippets that call the Langflow API and run the flow."]}),"\n",(0,t.jsxs)(n.p,{children:["These code snippets construct API requests with your Langflow server URL (",(0,t.jsx)(n.code,{children:"LANGFLOW_SERVER_ADDRESS"}),"), the flow to run (",(0,t.jsx)(n.code,{children:"FLOW_ID"}),"), required headers (",(0,t.jsx)(n.code,{children:"LANGFLOW_API_KEY"}),", ",(0,t.jsx)(n.code,{children:"Content-Type"}),"), and a payload containing the required inputs to run the flow, including a default chat input message."]}),"\n",(0,t.jsx)(n.p,{children:"In production, you would modify the inputs to suit your application logic. For example, you could replace the default chat input message with dynamic user input."}),"\n",(0,t.jsxs)(o.A,{children:[(0,t.jsx)(a.A,{value:"python",label:"Python",children:(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-python",children:'import requests\nimport os\nimport uuid\n\napi_key = \'LANGFLOW_API_KEY\'\nurl = "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID" # The complete API endpoint URL for this flow\n\n# Request payload configuration\npayload = {\n "output_type": "chat",\n "input_type": "chat",\n "input_value": "hello world!"\n}\npayload["session_id"] = str(uuid.uuid4())\n\nheaders = {"x-api-key": api_key}\n\ntry:\n # Send API request\n response = requests.request("POST", url, json=payload, headers=headers)\n response.raise_for_status() # Raise exception for bad status codes\n\n # Print response\n print(response.text)\n\nexcept requests.exceptions.RequestException as e:\n print(f"Error making API request: {e}")\nexcept ValueError as e:\n print(f"Error parsing response: {e}")\n'})})}),(0,t.jsx)(a.A,{value:"typescript",label:"TypeScript",children:(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:'const crypto = require(\'crypto\');\nconst apiKey = \'LANGFLOW_API_KEY\';\nconst payload = {\n "output_type": "chat",\n "input_type": "chat",\n "input_value": "hello world!"\n};\npayload.session_id = crypto.randomUUID();\n\nconst options = {\n method: \'POST\',\n headers: {\n \'Content-Type\': \'application/json\',\n "x-api-key": apiKey\n },\n body: JSON.stringify(payload)\n};\n\nfetch(\'http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID\', options)\n .then(response => response.json())\n .then(response => console.warn(response))\n .catch(err => console.error(err));\n'})})}),(0,t.jsx)(a.A,{value:"curl",label:"curl",children:(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'curl --request POST \\\n --url \'http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID?stream=false\' \\\n --header \'Content-Type: application/json\' \\\n --header "x-api-key: LANGFLOW_API_KEY" \\\n --data \'{\n "output_type": "chat",\n "input_type": "chat",\n "input_value": "hello world!"\n }\'\n'})})})]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:"Copy your preferred snippet, and then run it:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Python"}),": Paste the snippet into a ",(0,t.jsx)(n.code,{children:".py"})," file, save it, and then run it with ",(0,t.jsx)(n.code,{children:"python filename.py"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"TypeScript"}),": Paste the snippet into a ",(0,t.jsx)(n.code,{children:".ts"})," file, save it, and then run it with ",(0,t.jsx)(n.code,{children:"ts-node filename.ts"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"curl"}),": Paste and run snippet directly in your terminal."]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"If the request is successful, the response includes many details about the flow run, including the session ID, inputs, outputs, components, durations, and more."}),"\n",(0,t.jsxs)(n.p,{children:["In production, you won't pass the raw response to the user in its entirety.\nInstead, you extract and reformat relevant fields for different use cases, as demonstrated in the ",(0,t.jsx)(n.a,{href:"https://docs.langflow.org/quickstart#extract-data-from-the-response",children:"Langflow quickstart"}),".\nFor example, you could pass the chat output text to a front-end user-facing application, and store specific fields in logs and backend data stores for monitoring, chat history, or analytics.\nYou could also pass the output from one flow as input to another flow."]})]})}function d(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(c,{...e})}):c(e)}}}]); \ No newline at end of file +"use strict";(self.webpackChunkopenrag_docs=self.webpackChunkopenrag_docs||[]).push([[98],{1260:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>h,contentTitle:()=>d,default:()=>x,frontMatter:()=>c,metadata:()=>t,toc:()=>u});const t=JSON.parse('{"id":"get-started/quickstart","title":"Quickstart","description":"Use this quickstart to install OpenRAG, and then try some of OpenRAG\'s core features.","source":"@site/docs/get-started/quickstart.mdx","sourceDirName":"get-started","slug":"/quickstart","permalink":"/quickstart","draft":false,"unlisted":false,"editUrl":"https://github.com/openrag/openrag/tree/main/docs/docs/get-started/quickstart.mdx","tags":[],"version":"current","frontMatter":{"title":"Quickstart","slug":"/quickstart"},"sidebar":"tutorialSidebar","previous":{"title":"About OpenRAG","permalink":"/"},"next":{"title":"Install OpenRAG with TUI","permalink":"/install"}}');var i=s(4848),r=s(8453),o=s(1610),a=(s(1470),s(9365),s(3862)),l=s(7224);const c={title:"Quickstart",slug:"/quickstart"},d=void 0,h={},u=[{value:"Prerequisites",id:"prerequisites",level:2},...a.RM,{value:"Install OpenRAG",id:"install-openrag",level:2},{value:"Load and chat with documents",id:"chat-with-documents",level:2},{value:"Change the language model and chat settings",id:"change-components",level:2},{value:"Integrate OpenRAG into an application",id:"integrate-openrag-into-an-application",level:2},...l.RM,{value:"Next steps",id:"next-steps",level:2}];function p(e){const n={a:"a",code:"code",h2:"h2",img:"img",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components},{Details:t}=n;return t||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.p,{children:"Use this quickstart to install OpenRAG, and then try some of OpenRAG's core features."}),"\n",(0,i.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,i.jsx)(n.p,{children:"This quickstart requires the following:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["An ",(0,i.jsx)(n.a,{href:"https://platform.openai.com/api-keys",children:"OpenAI API key"}),".\nThis quickstart uses OpenAI for simplicity.\nFor other providers, see the complete ",(0,i.jsx)(n.a,{href:"/install",children:"installation guide"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.a,{href:"https://www.python.org/downloads/release/python-3100/",children:"Python"})," version 3.13 or later."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Microsoft Windows only: To run OpenRAG on Windows, you must use the Windows Subsystem for Linux (WSL)."}),"\n",(0,i.jsxs)(t,{children:[(0,i.jsx)("summary",{children:"Install WSL for OpenRAG"}),(0,i.jsx)(a.Ay,{})]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"install-openrag",children:"Install OpenRAG"}),"\n",(0,i.jsx)(n.p,{children:"For this quickstart, install OpenRAG with the automatic installer script and basic setup:"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Create a directory to store the OpenRAG configuration files, and then change to that directory:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"mkdir openrag-workspace\ncd openrag-workspace\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.a,{href:"https://docs.openr.ag/files/run_openrag_with_prereqs.sh",children:"Download the OpenRAG install script"}),", move it to your OpenRAG directory, and then run it:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"bash run_openrag_with_prereqs.sh\n"})}),"\n",(0,i.jsxs)(n.p,{children:["This script installs OpenRAG and its dependencies, including Docker or Podman, and it creates a ",(0,i.jsx)(n.code,{children:".env"})," file and ",(0,i.jsx)(n.code,{children:"docker-compose"})," files in the current working directory.\nYou might be prompted to install certain dependencies if they aren't already present in your environment.\nThis process can take a few minutes.\nOnce the environment is ready, OpenRAG starts."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Basic Setup"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Create passwords for your OpenRAG installation's OpenSearch and Langflow services. You can click ",(0,i.jsx)(n.strong,{children:"Generate Passwords"})," to automatically generate passwords."]}),"\n",(0,i.jsxs)(n.p,{children:["The OpenSearch password is required. The Langflow admin password is optional.\nIf you don't generate a Langflow admin password, Langflow runs in ",(0,i.jsx)(n.a,{href:"https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login",children:"autologin mode"})," with no password required."]}),"\n",(0,i.jsxs)(n.p,{children:["Your passwords are saved in the ",(0,i.jsx)(n.code,{children:".env"})," file that is used to start OpenRAG.\nYou can find this file in your OpenRAG installation directory."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Save Configuration"}),", and then click ",(0,i.jsx)(n.strong,{children:"Start All Services"}),"."]}),"\n",(0,i.jsx)(n.p,{children:"Wait a few minutes while the startup process pulls and runs the necessary container images.\nProceed when you see the following messages in the terminal user interface (TUI):"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"Services started successfully\nCommand completed successfully\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To open the OpenRAG application, go to the TUI main menu, and then click ",(0,i.jsx)(n.strong,{children:"Open App"}),".\nAlternatively, in your browser, navigate to ",(0,i.jsx)(n.code,{children:"localhost:3000"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Select the ",(0,i.jsx)(n.strong,{children:"OpenAI"})," model provider, enter your OpenAI API key, and then click ",(0,i.jsx)(n.strong,{children:"Complete"}),"."]}),"\n",(0,i.jsx)(n.p,{children:"For this quickstart, you can use the default options for the model settings."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click through the overview slides for a brief introduction to OpenRAG and basic setup, or click ",(0,i.jsx)(o.A,{name:"ArrowRight","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Skip overview"}),".\nYou can complete this quickstart without going through the overview."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"chat-with-documents",children:"Load and chat with documents"}),"\n",(0,i.jsxs)(n.p,{children:["Use the ",(0,i.jsxs)(n.a,{href:"/chat",children:["OpenRAG ",(0,i.jsx)(n.strong,{children:"Chat"})]})," to explore the documents in your OpenRAG database using natural language queries.\nSome documents are included by default to get you started, and you can load your own documents."]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["In OpenRAG, click ",(0,i.jsx)(o.A,{name:"MessageSquare","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Chat"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["For this quickstart, ask the agent what documents are available.\nFor example: ",(0,i.jsx)(n.code,{children:"What documents are available to you?"})]}),"\n",(0,i.jsx)(n.p,{children:"The agent responds with a summary of OpenRAG's default documents."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To verify the agent's response, click ",(0,i.jsx)(o.A,{name:"Library","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Knowledge"})," to view the documents stored in the OpenRAG OpenSearch vector database.\nYou can click a document to view the chunks of the document as they are stored in the database."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Add Knowledge"})," to add your own documents to your OpenRAG knowledge base."]}),"\n",(0,i.jsxs)(n.p,{children:["For this quickstart, use either the ",(0,i.jsx)(o.A,{name:"File","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"File"})," or ",(0,i.jsx)(o.A,{name:"Folder","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Folder"})," upload options to load documents from your local machine.\n",(0,i.jsx)(n.strong,{children:"Folder"})," uploads an entire directory.\nThe default directory is the ",(0,i.jsx)(n.code,{children:"/openrag-documents"})," subdirectory in your OpenRAG installation directory."]}),"\n",(0,i.jsxs)(n.p,{children:["For information about the cloud storage provider options, see ",(0,i.jsx)(n.a,{href:"/ingestion#oauth-ingestion",children:"Ingest files with OAuth connectors"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Return to the ",(0,i.jsx)(n.strong,{children:"Chat"})," window, and then ask a question related to the documents that you just uploaded."]}),"\n",(0,i.jsx)(n.p,{children:"If the agent's response doesn't seem to reference your documents correctly, try the following:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(o.A,{name:"Gear","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Function Call: search_documents (tool_call)"})," to view the log of tool calls made by the agent. This is helpful for troubleshooting because it shows you how the agent used particular tools."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(o.A,{name:"Library","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Knowledge"})," to confirm that the documents are present in the OpenRAG OpenSearch vector database, and then click each document to see how the document was chunked.\nIf a document was chunked improperly, you might need to tweak the ingestion or modify and reupload the document."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(o.A,{name:"Settings2","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Settings"})," to modify the knowledge ingestion settings."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["For more information, see ",(0,i.jsx)(n.a,{href:"/knowledge",children:"Configure knowledge"})," and ",(0,i.jsx)(n.a,{href:"/ingestion",children:"Ingest knowledge"}),"."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"change-components",children:"Change the language model and chat settings"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To change the knowledge ingestion settings, agent behavior, or language model, click ",(0,i.jsx)(o.A,{name:"Settings2","aria-hidden":"true"})," ",(0,i.jsx)(n.strong,{children:"Settings"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.strong,{children:"Settings"})," page provides quick access to commonly used parameters like the ",(0,i.jsx)(n.strong,{children:"Language model"})," and ",(0,i.jsx)(n.strong,{children:"Agent Instructions"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["For greater insight into the underlying ",(0,i.jsx)(n.a,{href:"/agents",children:"Langflow flow"})," that drives the OpenRAG chat, click ",(0,i.jsx)(n.strong,{children:"Edit in Langflow"})," and then click ",(0,i.jsx)(n.strong,{children:"Proceed"})," to launch the Langflow visual editor in a new browser window."]}),"\n",(0,i.jsxs)(n.p,{children:["If Langflow requests login information, enter the ",(0,i.jsx)(n.code,{children:"LANGFLOW_SUPERUSER"})," and ",(0,i.jsx)(n.code,{children:"LANGFLOW_SUPERUSER_PASSWORD"})," from the ",(0,i.jsx)(n.code,{children:".env"})," file in your OpenRAG installation directory."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.strong,{children:"OpenRAG OpenSearch Agent"})," flow opens in a new browser window."]}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.img,{alt:"OpenRAG OpenSearch Agent flow",src:s(3982).A+"",width:"4084",height:"2176"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["For this quickstart, try changing the model.\nClick the ",(0,i.jsx)(n.strong,{children:"Language Model"})," component, and then change the ",(0,i.jsx)(n.strong,{children:"Model Name"})," to a different OpenAI model."]}),"\n",(0,i.jsxs)(n.p,{children:["After you edit a built-in flow, you can click ",(0,i.jsx)(n.strong,{children:"Restore flow"})," on the ",(0,i.jsx)(n.strong,{children:"Settings"})," page to revert the flow to its original state when you first installed OpenRAG."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Press ",(0,i.jsx)("kbd",{children:"Command"}),"+",(0,i.jsx)("kbd",{children:"S"})," (",(0,i.jsx)("kbd",{children:"Ctrl"}),"+",(0,i.jsx)("kbd",{children:"S"}),") to save your changes."]}),"\n",(0,i.jsx)(n.p,{children:"You can close the Langflow browser window, or leave it open if you want to continue experimenting with the flow editor."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Switch to your OpenRAG browser window, and then click ",(0,i.jsx)(o.A,{name:"Plus","aria-hidden":"true"})," in the ",(0,i.jsx)(n.strong,{children:"Conversations"})," tab to start a new conversation.\nThis ensures that the chat doesn't persist any context from the previous conversation with the original model."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Ask the same question you asked in ",(0,i.jsx)(n.a,{href:"#chat-with-documents",children:"Load and chat with documents"})," to see how the response differs from the original model."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"integrate-openrag-into-an-application",children:"Integrate OpenRAG into an application"}),"\n",(0,i.jsxs)(n.p,{children:["Langflow in OpenRAG includes pre-built flows that you can integrate into your applications using the ",(0,i.jsx)(n.a,{href:"https://docs.langflow.org/api-reference-api-examples",children:"Langflow API"}),".\nYou can use these flows as-is or modify them to better suit your needs, as demonstrated in ",(0,i.jsx)(n.a,{href:"#change-components",children:"Change the language model and chat settings"}),"."]}),"\n",(0,i.jsx)(n.p,{children:"You can send and receive requests with the Langflow API using Python, TypeScript, or curl."}),"\n",(0,i.jsx)(l.Ay,{}),"\n",(0,i.jsx)(n.h2,{id:"next-steps",children:"Next steps"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Reinstall OpenRAG with your preferred settings"}),": This quickstart used a minimal setup to demonstrate OpenRAG's core functionality.\nIt is recommended that you ",(0,i.jsx)(n.a,{href:"/install#reinstall",children:"reinstall OpenRAG"})," with your preferred configuration because some settings are immutable after initial setup.\nFor all installation options, see ",(0,i.jsx)(n.a,{href:"/install",children:"Install OpenRAG with TUI"})," and ",(0,i.jsx)(n.a,{href:"/docker",children:"Install OpenRAG with containers"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Learn more about OpenRAG"}),": Explore OpenRAG and the OpenRAG documentation to learn more about its features and functionality."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Learn more about Langflow"}),": For a deep dive on the Langflow API and visual editor, see the ",(0,i.jsx)(n.a,{href:"https://docs.langflow.org/",children:"Langflow documentation"}),"."]}),"\n"]}),"\n"]})]})}function x(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(p,{...e})}):p(e)}},3862:(e,n,s)=>{s.d(n,{Ay:()=>a,RM:()=>r});var t=s(4848),i=s(8453);const r=[];function o(e){const n={a:"a",admonition:"admonition",code:"code",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",...(0,i.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install",children:"Install WSL"})," with the Ubuntu distribution using WSL 2:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-powershell",children:"wsl --install -d Ubuntu\n"})}),"\n",(0,t.jsxs)(n.p,{children:["For new installations, the ",(0,t.jsx)(n.code,{children:"wsl --install"})," command uses WSL 2 and Ubuntu by default."]}),"\n",(0,t.jsxs)(n.p,{children:["For existing WSL installations, you can ",(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install#change-the-default-linux-distribution-installed",children:"change the distribution"})," and ",(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install#upgrade-version-from-wsl-1-to-wsl-2",children:"check the WSL version"}),"."]}),"\n",(0,t.jsx)(n.admonition,{title:"Known limitation",type:"warning",children:(0,t.jsx)(n.p,{children:"OpenRAG isn't compatible with nested virtualization, which can cause networking issues.\nDon't install OpenRAG on a WSL distribution that is installed inside a Windows VM.\nInstead, install OpenRAG on your base OS or a non-nested Linux VM."})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install#ways-to-run-multiple-linux-distributions-with-wsl",children:"Start your WSL Ubuntu distribution"})," if it doesn't start automatically."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-your-linux-username-and-password",children:"Set up a username and password for your WSL distribution"}),"."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers",children:"Install Docker Desktop for Windows with WSL 2"}),". When you reach the Docker Desktop ",(0,t.jsx)(n.strong,{children:"WSL integration"})," settings, make sure your Ubuntu distribution is enabled, and then click ",(0,t.jsx)(n.strong,{children:"Apply & Restart"})," to enable Docker support in WSL."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:"Install and run OpenRAG from within your WSL Ubuntu distribution."}),"\n"]}),"\n"]}),"\n",(0,t.jsx)("br",{}),"\n",(0,t.jsxs)(n.p,{children:["If you encounter issues with port forwarding or the Windows Firewall, you might need to adjust the ",(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall",children:"Hyper-V firewall settings"})," to allow communication between your WSL distribution and the Windows host. For more troubleshooting advice for networking issues, see ",(0,t.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#common-issues",children:"Troubleshooting WSL common issues"}),"."]})]})}function a(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(o,{...e})}):o(e)}},3982:(e,n,s)=>{s.d(n,{A:()=>t});const t=s.p+"assets/images/opensearch-agent-flow-f3b279e02425cd043002eb7749067108.png"},7224:(e,n,s)=>{s.d(n,{Ay:()=>d,RM:()=>l});var t=s(4848),i=s(8453),r=s(1610),o=s(1470),a=s(9365);const l=[];function c(e){const n={a:"a",code:"code",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:["Open the ",(0,t.jsx)(n.strong,{children:"OpenRAG OpenSearch Agent"})," flow in the Langflow visual editor: From the ",(0,t.jsx)(n.strong,{children:"Chat"})," window, click ",(0,t.jsx)(r.A,{name:"Settings2","aria-hidden":"true"})," ",(0,t.jsx)(n.strong,{children:"Settings"}),", click ",(0,t.jsx)(n.strong,{children:"Edit in Langflow"}),", and then click ",(0,t.jsx)(n.strong,{children:"Proceed"}),"."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:["Create a ",(0,t.jsx)(n.a,{href:"https://docs.langflow.org/api-keys-and-authentication",children:"Langflow API key"}),", which is a user-specific token required to send requests to the Langflow server.\nThis key doesn't grant access to OpenRAG."]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["In the Langflow visual editor, click your user icon in the header, and then select ",(0,t.jsx)(n.strong,{children:"Settings"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:["Click ",(0,t.jsx)(n.strong,{children:"Langflow API Keys"}),", and then click ",(0,t.jsx)(r.A,{name:"Plus","aria-hidden":"true"})," ",(0,t.jsx)(n.strong,{children:"Add New"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:["Name your key, and then click ",(0,t.jsx)(n.strong,{children:"Create API Key"}),"."]}),"\n",(0,t.jsx)(n.li,{children:"Copy the API key and store it securely."}),"\n",(0,t.jsxs)(n.li,{children:["Exit the Langflow ",(0,t.jsx)(n.strong,{children:"Settings"})," page to return to the visual editor."]}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:["Click ",(0,t.jsx)(n.strong,{children:"Share"}),", and then select ",(0,t.jsx)(n.strong,{children:"API access"})," to get pregenerated code snippets that call the Langflow API and run the flow."]}),"\n",(0,t.jsxs)(n.p,{children:["These code snippets construct API requests with your Langflow server URL (",(0,t.jsx)(n.code,{children:"LANGFLOW_SERVER_ADDRESS"}),"), the flow to run (",(0,t.jsx)(n.code,{children:"FLOW_ID"}),"), required headers (",(0,t.jsx)(n.code,{children:"LANGFLOW_API_KEY"}),", ",(0,t.jsx)(n.code,{children:"Content-Type"}),"), and a payload containing the required inputs to run the flow, including a default chat input message."]}),"\n",(0,t.jsx)(n.p,{children:"In production, you would modify the inputs to suit your application logic. For example, you could replace the default chat input message with dynamic user input."}),"\n",(0,t.jsxs)(o.A,{children:[(0,t.jsx)(a.A,{value:"python",label:"Python",children:(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-python",children:'import requests\nimport os\nimport uuid\n\napi_key = \'LANGFLOW_API_KEY\'\nurl = "http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID" # The complete API endpoint URL for this flow\n\n# Request payload configuration\npayload = {\n "output_type": "chat",\n "input_type": "chat",\n "input_value": "hello world!"\n}\npayload["session_id"] = str(uuid.uuid4())\n\nheaders = {"x-api-key": api_key}\n\ntry:\n # Send API request\n response = requests.request("POST", url, json=payload, headers=headers)\n response.raise_for_status() # Raise exception for bad status codes\n\n # Print response\n print(response.text)\n\nexcept requests.exceptions.RequestException as e:\n print(f"Error making API request: {e}")\nexcept ValueError as e:\n print(f"Error parsing response: {e}")\n'})})}),(0,t.jsx)(a.A,{value:"typescript",label:"TypeScript",children:(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:'const crypto = require(\'crypto\');\nconst apiKey = \'LANGFLOW_API_KEY\';\nconst payload = {\n "output_type": "chat",\n "input_type": "chat",\n "input_value": "hello world!"\n};\npayload.session_id = crypto.randomUUID();\n\nconst options = {\n method: \'POST\',\n headers: {\n \'Content-Type\': \'application/json\',\n "x-api-key": apiKey\n },\n body: JSON.stringify(payload)\n};\n\nfetch(\'http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID\', options)\n .then(response => response.json())\n .then(response => console.warn(response))\n .catch(err => console.error(err));\n'})})}),(0,t.jsx)(a.A,{value:"curl",label:"curl",children:(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'curl --request POST \\\n --url \'http://LANGFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID?stream=false\' \\\n --header \'Content-Type: application/json\' \\\n --header "x-api-key: LANGFLOW_API_KEY" \\\n --data \'{\n "output_type": "chat",\n "input_type": "chat",\n "input_value": "hello world!"\n }\'\n'})})})]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:"Copy your preferred snippet, and then run it:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Python"}),": Paste the snippet into a ",(0,t.jsx)(n.code,{children:".py"})," file, save it, and then run it with ",(0,t.jsx)(n.code,{children:"python filename.py"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"TypeScript"}),": Paste the snippet into a ",(0,t.jsx)(n.code,{children:".ts"})," file, save it, and then run it with ",(0,t.jsx)(n.code,{children:"ts-node filename.ts"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"curl"}),": Paste and run snippet directly in your terminal."]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"If the request is successful, the response includes many details about the flow run, including the session ID, inputs, outputs, components, durations, and more."}),"\n",(0,t.jsxs)(n.p,{children:["In production, you won't pass the raw response to the user in its entirety.\nInstead, you extract and reformat relevant fields for different use cases, as demonstrated in the ",(0,t.jsx)(n.a,{href:"https://docs.langflow.org/quickstart#extract-data-from-the-response",children:"Langflow quickstart"}),".\nFor example, you could pass the chat output text to a front-end user-facing application, and store specific fields in logs and backend data stores for monitoring, chat history, or analytics.\nYou could also pass the output from one flow as input to another flow."]})]})}function d(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(c,{...e})}):c(e)}}}]); \ No newline at end of file diff --git a/assets/js/c8078f0a.d456318f.js b/assets/js/c8078f0a.f1c0e5b8.js similarity index 84% rename from assets/js/c8078f0a.d456318f.js rename to assets/js/c8078f0a.f1c0e5b8.js index a8091431..1fd5467d 100644 --- a/assets/js/c8078f0a.d456318f.js +++ b/assets/js/c8078f0a.f1c0e5b8.js @@ -1 +1 @@ -"use strict";(self.webpackChunkopenrag_docs=self.webpackChunkopenrag_docs||[]).push([[9026],{9196:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>c,contentTitle:()=>t,default:()=>a,frontMatter:()=>l,metadata:()=>i,toc:()=>o});const i=JSON.parse('{"id":"reference/configuration","title":"Environment variables","description":"OpenRAG recognizes environment variables from the following sources:","source":"@site/docs/reference/configuration.mdx","sourceDirName":"reference","slug":"/reference/configuration","permalink":"/reference/configuration","draft":false,"unlisted":false,"editUrl":"https://github.com/openrag/openrag/tree/main/docs/docs/reference/configuration.mdx","tags":[],"version":"current","frontMatter":{"title":"Environment variables","slug":"/reference/configuration"},"sidebar":"tutorialSidebar","previous":{"title":"Chat","permalink":"/chat"},"next":{"title":"Troubleshoot OpenRAG","permalink":"/support/troubleshoot"}}');var r=s(4848),d=s(8453);s(1610),s(1470),s(9365);const l={title:"Environment variables",slug:"/reference/configuration"},t=void 0,c={},o=[{value:"Configure environment variables",id:"configure-environment-variables",level:2},{value:"Set environment variables",id:"set-environment-variables",level:3},{value:"Supported environment variables",id:"supported-environment-variables",level:2},{value:"AI provider settings",id:"ai-provider-settings",level:3},{value:"Document processing",id:"document-processing",level:3},{value:"Langflow settings",id:"langflow-settings",level:3},{value:"OAuth provider settings",id:"oauth-provider-settings",level:3},{value:"OpenSearch settings",id:"opensearch-settings",level:3},{value:"System settings",id:"system-settings",level:3},{value:"Langflow runtime overrides",id:"langflow-runtime-overrides",level:2},{value:"Default values and fallbacks",id:"default-values-and-fallbacks",level:2}];function h(e){const n={a:"a",code:"code",em:"em",h2:"h2",h3:"h3",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,d.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.p,{children:"OpenRAG recognizes environment variables from the following sources:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"#configure-environment-variables",children:"Environment variables"}),": Values set in the ",(0,r.jsx)(n.code,{children:".env"})," file."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"#langflow-runtime-overrides",children:"Langflow runtime overrides"}),": Langflow components can set environment variables at runtime."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"#default-values-and-fallbacks",children:"Default or fallback values"}),": These values are default or fallback values if OpenRAG doesn't find a value."]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"configure-environment-variables",children:"Configure environment variables"}),"\n",(0,r.jsxs)(n.p,{children:["Environment variables are set in a ",(0,r.jsx)(n.code,{children:".env"})," file in the root of your OpenRAG project directory."]}),"\n",(0,r.jsxs)(n.p,{children:["For an example ",(0,r.jsx)(n.code,{children:".env"})," file, see ",(0,r.jsxs)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/.env.example",children:[(0,r.jsx)(n.code,{children:".env.example"})," in the OpenRAG repository"]}),"."]}),"\n",(0,r.jsxs)(n.p,{children:["The Docker Compose files are populated with values from your ",(0,r.jsx)(n.code,{children:".env"}),", so you don't need to edit the Docker Compose files manually."]}),"\n",(0,r.jsx)(n.p,{children:"Environment variables always take precedence over other variables."}),"\n",(0,r.jsx)(n.h3,{id:"set-environment-variables",children:"Set environment variables"}),"\n",(0,r.jsxs)(n.p,{children:["After you start OpenRAG, you must ",(0,r.jsx)(n.a,{href:"/install#tui-container-management",children:"stop and restart OpenRAG containers"})," to apply any changes you make to the ",(0,r.jsx)(n.code,{children:".env"})," file."]}),"\n",(0,r.jsx)(n.p,{children:"To set mutable environment variables, do the following:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:"Stop OpenRAG with the TUI or Docker Compose."}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:["Set the values in the ",(0,r.jsx)(n.code,{children:".env"})," file:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"LOG_LEVEL=DEBUG\nLOG_FORMAT=json\nSERVICE_NAME=openrag-dev\n"})}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:"Start OpenRAG with the TUI or Docker Compose."}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:["Certain environment variables that you set during ",(0,r.jsx)(n.a,{href:"/install#application-onboarding",children:"application onboarding"}),", such as provider API keys and provider endpoints, require resetting the containers after modifying the ",(0,r.jsx)(n.code,{children:".env"})," file."]}),"\n",(0,r.jsxs)(n.p,{children:["To change immutable variables with TUI-managed containers, you must ",(0,r.jsx)(n.a,{href:"/install#reinstall",children:"reinstall OpenRAG"})," and either delete or modify the ",(0,r.jsx)(n.code,{children:".env"})," file before you repeat the setup and onboarding process in the TUI."]}),"\n",(0,r.jsx)(n.p,{children:"To change immutable variables with self-managed containers, do the following:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:"Stop OpenRAG with Docker Compose."}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:"Remove the containers:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker-compose down\n"})}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:["Update the values in your ",(0,r.jsx)(n.code,{children:".env"})," file."]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:"Start OpenRAG with Docker Compose:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker-compose up -d\n"})}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:["Repeat ",(0,r.jsx)(n.a,{href:"/install#application-onboarding",children:"application onboarding"}),". The values in your ",(0,r.jsx)(n.code,{children:".env"})," file are automatically populated."]}),"\n"]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"supported-environment-variables",children:"Supported environment variables"}),"\n",(0,r.jsx)(n.p,{children:"All OpenRAG configuration can be controlled through environment variables."}),"\n",(0,r.jsx)(n.h3,{id:"ai-provider-settings",children:"AI provider settings"}),"\n",(0,r.jsxs)(n.p,{children:["Configure which models and providers OpenRAG uses to generate text and embeddings.\nThese are initially set during ",(0,r.jsx)(n.a,{href:"/install#application-onboarding",children:"application onboarding"}),".\nSome values are immutable and can only be changed by recreating the OpenRAG containers, as explained in ",(0,r.jsx)(n.a,{href:"#set-environment-variables",children:"Set environment variables"}),"."]}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Variable"}),(0,r.jsx)(n.th,{children:"Default"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"EMBEDDING_MODEL"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"text-embedding-3-small"})}),(0,r.jsx)(n.td,{children:"Embedding model for generating vector embeddings for documents in the knowledge base and similarity search queries. Can be changed after application onboarding. Accepts one or more models."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LLM_MODEL"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"gpt-4o-mini"})}),(0,r.jsxs)(n.td,{children:["Language model for language processing and text generation in the ",(0,r.jsx)(n.strong,{children:"Chat"})," feature."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"MODEL_PROVIDER"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"openai"})}),(0,r.jsx)(n.td,{children:"Model provider, such as OpenAI or IBM watsonx.ai."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENAI_API_KEY"})}),(0,r.jsx)(n.td,{children:"Not set"}),(0,r.jsxs)(n.td,{children:["Optional OpenAI API key for the default model. For other providers, use ",(0,r.jsx)(n.code,{children:"PROVIDER_API_KEY"}),"."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"PROVIDER_API_KEY"})}),(0,r.jsx)(n.td,{children:"Not set"}),(0,r.jsx)(n.td,{children:"API key for the model provider."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"PROVIDER_ENDPOINT"})}),(0,r.jsx)(n.td,{children:"Not set"}),(0,r.jsx)(n.td,{children:"Custom provider endpoint for the IBM and Ollama model providers. Leave unset for other model providers."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"PROVIDER_PROJECT_ID"})}),(0,r.jsx)(n.td,{children:"Not set"}),(0,r.jsx)(n.td,{children:"Project ID for the IBM watsonx.ai model provider only. Leave unset for other model providers."})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"document-processing",children:"Document processing"}),"\n",(0,r.jsxs)(n.p,{children:["Control how OpenRAG ",(0,r.jsx)(n.a,{href:"/ingestion",children:"processes and ingests documents"})," into your knowledge base."]}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Variable"}),(0,r.jsx)(n.th,{children:"Default"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"CHUNK_OVERLAP"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"200"})}),(0,r.jsx)(n.td,{children:"Overlap between chunks."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"CHUNK_SIZE"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"1000"})}),(0,r.jsx)(n.td,{children:"Text chunk size for document processing."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"DISABLE_INGEST_WITH_LANGFLOW"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"false"})}),(0,r.jsx)(n.td,{children:"Disable Langflow ingestion pipeline."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"DOCLING_OCR_ENGINE"})}),(0,r.jsx)(n.td,{children:"Set by OS"}),(0,r.jsxs)(n.td,{children:["OCR engine for document processing. For macOS, ",(0,r.jsx)(n.code,{children:"ocrmac"}),". For any other OS, ",(0,r.jsx)(n.code,{children:"easyocr"}),"."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OCR_ENABLED"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"false"})}),(0,r.jsx)(n.td,{children:"Enable OCR for image processing."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENRAG_DOCUMENTS_PATHS"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"./openrag-documents"})}),(0,r.jsx)(n.td,{children:"Document paths for ingestion."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"PICTURE_DESCRIPTIONS_ENABLED"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"false"})}),(0,r.jsx)(n.td,{children:"Enable picture descriptions."})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"langflow-settings",children:"Langflow settings"}),"\n",(0,r.jsx)(n.p,{children:"Configure Langflow authentication."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Variable"}),(0,r.jsx)(n.th,{children:"Default"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_AUTO_LOGIN"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"False"})}),(0,r.jsx)(n.td,{children:"Enable auto-login for Langflow."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_CHAT_FLOW_ID"})}),(0,r.jsx)(n.td,{children:"Built-in flow ID"}),(0,r.jsxs)(n.td,{children:["This value is automatically set to the ID of the chat ",(0,r.jsx)(n.a,{href:"/agents",children:"flow"}),". The default value is found in ",(0,r.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/.env.example",children:(0,r.jsx)(n.code,{children:".env.example"})}),". Only change this value if you explicitly don't want to use this built-in flow."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_ENABLE_SUPERUSER_CLI"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"False"})}),(0,r.jsx)(n.td,{children:"Enable superuser privileges for Langflow CLI commands."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_INGEST_FLOW_ID"})}),(0,r.jsx)(n.td,{children:"Built-in flow ID"}),(0,r.jsxs)(n.td,{children:["This value is automatically set to the ID of the ingestion ",(0,r.jsx)(n.a,{href:"/agents",children:"flow"}),". The default value is found in ",(0,r.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/.env.example",children:(0,r.jsx)(n.code,{children:".env.example"})}),". Only change this value if you explicitly don't want to use this built-in flow."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_KEY"})}),(0,r.jsx)(n.td,{children:"Automatically generated"}),(0,r.jsx)(n.td,{children:"Explicit Langflow API key."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_NEW_USER_IS_ACTIVE"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"False"})}),(0,r.jsx)(n.td,{children:"Whether new Langflow users are active by default."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_PUBLIC_URL"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"http://localhost:7860"})}),(0,r.jsx)(n.td,{children:"Public URL for the Langflow instance."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_SECRET_KEY"})}),(0,r.jsx)(n.td,{children:"Not set"}),(0,r.jsx)(n.td,{children:"Secret key for Langflow internal operations."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_SUPERUSER"})}),(0,r.jsx)(n.td,{children:"None, must be explicitly set"}),(0,r.jsx)(n.td,{children:"Langflow admin username. Required."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_SUPERUSER_PASSWORD"})}),(0,r.jsx)(n.td,{children:"None, must be explicitly set"}),(0,r.jsx)(n.td,{children:"Langflow admin password. Required."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_URL"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"http://localhost:7860"})}),(0,r.jsx)(n.td,{children:"URL for the Langflow instance."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"NUDGES_FLOW_ID"})}),(0,r.jsx)(n.td,{children:"Built-in flow ID"}),(0,r.jsxs)(n.td,{children:["This value is automatically set to the ID of the nudges ",(0,r.jsx)(n.a,{href:"/agents",children:"flow"}),". The default value is found in ",(0,r.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/.env.example",children:(0,r.jsx)(n.code,{children:".env.example"})}),". Only change this value if you explicitly don't want to use this built-in flow."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"SYSTEM_PROMPT"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context."})}),(0,r.jsxs)(n.td,{children:["System prompt instructions for the agent driving the ",(0,r.jsx)(n.strong,{children:"Chat"})," flow."]})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"oauth-provider-settings",children:"OAuth provider settings"}),"\n",(0,r.jsx)(n.p,{children:"Configure OAuth providers and external service integrations."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Variable"}),(0,r.jsx)(n.th,{children:"Default"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"AWS_ACCESS_KEY_ID"})," / ",(0,r.jsx)(n.code,{children:"AWS_SECRET_ACCESS_KEY"})]}),(0,r.jsx)(n.td,{children:"-"}),(0,r.jsx)(n.td,{children:"AWS integrations."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"GOOGLE_OAUTH_CLIENT_ID"})," / ",(0,r.jsx)(n.code,{children:"GOOGLE_OAUTH_CLIENT_SECRET"})]}),(0,r.jsx)(n.td,{children:"-"}),(0,r.jsx)(n.td,{children:"Google OAuth authentication."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"MICROSOFT_GRAPH_OAUTH_CLIENT_ID"})," / ",(0,r.jsx)(n.code,{children:"MICROSOFT_GRAPH_OAUTH_CLIENT_SECRET"})]}),(0,r.jsx)(n.td,{children:"-"}),(0,r.jsx)(n.td,{children:"Microsoft OAuth."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"WEBHOOK_BASE_URL"})}),(0,r.jsx)(n.td,{children:"-"}),(0,r.jsx)(n.td,{children:"Base URL for webhook endpoints."})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"opensearch-settings",children:"OpenSearch settings"}),"\n",(0,r.jsx)(n.p,{children:"Configure OpenSearch database authentication."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Variable"}),(0,r.jsx)(n.th,{children:"Default"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENSEARCH_HOST"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"localhost"})}),(0,r.jsx)(n.td,{children:"OpenSearch host."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENSEARCH_PASSWORD"})}),(0,r.jsx)(n.td,{children:"-"}),(0,r.jsx)(n.td,{children:"Password for OpenSearch admin user. Required."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENSEARCH_PORT"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"9200"})}),(0,r.jsx)(n.td,{children:"OpenSearch port."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENSEARCH_USERNAME"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"admin"})}),(0,r.jsx)(n.td,{children:"OpenSearch username."})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"system-settings",children:"System settings"}),"\n",(0,r.jsx)(n.p,{children:"Configure general system components, session management, and logging."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Variable"}),(0,r.jsx)(n.th,{children:"Default"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_KEY_RETRIES"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"15"})}),(0,r.jsx)(n.td,{children:"Number of retries for Langflow key generation."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_KEY_RETRY_DELAY"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"2.0"})}),(0,r.jsx)(n.td,{children:"Delay between retries in seconds."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_VERSION"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"latest"})}),(0,r.jsx)(n.td,{children:"Langflow Docker image version."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LOG_FORMAT"})}),(0,r.jsx)(n.td,{children:"Disabled"}),(0,r.jsxs)(n.td,{children:["Set to ",(0,r.jsx)(n.code,{children:"json"})," to enabled JSON-formatted log output."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LOG_LEVEL"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"INFO"})}),(0,r.jsx)(n.td,{children:"Logging level (DEBUG, INFO, WARNING, ERROR)."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"MAX_WORKERS"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"1"})}),(0,r.jsx)(n.td,{children:"Maximum number of workers for document processing."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENRAG_VERSION"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"latest"})}),(0,r.jsx)(n.td,{children:"OpenRAG Docker image version."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"SERVICE_NAME"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"openrag"})}),(0,r.jsx)(n.td,{children:"Service name for logging."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"SESSION_SECRET"})}),(0,r.jsx)(n.td,{children:"Automatically generated"}),(0,r.jsx)(n.td,{children:"Session management."})]})]})]}),"\n",(0,r.jsx)(n.h2,{id:"langflow-runtime-overrides",children:"Langflow runtime overrides"}),"\n",(0,r.jsxs)(n.p,{children:["You can modify ",(0,r.jsx)(n.a,{href:"/agents",children:"flow"})," settings at runtime without permanently changing the flow's configuration."]}),"\n",(0,r.jsxs)(n.p,{children:["Runtime overrides are implemented through ",(0,r.jsx)(n.em,{children:"tweaks"}),", which are one-time parameter modifications that are passed to specific Langflow components during flow execution."]}),"\n",(0,r.jsxs)(n.p,{children:["For more information on tweaks, see the Langflow documentation on ",(0,r.jsx)(n.a,{href:"https://docs.langflow.org/concepts-publish#input-schema",children:"Input schema (tweaks)"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"default-values-and-fallbacks",children:"Default values and fallbacks"}),"\n",(0,r.jsx)(n.p,{children:"If a variable isn't set by environment variables or a configuration file, OpenRAG can use a default value if one is defined in the codebase.\nDefault values can be found in the OpenRAG repository:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:["OpenRAG configuration: ",(0,r.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/src/config/config_manager.py",children:(0,r.jsx)(n.code,{children:"config_manager.py"})})]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:["System configuration: ",(0,r.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/src/config/settings.py",children:(0,r.jsx)(n.code,{children:"settings.py"})})]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:["Logging configuration: ",(0,r.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/src/utils/logging_config.py",children:(0,r.jsx)(n.code,{children:"logging_config.py"})})]}),"\n"]}),"\n"]})]})}function a(e={}){const{wrapper:n}={...(0,d.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(h,{...e})}):h(e)}}}]); \ No newline at end of file +"use strict";(self.webpackChunkopenrag_docs=self.webpackChunkopenrag_docs||[]).push([[9026],{9196:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>c,contentTitle:()=>t,default:()=>a,frontMatter:()=>l,metadata:()=>i,toc:()=>o});const i=JSON.parse('{"id":"reference/configuration","title":"Environment variables","description":"OpenRAG recognizes environment variables from the following sources:","source":"@site/docs/reference/configuration.mdx","sourceDirName":"reference","slug":"/reference/configuration","permalink":"/reference/configuration","draft":false,"unlisted":false,"editUrl":"https://github.com/openrag/openrag/tree/main/docs/docs/reference/configuration.mdx","tags":[],"version":"current","frontMatter":{"title":"Environment variables","slug":"/reference/configuration"},"sidebar":"tutorialSidebar","previous":{"title":"Chat","permalink":"/chat"},"next":{"title":"Troubleshoot OpenRAG","permalink":"/support/troubleshoot"}}');var r=s(4848),d=s(8453);s(1610),s(1470),s(9365);const l={title:"Environment variables",slug:"/reference/configuration"},t=void 0,c={},o=[{value:"Configure environment variables",id:"configure-environment-variables",level:2},{value:"Set environment variables",id:"set-environment-variables",level:3},{value:"Supported environment variables",id:"supported-environment-variables",level:2},{value:"AI provider settings",id:"ai-provider-settings",level:3},{value:"Document processing",id:"document-processing",level:3},{value:"Langflow settings",id:"langflow-settings",level:3},{value:"OAuth provider settings",id:"oauth-provider-settings",level:3},{value:"OpenSearch settings",id:"opensearch-settings",level:3},{value:"System settings",id:"system-settings",level:3},{value:"Langflow runtime overrides",id:"langflow-runtime-overrides",level:2},{value:"Default values and fallbacks",id:"default-values-and-fallbacks",level:2}];function h(e){const n={a:"a",code:"code",em:"em",h2:"h2",h3:"h3",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,d.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.p,{children:"OpenRAG recognizes environment variables from the following sources:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"#configure-environment-variables",children:"Environment variables"}),": Values set in the ",(0,r.jsx)(n.code,{children:".env"})," file."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"#langflow-runtime-overrides",children:"Langflow runtime overrides"}),": Langflow components can set environment variables at runtime."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"#default-values-and-fallbacks",children:"Default or fallback values"}),": These values are default or fallback values if OpenRAG doesn't find a value."]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"configure-environment-variables",children:"Configure environment variables"}),"\n",(0,r.jsxs)(n.p,{children:["Environment variables are set in a ",(0,r.jsx)(n.code,{children:".env"})," file in the root of your OpenRAG project directory."]}),"\n",(0,r.jsxs)(n.p,{children:["For an example ",(0,r.jsx)(n.code,{children:".env"})," file, see ",(0,r.jsxs)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/.env.example",children:[(0,r.jsx)(n.code,{children:".env.example"})," in the OpenRAG repository"]}),"."]}),"\n",(0,r.jsxs)(n.p,{children:["The Docker Compose files are populated with values from your ",(0,r.jsx)(n.code,{children:".env"}),", so you don't need to edit the Docker Compose files manually."]}),"\n",(0,r.jsx)(n.p,{children:"Environment variables always take precedence over other variables."}),"\n",(0,r.jsx)(n.h3,{id:"set-environment-variables",children:"Set environment variables"}),"\n",(0,r.jsxs)(n.p,{children:["After you start OpenRAG, you must ",(0,r.jsx)(n.a,{href:"/install#tui-container-management",children:"stop and restart OpenRAG containers"})," to apply any changes you make to the ",(0,r.jsx)(n.code,{children:".env"})," file."]}),"\n",(0,r.jsx)(n.p,{children:"To set mutable environment variables, do the following:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:"Stop OpenRAG with the TUI or Docker Compose."}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:["Set the values in the ",(0,r.jsx)(n.code,{children:".env"})," file:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"LOG_LEVEL=DEBUG\nLOG_FORMAT=json\nSERVICE_NAME=openrag-dev\n"})}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:"Start OpenRAG with the TUI or Docker Compose."}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:["Certain environment variables that you set during ",(0,r.jsx)(n.a,{href:"/install#application-onboarding",children:"application onboarding"}),", such as provider API keys and provider endpoints, require resetting the containers after modifying the ",(0,r.jsx)(n.code,{children:".env"})," file."]}),"\n",(0,r.jsxs)(n.p,{children:["To change immutable variables with TUI-managed containers, you must ",(0,r.jsx)(n.a,{href:"/install#reinstall",children:"reinstall OpenRAG"})," and either delete or modify the ",(0,r.jsx)(n.code,{children:".env"})," file before you repeat the setup and onboarding process in the TUI."]}),"\n",(0,r.jsx)(n.p,{children:"To change immutable variables with self-managed containers, do the following:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:"Stop OpenRAG with Docker Compose."}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:"Remove the containers:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker-compose down\n"})}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:["Update the values in your ",(0,r.jsx)(n.code,{children:".env"})," file."]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:"Start OpenRAG with Docker Compose:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker-compose up -d\n"})}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:["Repeat ",(0,r.jsx)(n.a,{href:"/install#application-onboarding",children:"application onboarding"}),". The values in your ",(0,r.jsx)(n.code,{children:".env"})," file are automatically populated."]}),"\n"]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"supported-environment-variables",children:"Supported environment variables"}),"\n",(0,r.jsx)(n.p,{children:"All OpenRAG configuration can be controlled through environment variables."}),"\n",(0,r.jsx)(n.h3,{id:"ai-provider-settings",children:"AI provider settings"}),"\n",(0,r.jsxs)(n.p,{children:["Configure which models and providers OpenRAG uses to generate text and embeddings.\nThese are initially set during ",(0,r.jsx)(n.a,{href:"/install#application-onboarding",children:"application onboarding"}),".\nSome values are immutable and can only be changed by recreating the OpenRAG containers, as explained in ",(0,r.jsx)(n.a,{href:"#set-environment-variables",children:"Set environment variables"}),"."]}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Variable"}),(0,r.jsx)(n.th,{children:"Default"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"EMBEDDING_MODEL"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"text-embedding-3-small"})}),(0,r.jsx)(n.td,{children:"Embedding model for generating vector embeddings for documents in the knowledge base and similarity search queries. Can be changed after application onboarding. Accepts one or more models."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LLM_MODEL"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"gpt-4o-mini"})}),(0,r.jsxs)(n.td,{children:["Language model for language processing and text generation in the ",(0,r.jsx)(n.strong,{children:"Chat"})," feature."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"MODEL_PROVIDER"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"openai"})}),(0,r.jsx)(n.td,{children:"Model provider, such as OpenAI or IBM watsonx.ai."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENAI_API_KEY"})}),(0,r.jsx)(n.td,{children:"Not set"}),(0,r.jsxs)(n.td,{children:["Optional OpenAI API key for the default model. For other providers, use ",(0,r.jsx)(n.code,{children:"PROVIDER_API_KEY"}),"."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"PROVIDER_API_KEY"})}),(0,r.jsx)(n.td,{children:"Not set"}),(0,r.jsx)(n.td,{children:"API key for the model provider."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"PROVIDER_ENDPOINT"})}),(0,r.jsx)(n.td,{children:"Not set"}),(0,r.jsx)(n.td,{children:"Custom provider endpoint for the IBM and Ollama model providers. Leave unset for other model providers."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"PROVIDER_PROJECT_ID"})}),(0,r.jsx)(n.td,{children:"Not set"}),(0,r.jsx)(n.td,{children:"Project ID for the IBM watsonx.ai model provider only. Leave unset for other model providers."})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"document-processing",children:"Document processing"}),"\n",(0,r.jsxs)(n.p,{children:["Control how OpenRAG ",(0,r.jsx)(n.a,{href:"/ingestion",children:"processes and ingests documents"})," into your knowledge base."]}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Variable"}),(0,r.jsx)(n.th,{children:"Default"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"CHUNK_OVERLAP"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"200"})}),(0,r.jsx)(n.td,{children:"Overlap between chunks."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"CHUNK_SIZE"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"1000"})}),(0,r.jsx)(n.td,{children:"Text chunk size for document processing."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"DISABLE_INGEST_WITH_LANGFLOW"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"false"})}),(0,r.jsx)(n.td,{children:"Disable Langflow ingestion pipeline."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"DOCLING_OCR_ENGINE"})}),(0,r.jsx)(n.td,{children:"Set by OS"}),(0,r.jsxs)(n.td,{children:["OCR engine for document processing. For macOS, ",(0,r.jsx)(n.code,{children:"ocrmac"}),". For any other OS, ",(0,r.jsx)(n.code,{children:"easyocr"}),"."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OCR_ENABLED"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"false"})}),(0,r.jsx)(n.td,{children:"Enable OCR for image processing."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENRAG_DOCUMENTS_PATHS"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"./openrag-documents"})}),(0,r.jsx)(n.td,{children:"Document paths for ingestion."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"PICTURE_DESCRIPTIONS_ENABLED"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"false"})}),(0,r.jsx)(n.td,{children:"Enable picture descriptions."})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"langflow-settings",children:"Langflow settings"}),"\n",(0,r.jsx)(n.p,{children:"Configure Langflow authentication."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Variable"}),(0,r.jsx)(n.th,{children:"Default"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_AUTO_LOGIN"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"False"})}),(0,r.jsx)(n.td,{children:"Enable auto-login for Langflow."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_CHAT_FLOW_ID"})}),(0,r.jsx)(n.td,{children:"Built-in flow ID"}),(0,r.jsxs)(n.td,{children:["This value is automatically set to the ID of the chat ",(0,r.jsx)(n.a,{href:"/agents",children:"flow"}),". The default value is found in ",(0,r.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/.env.example",children:(0,r.jsx)(n.code,{children:".env.example"})}),". Only change this value if you explicitly don't want to use this built-in flow."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_ENABLE_SUPERUSER_CLI"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"False"})}),(0,r.jsx)(n.td,{children:"Enable superuser privileges for Langflow CLI commands."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_INGEST_FLOW_ID"})}),(0,r.jsx)(n.td,{children:"Built-in flow ID"}),(0,r.jsxs)(n.td,{children:["This value is automatically set to the ID of the ingestion ",(0,r.jsx)(n.a,{href:"/agents",children:"flow"}),". The default value is found in ",(0,r.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/.env.example",children:(0,r.jsx)(n.code,{children:".env.example"})}),". Only change this value if you explicitly don't want to use this built-in flow."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_KEY"})}),(0,r.jsx)(n.td,{children:"Automatically generated"}),(0,r.jsx)(n.td,{children:"Explicit Langflow API key."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_NEW_USER_IS_ACTIVE"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"False"})}),(0,r.jsx)(n.td,{children:"Whether new Langflow users are active by default."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_PUBLIC_URL"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"http://localhost:7860"})}),(0,r.jsx)(n.td,{children:"Public URL for the Langflow instance."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_SECRET_KEY"})}),(0,r.jsx)(n.td,{children:"Not set"}),(0,r.jsx)(n.td,{children:"Secret key for Langflow internal operations."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_SUPERUSER"})}),(0,r.jsx)(n.td,{children:"None, must be explicitly set"}),(0,r.jsx)(n.td,{children:"Langflow admin username. Required."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_SUPERUSER_PASSWORD"})}),(0,r.jsx)(n.td,{children:"None, must be explicitly set"}),(0,r.jsx)(n.td,{children:"Langflow admin password. Required."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_URL"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"http://localhost:7860"})}),(0,r.jsx)(n.td,{children:"URL for the Langflow instance."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"NUDGES_FLOW_ID"})}),(0,r.jsx)(n.td,{children:"Built-in flow ID"}),(0,r.jsxs)(n.td,{children:["This value is automatically set to the ID of the nudges ",(0,r.jsx)(n.a,{href:"/agents",children:"flow"}),". The default value is found in ",(0,r.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/.env.example",children:(0,r.jsx)(n.code,{children:".env.example"})}),". Only change this value if you explicitly don't want to use this built-in flow."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"SYSTEM_PROMPT"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context."})}),(0,r.jsxs)(n.td,{children:["System prompt instructions for the agent driving the ",(0,r.jsx)(n.strong,{children:"Chat"})," flow."]})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"oauth-provider-settings",children:"OAuth provider settings"}),"\n",(0,r.jsx)(n.p,{children:"Configure OAuth providers and external service integrations."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Variable"}),(0,r.jsx)(n.th,{children:"Default"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"AWS_ACCESS_KEY_ID"})," / ",(0,r.jsx)(n.code,{children:"AWS_SECRET_ACCESS_KEY"})]}),(0,r.jsx)(n.td,{children:"-"}),(0,r.jsx)(n.td,{children:"AWS integrations."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"GOOGLE_OAUTH_CLIENT_ID"})," / ",(0,r.jsx)(n.code,{children:"GOOGLE_OAUTH_CLIENT_SECRET"})]}),(0,r.jsx)(n.td,{children:"-"}),(0,r.jsx)(n.td,{children:"Google OAuth authentication."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"MICROSOFT_GRAPH_OAUTH_CLIENT_ID"})," / ",(0,r.jsx)(n.code,{children:"MICROSOFT_GRAPH_OAUTH_CLIENT_SECRET"})]}),(0,r.jsx)(n.td,{children:"-"}),(0,r.jsx)(n.td,{children:"Microsoft OAuth."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"WEBHOOK_BASE_URL"})}),(0,r.jsx)(n.td,{children:"-"}),(0,r.jsx)(n.td,{children:"Base URL for webhook endpoints."})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"opensearch-settings",children:"OpenSearch settings"}),"\n",(0,r.jsx)(n.p,{children:"Configure OpenSearch database authentication."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Variable"}),(0,r.jsx)(n.th,{children:"Default"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENSEARCH_HOST"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"localhost"})}),(0,r.jsx)(n.td,{children:"OpenSearch host."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENSEARCH_PASSWORD"})}),(0,r.jsx)(n.td,{children:"-"}),(0,r.jsx)(n.td,{children:"Password for OpenSearch admin user. Required."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENSEARCH_PORT"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"9200"})}),(0,r.jsx)(n.td,{children:"OpenSearch port."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENSEARCH_USERNAME"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"admin"})}),(0,r.jsx)(n.td,{children:"OpenSearch username."})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"system-settings",children:"System settings"}),"\n",(0,r.jsx)(n.p,{children:"Configure general system components, session management, and logging."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Variable"}),(0,r.jsx)(n.th,{children:"Default"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_KEY_RETRIES"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"15"})}),(0,r.jsx)(n.td,{children:"Number of retries for Langflow key generation."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_KEY_RETRY_DELAY"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"2.0"})}),(0,r.jsx)(n.td,{children:"Delay between retries in seconds."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LANGFLOW_VERSION"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENRAG_VERSION"})}),(0,r.jsxs)(n.td,{children:["Langflow Docker image version. By default, OpenRAG uses the ",(0,r.jsx)(n.code,{children:"OPENRAG_VERSION"})," for the Langflow Docker image version."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LOG_FORMAT"})}),(0,r.jsx)(n.td,{children:"Disabled"}),(0,r.jsxs)(n.td,{children:["Set to ",(0,r.jsx)(n.code,{children:"json"})," to enabled JSON-formatted log output."]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LOG_LEVEL"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"INFO"})}),(0,r.jsx)(n.td,{children:"Logging level (DEBUG, INFO, WARNING, ERROR)."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"MAX_WORKERS"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"1"})}),(0,r.jsx)(n.td,{children:"Maximum number of workers for document processing."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"OPENRAG_VERSION"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"latest"})}),(0,r.jsxs)(n.td,{children:["The version of the OpenRAG Docker images to run. For more information, see ",(0,r.jsx)(n.a,{href:"/install#upgrade",children:"Upgrade OpenRAG"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"SERVICE_NAME"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"openrag"})}),(0,r.jsx)(n.td,{children:"Service name for logging."})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"SESSION_SECRET"})}),(0,r.jsx)(n.td,{children:"Automatically generated"}),(0,r.jsx)(n.td,{children:"Session management."})]})]})]}),"\n",(0,r.jsx)(n.h2,{id:"langflow-runtime-overrides",children:"Langflow runtime overrides"}),"\n",(0,r.jsxs)(n.p,{children:["You can modify ",(0,r.jsx)(n.a,{href:"/agents",children:"flow"})," settings at runtime without permanently changing the flow's configuration."]}),"\n",(0,r.jsxs)(n.p,{children:["Runtime overrides are implemented through ",(0,r.jsx)(n.em,{children:"tweaks"}),", which are one-time parameter modifications that are passed to specific Langflow components during flow execution."]}),"\n",(0,r.jsxs)(n.p,{children:["For more information on tweaks, see the Langflow documentation on ",(0,r.jsx)(n.a,{href:"https://docs.langflow.org/concepts-publish#input-schema",children:"Input schema (tweaks)"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"default-values-and-fallbacks",children:"Default values and fallbacks"}),"\n",(0,r.jsx)(n.p,{children:"If a variable isn't set by environment variables or a configuration file, OpenRAG can use a default value if one is defined in the codebase.\nDefault values can be found in the OpenRAG repository:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:["OpenRAG configuration: ",(0,r.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/src/config/config_manager.py",children:(0,r.jsx)(n.code,{children:"config_manager.py"})})]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:["System configuration: ",(0,r.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/src/config/settings.py",children:(0,r.jsx)(n.code,{children:"settings.py"})})]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:["Logging configuration: ",(0,r.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/src/utils/logging_config.py",children:(0,r.jsx)(n.code,{children:"logging_config.py"})})]}),"\n"]}),"\n"]})]})}function a(e={}){const{wrapper:n}={...(0,d.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(h,{...e})}):h(e)}}}]); \ No newline at end of file diff --git a/assets/js/d0314b07.788dda5b.js b/assets/js/d0314b07.788dda5b.js deleted file mode 100644 index 7d01dfde..00000000 --- a/assets/js/d0314b07.788dda5b.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkopenrag_docs=self.webpackChunkopenrag_docs||[]).push([[5750],{3656:(e,n,s)=>{s.d(n,{Ay:()=>p,RM:()=>d});var r=s(4848),i=s(8453),t=s(1610),o=s(1470),l=s(9365);function a(e){const n={a:"a",code:"code",li:"li",ol:"ol",p:"p",strong:"strong",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.p,{children:"Using Ollama for your OpenRAG language model provider offers greater flexibility and configuration, but can also be overwhelming to start.\nThese recommendations are a reasonable starting point for users with at least one GPU and experience running LLMs locally."}),"\n",(0,r.jsxs)(n.p,{children:["For best performance, OpenRAG recommends OpenAI's ",(0,r.jsx)(n.code,{children:"gpt-oss:20b"})," language model. However, this model uses 16GB of RAM, so consider using Ollama Cloud or running Ollama on a remote machine."]}),"\n",(0,r.jsxs)(n.p,{children:["For generating embeddings, OpenRAG recommends the ",(0,r.jsx)(n.a,{href:"https://ollama.com/library/nomic-embed-text",children:(0,r.jsx)(n.code,{children:"nomic-embed-text"})})," embedding model, which provides high-quality embeddings optimized for retrieval tasks."]}),"\n",(0,r.jsxs)(n.p,{children:["To run models in ",(0,r.jsx)(n.a,{href:"https://docs.ollama.com/cloud",children:(0,r.jsx)(n.strong,{children:"Ollama Cloud"})}),", follow these steps:"]}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Sign in to Ollama Cloud.\nIn a terminal, enter ",(0,r.jsx)(n.code,{children:"ollama signin"})," to connect your local environment with Ollama Cloud."]}),"\n",(0,r.jsxs)(n.li,{children:["To run the model, in Ollama, select the ",(0,r.jsx)(n.code,{children:"gpt-oss:20b-cloud"})," model, or run ",(0,r.jsx)(n.code,{children:"ollama run gpt-oss:20b-cloud"})," in a terminal.\nOllama Cloud models are run at the same URL as your local Ollama server at ",(0,r.jsx)(n.code,{children:"http://localhost:11434"}),", and automatically offloaded to Ollama's cloud service."]}),"\n",(0,r.jsxs)(n.li,{children:["Connect OpenRAG to the same local Ollama server as you would for local models in onboarding, using the default address of ",(0,r.jsx)(n.code,{children:"http://localhost:11434"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["In the ",(0,r.jsx)(n.strong,{children:"Language model"})," field, select the ",(0,r.jsx)(n.code,{children:"gpt-oss:20b-cloud"})," model."]}),"\n"]}),"\n",(0,r.jsx)("br",{}),"\n",(0,r.jsxs)(n.p,{children:["To run models on a ",(0,r.jsx)(n.strong,{children:"remote Ollama server"}),", follow these steps:"]}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsx)(n.li,{children:"Ensure your remote Ollama server is accessible from your OpenRAG instance."}),"\n",(0,r.jsxs)(n.li,{children:["In the ",(0,r.jsx)(n.strong,{children:"Ollama Base URL"})," field, enter your remote Ollama server's base URL, such as ",(0,r.jsx)(n.code,{children:"http://your-remote-server:11434"}),".\nOpenRAG connects to the remote Ollama server and populates the lists with the server's available models."]}),"\n",(0,r.jsxs)(n.li,{children:["Select your ",(0,r.jsx)(n.strong,{children:"Embedding model"})," and ",(0,r.jsx)(n.strong,{children:"Language model"})," from the available options."]}),"\n"]})]})}function c(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(a,{...e})}):a(e)}const d=[{value:"Application onboarding",id:"application-onboarding",level:2}];function h(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",li:"li",ol:"ol",p:"p",strong:"strong",...(0,i.R)(),...e.components},{Details:s}=n;return s||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.h2,{id:"application-onboarding",children:"Application onboarding"}),"\n",(0,r.jsx)(n.p,{children:"The first time you start OpenRAG, regardless of how you installed it, you must complete application onboarding."}),"\n",(0,r.jsxs)(n.p,{children:["Some of these variables, such as the embedding models, can be changed seamlessly after onboarding.\nOthers are immutable and require you to destroy and recreate the OpenRAG containers.\nFor more information, see ",(0,r.jsx)(n.a,{href:"/reference/configuration",children:"Environment variables"}),"."]}),"\n",(0,r.jsx)(n.p,{children:"You can use different providers for your language model and embedding model, such as Anthropic for the language model and OpenAI for the embeddings model.\nAdditionally, you can set multiple embedding models."}),"\n",(0,r.jsx)(n.p,{children:"You only need to complete onboarding for your preferred providers."}),"\n",(0,r.jsxs)(o.A,{groupId:"Provider",children:[(0,r.jsxs)(l.A,{value:"Anthropic",label:"Anthropic",default:!0,children:[(0,r.jsx)(n.admonition,{type:"info",children:(0,r.jsx)(n.p,{children:"Anthropic doesn't provide embedding models. If you select Anthropic for your language model, you must select a different provider for embeddings."})}),(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Enable ",(0,r.jsx)(n.strong,{children:"Use environment Anthropic API key"})," to automatically use your key from the ",(0,r.jsx)(n.code,{children:".env"})," file.\nAlternatively, paste an Anthropic API key into the field."]}),"\n",(0,r.jsxs)(n.li,{children:["Under ",(0,r.jsx)(n.strong,{children:"Advanced settings"}),", select your ",(0,r.jsx)(n.strong,{children:"Language Model"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Click ",(0,r.jsx)(n.strong,{children:"Complete"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["In the second onboarding panel, select a provider for embeddings and select your ",(0,r.jsx)(n.strong,{children:"Embedding Model"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["To complete the onboarding tasks, click ",(0,r.jsx)(n.strong,{children:"What is OpenRAG"}),", and then click ",(0,r.jsx)(n.strong,{children:"Add a Document"}),".\nAlternatively, click ",(0,r.jsx)(t.A,{name:"ArrowRight","aria-hidden":"true"})," ",(0,r.jsx)(n.strong,{children:"Skip overview"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Continue with the ",(0,r.jsx)(n.a,{href:"/quickstart",children:"Quickstart"}),"."]}),"\n"]})]}),(0,r.jsx)(l.A,{value:"OpenAI",label:"OpenAI",children:(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Enable ",(0,r.jsx)(n.strong,{children:"Get API key from environment variable"})," to automatically enter your key from the TUI-generated ",(0,r.jsx)(n.code,{children:".env"})," file.\nAlternatively, paste an OpenAI API key into the field."]}),"\n",(0,r.jsxs)(n.li,{children:["Under ",(0,r.jsx)(n.strong,{children:"Advanced settings"}),", select your ",(0,r.jsx)(n.strong,{children:"Language Model"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Click ",(0,r.jsx)(n.strong,{children:"Complete"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["In the second onboarding panel, select a provider for embeddings and select your ",(0,r.jsx)(n.strong,{children:"Embedding Model"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["To complete the onboarding tasks, click ",(0,r.jsx)(n.strong,{children:"What is OpenRAG"}),", and then click ",(0,r.jsx)(n.strong,{children:"Add a Document"}),".\nAlternatively, click ",(0,r.jsx)(t.A,{name:"ArrowRight","aria-hidden":"true"})," ",(0,r.jsx)(n.strong,{children:"Skip overview"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Continue with the ",(0,r.jsx)(n.a,{href:"/quickstart",children:"Quickstart"}),"."]}),"\n"]})}),(0,r.jsx)(l.A,{value:"IBM watsonx.ai",label:"IBM watsonx.ai",children:(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Complete the fields for ",(0,r.jsx)(n.strong,{children:"watsonx.ai API Endpoint"}),", ",(0,r.jsx)(n.strong,{children:"IBM Project ID"}),", and ",(0,r.jsx)(n.strong,{children:"IBM API key"}),".\nThese values are found in your IBM watsonx deployment."]}),"\n",(0,r.jsxs)(n.li,{children:["Under ",(0,r.jsx)(n.strong,{children:"Advanced settings"}),", select your ",(0,r.jsx)(n.strong,{children:"Language Model"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Click ",(0,r.jsx)(n.strong,{children:"Complete"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["In the second onboarding panel, select a provider for embeddings and select your ",(0,r.jsx)(n.strong,{children:"Embedding Model"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["To complete the onboarding tasks, click ",(0,r.jsx)(n.strong,{children:"What is OpenRAG"}),", and then click ",(0,r.jsx)(n.strong,{children:"Add a Document"}),".\nAlternatively, click ",(0,r.jsx)(t.A,{name:"ArrowRight","aria-hidden":"true"})," ",(0,r.jsx)(n.strong,{children:"Skip overview"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Continue with the ",(0,r.jsx)(n.a,{href:"/quickstart",children:"Quickstart"}),"."]}),"\n"]})}),(0,r.jsxs)(l.A,{value:"Ollama",label:"Ollama",children:[(0,r.jsx)(n.admonition,{type:"info",children:(0,r.jsxs)(n.p,{children:["Ollama isn't installed with OpenRAG. To install Ollama, see the ",(0,r.jsx)(n.a,{href:"https://docs.ollama.com/",children:"Ollama documentation"}),"."]})}),(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["To connect to an Ollama server running on your local machine, enter your Ollama server's base URL address.\nThe default Ollama server address is ",(0,r.jsx)(n.code,{children:"http://localhost:11434"}),".\nOpenRAG connects to the Ollama server and populates the model lists with the server's available models."]}),"\n",(0,r.jsxs)(n.li,{children:["Select the ",(0,r.jsx)(n.strong,{children:"Embedding Model"})," and ",(0,r.jsx)(n.strong,{children:"Language Model"})," your Ollama server is running.","\n",(0,r.jsxs)(s,{closed:!0,children:[(0,r.jsx)("summary",{children:"Ollama model selection and external server configuration"}),(0,r.jsx)(c,{})]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["Click ",(0,r.jsx)(n.strong,{children:"Complete"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["To complete the onboarding tasks, click ",(0,r.jsx)(n.strong,{children:"What is OpenRAG"}),", and then click ",(0,r.jsx)(n.strong,{children:"Add a Document"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Continue with the ",(0,r.jsx)(n.a,{href:"/quickstart",children:"Quickstart"}),"."]}),"\n"]})]})]})]})}function p(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(h,{...e})}):h(e)}},3862:(e,n,s)=>{s.d(n,{Ay:()=>l,RM:()=>t});var r=s(4848),i=s(8453);const t=[];function o(e){const n={a:"a",admonition:"admonition",code:"code",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install",children:"Install WSL"})," with the Ubuntu distribution using WSL 2:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-powershell",children:"wsl --install -d Ubuntu\n"})}),"\n",(0,r.jsxs)(n.p,{children:["For new installations, the ",(0,r.jsx)(n.code,{children:"wsl --install"})," command uses WSL 2 and Ubuntu by default."]}),"\n",(0,r.jsxs)(n.p,{children:["For existing WSL installations, you can ",(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install#change-the-default-linux-distribution-installed",children:"change the distribution"})," and ",(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install#upgrade-version-from-wsl-1-to-wsl-2",children:"check the WSL version"}),"."]}),"\n",(0,r.jsx)(n.admonition,{title:"Known limitation",type:"warning",children:(0,r.jsx)(n.p,{children:"OpenRAG isn't compatible with nested virtualization, which can cause networking issues.\nDon't install OpenRAG on a WSL distribution that is installed inside a Windows VM.\nInstead, install OpenRAG on your base OS or a non-nested Linux VM."})}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install#ways-to-run-multiple-linux-distributions-with-wsl",children:"Start your WSL Ubuntu distribution"})," if it doesn't start automatically."]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-your-linux-username-and-password",children:"Set up a username and password for your WSL distribution"}),"."]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers",children:"Install Docker Desktop for Windows with WSL 2"}),". When you reach the Docker Desktop ",(0,r.jsx)(n.strong,{children:"WSL integration"})," settings, make sure your Ubuntu distribution is enabled, and then click ",(0,r.jsx)(n.strong,{children:"Apply & Restart"})," to enable Docker support in WSL."]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:"Install and run OpenRAG from within your WSL Ubuntu distribution."}),"\n"]}),"\n"]}),"\n",(0,r.jsx)("br",{}),"\n",(0,r.jsxs)(n.p,{children:["If you encounter issues with port forwarding or the Windows Firewall, you might need to adjust the ",(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall",children:"Hyper-V firewall settings"})," to allow communication between your WSL distribution and the Windows host. For more troubleshooting advice for networking issues, see ",(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#common-issues",children:"Troubleshooting WSL common issues"}),"."]})]})}function l(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(o,{...e})}):o(e)}},4398:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>p,contentTitle:()=>h,default:()=>j,frontMatter:()=>d,metadata:()=>r,toc:()=>u});const r=JSON.parse('{"id":"get-started/install","title":"Install OpenRAG with TUI","description":"Install OpenRAG and then run the OpenRAG Terminal User Interface(TUI) to start your OpenRAG deployment with a guided setup process.","source":"@site/docs/get-started/install.mdx","sourceDirName":"get-started","slug":"/install","permalink":"/install","draft":false,"unlisted":false,"editUrl":"https://github.com/openrag/openrag/tree/main/docs/docs/get-started/install.mdx","tags":[],"version":"current","frontMatter":{"title":"Install OpenRAG with TUI","slug":"/install"},"sidebar":"tutorialSidebar","previous":{"title":"Quickstart","permalink":"/quickstart"},"next":{"title":"Install OpenRAG containers","permalink":"/docker"}}');var i=s(4848),t=s(8453),o=s(1470),l=s(9365),a=s(3656),c=s(3862);const d={title:"Install OpenRAG with TUI",slug:"/install"},h=void 0,p={},u=[{value:"Prerequisites",id:"prerequisites",level:2},...c.RM,{value:"Install OpenRAG",id:"install",level:2},{value:"Set up OpenRAG with the TUI",id:"setup",level:2},...a.RM,{value:"Exit the OpenRAG TUI",id:"exit-the-openrag-tui",level:2},{value:"Manage OpenRAG containers with the TUI",id:"tui-container-management",level:2},{value:"Start all services",id:"start-all-services",level:3},{value:"Status",id:"status",level:3},{value:"Native services status",id:"native-services-status",level:3},{value:"Upgrade OpenRAG",id:"upgrade",level:2},{value:"Upgrade OpenRAG python package",id:"upgrade-openrag-python-package",level:3},{value:"Upgrade OpenRAG containers with the TUI",id:"upgrade-openrag-containers-with-the-tui",level:3},{value:"Diagnostics",id:"diagnostics",level:2},{value:"Reinstall OpenRAG",id:"reinstall",level:2}];function x(e){const n={a:"a",admonition:"admonition",code:"code",em:"em",h2:"h2",h3:"h3",img:"img",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components},{Details:r}=n;return r||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,i.jsxs)(i.Fragment,{children:[(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.a,{href:"#install",children:"Install OpenRAG"})," and then run the ",(0,i.jsx)(n.a,{href:"#setup",children:"OpenRAG Terminal User Interface(TUI)"})," to start your OpenRAG deployment with a guided setup process."]}),"\n",(0,i.jsx)(n.p,{children:"The OpenRAG Terminal User Interface (TUI) allows you to set up, configure, and monitor your OpenRAG deployment directly from the terminal."}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.img,{alt:"OpenRAG TUI Interface",src:s(5689).A+"",width:"1995",height:"1099"})}),"\n",(0,i.jsxs)(n.p,{children:["Instead of starting OpenRAG using Docker commands and manually editing values in the ",(0,i.jsx)(n.code,{children:".env"})," file, the TUI walks you through the setup. It prompts for variables where required, creates a ",(0,i.jsx)(n.code,{children:".env"})," file for you, and then starts OpenRAG."]}),"\n",(0,i.jsx)(n.p,{children:"Once OpenRAG is running, use the TUI to monitor your application, control your containers, and retrieve logs."}),"\n",(0,i.jsxs)(n.p,{children:["If you prefer running Podman or Docker containers and manually editing ",(0,i.jsx)(n.code,{children:".env"})," files, see ",(0,i.jsx)(n.a,{href:"/docker",children:"Install OpenRAG Containers"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["All OpenRAG installations require ",(0,i.jsx)(n.a,{href:"https://www.python.org/downloads/release/python-3100/",children:"Python"})," version 3.13 or later."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"If you aren't using the automatic installer script, install the following:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"https://docs.astral.sh/uv/getting-started/installation/",children:"uv"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"https://podman.io/docs/installation",children:"Podman"})," (recommended) or ",(0,i.jsx)(n.a,{href:"https://docs.docker.com/get-docker/",children:"Docker"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"https://docs.podman.io/en/latest/markdown/podman-compose.1.html",children:(0,i.jsx)(n.code,{children:"podman-compose"})})," or ",(0,i.jsx)(n.a,{href:"https://docs.docker.com/compose/install/",children:"Docker Compose"}),". To use Docker Compose with Podman, you must alias Docker Compose commands to Podman commands."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Microsoft Windows only: To run OpenRAG on Windows, you must use the Windows Subsystem for Linux (WSL)."}),"\n",(0,i.jsxs)(r,{children:[(0,i.jsx)("summary",{children:"Install WSL for OpenRAG"}),(0,i.jsx)(c.Ay,{})]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Prepare model providers and credentials."}),"\n",(0,i.jsxs)(n.p,{children:["During ",(0,i.jsx)(n.a,{href:"#application-onboarding",children:"application onboarding"}),", you must select language model and embedding model providers.\nIf your chosen provider offers both types, you can use the same provider for both selections.\nIf your provider offers only one type, such as Anthropic, you must select two providers."]}),"\n",(0,i.jsx)(n.p,{children:"Gather the credentials and connection details for your chosen model providers before starting onboarding:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["OpenAI: Create an ",(0,i.jsx)(n.a,{href:"https://platform.openai.com/api-keys",children:"OpenAI API key"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:["Anthropic language models: Create an ",(0,i.jsx)(n.a,{href:"https://www.anthropic.com/docs/api/reference",children:"Anthropic API key"}),"."]}),"\n",(0,i.jsx)(n.li,{children:"IBM watsonx.ai: Get your watsonx.ai API endpoint, IBM project ID, and IBM API key from your watsonx deployment."}),"\n",(0,i.jsxs)(n.li,{children:["Ollama: Use the ",(0,i.jsx)(n.a,{href:"https://docs.ollama.com/",children:"Ollama documentation"})," to set up your Ollama instance locally, in the cloud, or on a remote server, and then get your Ollama server's base URL."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Optional: Install GPU support with an NVIDIA GPU, ",(0,i.jsx)(n.a,{href:"https://docs.nvidia.com/cuda/",children:"CUDA"})," support, and compatible NVIDIA drivers on the OpenRAG host machine. If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"install",children:"Install OpenRAG"}),"\n",(0,i.jsx)(n.p,{children:"Choose an installation method based on your needs:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"For new users, the automatic installer script detects and installs prerequisites and then runs OpenRAG."}),"\n",(0,i.jsxs)(n.li,{children:["For a quick test, use ",(0,i.jsx)(n.code,{children:"uvx"})," to run OpenRAG without creating a project or modifying files."]}),"\n",(0,i.jsxs)(n.li,{children:["Use ",(0,i.jsx)(n.code,{children:"uv add"})," to install OpenRAG as a managed dependency in a new or existing Python project."]}),"\n",(0,i.jsxs)(n.li,{children:["Use ",(0,i.jsx)(n.code,{children:"uv pip install"})," to install OpenRAG into an existing virtual environment."]}),"\n"]}),"\n",(0,i.jsxs)(o.A,{groupId:"Installation method",children:[(0,i.jsxs)(l.A,{value:"installer",label:"Automatic installer",default:!0,children:[(0,i.jsxs)(n.p,{children:["The script detects and installs uv, Docker/Podman, and Docker Compose prerequisites, then runs OpenRAG with ",(0,i.jsx)(n.code,{children:"uvx"}),"."]}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Create a directory to store the OpenRAG configuration files:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"mkdir openrag-workspace\ncd openrag-workspace\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Run the installer:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"curl -fsSL https://docs.openr.ag/files/run_openrag_with_prereqs.sh | bash\n"})}),"\n"]}),"\n"]}),(0,i.jsxs)(n.p,{children:["The TUI creates a ",(0,i.jsx)(n.code,{children:".env"})," file and docker-compose files in the current working directory."]})]}),(0,i.jsxs)(l.A,{value:"uvx",label:"Quick test with uvx",children:[(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"uvx"})," to quickly run OpenRAG without creating a project or modifying any files."]}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Create a directory to store the OpenRAG configuration files:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"mkdir openrag-workspace\ncd openrag-workspace\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Run OpenRAG:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uvx openrag\n"})}),"\n",(0,i.jsx)(n.p,{children:"To run a specific version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uvx --from openrag==0.1.30 openrag\n"})}),"\n"]}),"\n"]}),(0,i.jsxs)(n.p,{children:["The TUI creates a ",(0,i.jsx)(n.code,{children:".env"})," file and docker-compose files in the current working directory."]})]}),(0,i.jsxs)(l.A,{value:"uv-add",label:"Python project with uv add",children:[(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"uv add"})," to install OpenRAG as a dependency in your Python project. This adds OpenRAG to your ",(0,i.jsx)(n.code,{children:"pyproject.toml"})," and lockfile, making your installation reproducible and version-controlled."]}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Create a new project with a virtual environment:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv init YOUR_PROJECT_NAME\ncd YOUR_PROJECT_NAME\n"})}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"(venv)"})," prompt doesn't change, but ",(0,i.jsx)(n.code,{children:"uv"})," commands will automatically use the project's virtual environment."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Add OpenRAG to your project:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv add openrag\n"})}),"\n",(0,i.jsx)(n.p,{children:"To add a specific version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv add openrag==0.1.30\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Start the OpenRAG TUI:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv run openrag\n"})}),"\n"]}),"\n"]}),(0,i.jsxs)(r,{closed:!0,children:[(0,i.jsx)("summary",{children:"Install a local wheel"}),(0,i.jsx)(n.p,{children:"If you downloaded the OpenRAG wheel to your local machine, install it by specifying its path:"}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Add the wheel to your project:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv add PATH/TO/openrag-VERSION-py3-none-any.whl\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Replace ",(0,i.jsx)(n.code,{children:"PATH/TO/"})," and ",(0,i.jsx)(n.code,{children:"VERSION"})," with the path and version of your downloaded OpenRAG ",(0,i.jsx)(n.code,{children:".whl"})," file."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Run OpenRAG:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv run openrag\n"})}),"\n"]}),"\n"]})]})]}),(0,i.jsxs)(l.A,{value:"uv-pip",label:"Existing virtual environment with uv pip install",children:[(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"uv pip install"})," to install OpenRAG into an existing virtual environment that isn't managed by ",(0,i.jsx)(n.code,{children:"uv"}),"."]}),(0,i.jsx)(n.admonition,{type:"tip",children:(0,i.jsxs)(n.p,{children:["For new projects, ",(0,i.jsx)(n.code,{children:"uv add"})," is recommended as it manages dependencies in your project's lockfile."]})}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Activate your virtual environment."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Install OpenRAG:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv pip install openrag\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Run OpenRAG:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv run openrag\n"})}),"\n"]}),"\n"]})]})]}),"\n",(0,i.jsxs)(n.p,{children:["Continue with ",(0,i.jsx)(n.a,{href:"#setup",children:"Set up OpenRAG with the TUI"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["If you encounter errors during installation, see ",(0,i.jsx)(n.a,{href:"/support/troubleshoot",children:"Troubleshoot OpenRAG"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"setup",children:"Set up OpenRAG with the TUI"}),"\n",(0,i.jsxs)(n.p,{children:["The OpenRAG setup process creates a ",(0,i.jsx)(n.code,{children:".env"})," file at the root of your OpenRAG directory, and then starts OpenRAG.\nIf it detects a ",(0,i.jsx)(n.code,{children:".env"})," file in the OpenRAG root directory, it sources any variables from the ",(0,i.jsx)(n.code,{children:".env"})," file."]}),"\n",(0,i.jsxs)(n.p,{children:["The TUI offers two setup methods to populate the required values. ",(0,i.jsx)(n.strong,{children:"Basic Setup"})," can generate all minimum required values for OpenRAG. However, ",(0,i.jsx)(n.strong,{children:"Basic Setup"})," doesn't enable ",(0,i.jsx)(n.a,{href:"/knowledge#auth",children:"OAuth connectors for cloud storage"}),". If you want to use OAuth connectors to upload documents from cloud storage, select ",(0,i.jsx)(n.strong,{children:"Advanced Setup"}),".\nIf OpenRAG detects OAuth credentials, it recommends ",(0,i.jsx)(n.strong,{children:"Advanced Setup"}),"."]}),"\n",(0,i.jsxs)(o.A,{groupId:"Setup method",children:[(0,i.jsx)(l.A,{value:"Basic setup",label:"Basic setup",default:!0,children:(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To install OpenRAG with ",(0,i.jsx)(n.strong,{children:"Basic Setup"}),", click ",(0,i.jsx)(n.strong,{children:"Basic Setup"})," or press ",(0,i.jsx)("kbd",{children:"1"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Generate Passwords"})," to generate passwords for OpenSearch and Langflow."]}),"\n",(0,i.jsxs)(n.p,{children:["The OpenSearch password is required. The Langflow admin password is optional.\nIf no Langflow admin password is generated, Langflow runs in ",(0,i.jsx)(n.a,{href:"https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login",children:"autologin mode"})," with no password required."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Optional: Paste your OpenAI API key in the OpenAI API key field. You can also provide this during onboarding or choose a different model provider."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Save Configuration"}),".\nYour passwords are saved in the ",(0,i.jsx)(n.code,{children:".env"})," file used to start OpenRAG."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To start OpenRAG, click ",(0,i.jsx)(n.strong,{children:"Start All Services"}),".\nStartup pulls container images and runs them, so it can take some time.\nWhen startup is complete, the TUI displays the following:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"Services started successfully\nCommand completed successfully\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To start the Docling service, under ",(0,i.jsx)(n.strong,{children:"Native Services"}),", click ",(0,i.jsx)(n.strong,{children:"Start"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To open the OpenRAG application, navigate to the TUI main menu, and then click ",(0,i.jsx)(n.strong,{children:"Open App"}),".\nAlternatively, in your browser, navigate to ",(0,i.jsx)(n.code,{children:"localhost:3000"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Continue with ",(0,i.jsx)(n.a,{href:"#application-onboarding",children:"application onboarding"}),"."]}),"\n"]}),"\n"]})}),(0,i.jsx)(l.A,{value:"Advanced setup",label:"Advanced setup",children:(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To install OpenRAG with ",(0,i.jsx)(n.strong,{children:"Advanced Setup"}),", click ",(0,i.jsx)(n.strong,{children:"Advanced Setup"})," or press ",(0,i.jsx)("kbd",{children:"2"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Generate Passwords"})," to generate passwords for OpenSearch and Langflow."]}),"\n",(0,i.jsxs)(n.p,{children:["The OpenSearch password is required. The Langflow admin password is optional.\nIf no Langflow admin password is generated, Langflow runs in ",(0,i.jsx)(n.a,{href:"https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login",children:"autologin mode"})," with no password required."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Paste your OpenAI API key in the OpenAI API key field."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["If you want to upload documents from external storage, such as Google Drive, add the required OAuth credentials for the connectors that you want to use. These settings can be populated automatically if OpenRAG detects these credentials in a ",(0,i.jsx)(n.code,{children:".env"})," file in the OpenRAG installation directory."]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Amazon"}),": Provide your AWS Access Key ID and AWS Secret Access Key with access to your S3 instance. For more information, see the AWS documentation on ",(0,i.jsx)(n.a,{href:"https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-applications.html",children:"Configuring access to AWS applications"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Google"}),": Provide your Google OAuth Client ID and Google OAuth Client Secret. You can generate these in the ",(0,i.jsx)(n.a,{href:"https://console.cloud.google.com/apis/credentials",children:"Google Cloud Console"}),". For more information, see the ",(0,i.jsx)(n.a,{href:"https://developers.google.com/identity/protocols/oauth2",children:"Google OAuth client documentation"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Microsoft"}),": For the Microsoft OAuth Client ID and Microsoft OAuth Client Secret, provide ",(0,i.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/app-registration?view=odsp-graph-online",children:"Azure application registration credentials for SharePoint and OneDrive"}),". For more information, see the ",(0,i.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/graph-oauth",children:"Microsoft Graph OAuth client documentation"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["You can ",(0,i.jsx)(n.a,{href:"/ingestion#oauth-ingestion",children:"manage OAuth credentials"})," later, but it is recommended to configure them during initial set up."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"The OpenRAG TUI presents redirect URIs for your OAuth app.\nThese are the URLs your OAuth provider will redirect back to after user sign-in.\nRegister these redirect values with your OAuth provider as they are presented in the TUI."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Save Configuration"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To start OpenRAG, click ",(0,i.jsx)(n.strong,{children:"Start All Services"}),".\nStartup pulls container images and runs them, so it can take some time.\nWhen startup is complete, the TUI displays the following:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"Services started successfully\nCommand completed successfully\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To start the Docling service, under ",(0,i.jsx)(n.strong,{children:"Native Services"}),", click ",(0,i.jsx)(n.strong,{children:"Start"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To open the OpenRAG application, navigate to the TUI main menu, and then click ",(0,i.jsx)(n.strong,{children:"Open App"}),".\nAlternatively, in your browser, navigate to ",(0,i.jsx)(n.code,{children:"localhost:3000"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"If you enabled OAuth connectors, you must sign in to your OAuth provider before being redirected to your OpenRAG instance."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Two additional variables are available for ",(0,i.jsx)(n.strong,{children:"Advanced Setup"})," at this point.\nOnly change these variables if you have a non-default network configuration for your deployment, such as using a reverse proxy or custom domain."]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"LANGFLOW_PUBLIC_URL"}),": Sets the base address to access the Langflow web interface. This is where users interact with flows in a browser."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"WEBHOOK_BASE_URL"}),": Sets the base address of the OpenRAG OAuth connector endpoint.\nSupported webhook endpoints:"]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Amazon S3: Not applicable."}),"\n",(0,i.jsxs)(n.li,{children:["Google Drive: ",(0,i.jsx)(n.code,{children:"/connectors/google_drive/webhook"})]}),"\n",(0,i.jsxs)(n.li,{children:["OneDrive: ",(0,i.jsx)(n.code,{children:"/connectors/onedrive/webhook"})]}),"\n",(0,i.jsxs)(n.li,{children:["SharePoint: ",(0,i.jsx)(n.code,{children:"/connectors/sharepoint/webhook"})]}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Continue with ",(0,i.jsx)(n.a,{href:"#application-onboarding",children:"application onboarding"}),"."]}),"\n"]}),"\n"]})})]}),"\n",(0,i.jsx)(a.Ay,{}),"\n",(0,i.jsx)(n.h2,{id:"exit-the-openrag-tui",children:"Exit the OpenRAG TUI"}),"\n",(0,i.jsxs)(n.p,{children:["To exit the OpenRAG TUI, navigate to the main menu, and then press ",(0,i.jsx)("kbd",{children:"q"}),".\nThe OpenRAG containers continue to run until they are stopped.\nFor more information, see ",(0,i.jsx)(n.a,{href:"#tui-container-management",children:"Manage OpenRAG containers with the TUI "}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["To relaunch the TUI, run ",(0,i.jsx)(n.code,{children:"uv run openrag"}),".\nIf you installed OpenRAG with ",(0,i.jsx)(n.code,{children:"uvx"}),", run ",(0,i.jsx)(n.code,{children:"uvx openrag"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"tui-container-management",children:"Manage OpenRAG containers with the TUI"}),"\n",(0,i.jsx)(n.p,{children:"After installation, the TUI can deploy, manage, and upgrade your OpenRAG containers."}),"\n",(0,i.jsx)(n.h3,{id:"start-all-services",children:"Start all services"}),"\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Start All Services"})," to start the OpenRAG containers.\nThe TUI automatically detects your container runtime, and then checks if your machine has compatible GPU support by checking for ",(0,i.jsx)(n.code,{children:"CUDA"}),", ",(0,i.jsx)(n.code,{children:"NVIDIA_SMI"}),", and Docker/Podman runtime support. This check determines which Docker Compose file OpenRAG uses.\nThe TUI then pulls the images and deploys the containers with the following command."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"docker compose up -d\n"})}),"\n",(0,i.jsxs)(n.p,{children:["If images are missing, the TUI runs ",(0,i.jsx)(n.code,{children:"docker compose pull"}),", then runs ",(0,i.jsx)(n.code,{children:"docker compose up -d"}),"."]}),"\n",(0,i.jsx)(n.h3,{id:"status",children:"Status"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.strong,{children:"Status"})," menu displays information on your container deployment.\nHere you can check container health, find your service ports, view logs, and upgrade your containers."]}),"\n",(0,i.jsxs)(n.p,{children:["To view streaming logs, select the container you want to view, and press ",(0,i.jsx)("kbd",{children:"l"}),".\nTo copy your logs, click ",(0,i.jsx)(n.strong,{children:"Copy to Clipboard"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["To ",(0,i.jsx)(n.strong,{children:"upgrade"})," your containers, click ",(0,i.jsx)(n.strong,{children:"Upgrade"}),".\n",(0,i.jsx)(n.strong,{children:"Upgrade"})," runs ",(0,i.jsx)(n.code,{children:"docker compose pull"})," and then ",(0,i.jsx)(n.code,{children:"docker compose up -d --force-recreate"}),".\nFor more information, see ",(0,i.jsx)(n.a,{href:"#upgrade-openrag-containers-with-the-tui",children:"Upgrade OpenRAG containers with the TUI"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["To ",(0,i.jsx)(n.strong,{children:"reset"})," your containers, click ",(0,i.jsx)(n.strong,{children:"Reset"}),".\nReset gives you a completely fresh start.\nReset deletes all of your data, including OpenSearch data, uploaded documents, and authentication.\n",(0,i.jsx)(n.strong,{children:"Reset"})," runs two commands.\nIt first stops and removes all containers, volumes, and local images."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:"docker compose down --volumes --remove-orphans --rmi local\n"})}),"\n",(0,i.jsxs)(n.p,{children:["When the first command is complete, OpenRAG removes any additional Docker objects with ",(0,i.jsx)(n.code,{children:"prune"}),"."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:"docker system prune -f\n"})}),"\n",(0,i.jsx)(n.h3,{id:"native-services-status",children:"Native services status"}),"\n",(0,i.jsxs)(n.p,{children:["A ",(0,i.jsx)(n.em,{children:"native service"})," in OpenRAG refers to a service run locally on your machine, and not within a container.\nThe ",(0,i.jsx)(n.code,{children:"docling serve"})," process is a native service in OpenRAG, because it's a document processing service that is run on your local machine, and controlled separately from the containers."]}),"\n",(0,i.jsxs)(n.p,{children:["To start or stop ",(0,i.jsx)(n.code,{children:"docling serve"})," or any other native services, in the TUI Status menu, click ",(0,i.jsx)(n.strong,{children:"Stop"})," or ",(0,i.jsx)(n.strong,{children:"Restart"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["To view the status, port, or PID of a native service, in the TUI main menu, click ",(0,i.jsx)(n.a,{href:"#status",children:"Status"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"upgrade",children:"Upgrade OpenRAG"}),"\n",(0,i.jsx)(n.p,{children:"To upgrade OpenRAG, upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers using the OpenRAG TUI."}),"\n",(0,i.jsxs)(n.p,{children:["Upgrading the OpenRAG Python package updates the TUI and Python code, but container versions are controlled separately by environment variables in your ",(0,i.jsx)(n.code,{children:".env"})," file."]}),"\n",(0,i.jsx)(n.h3,{id:"upgrade-openrag-python-package",children:"Upgrade OpenRAG python package"}),"\n",(0,i.jsxs)(n.p,{children:["Use the following steps to upgrade the OpenRAG Python package to the latest version from ",(0,i.jsx)(n.a,{href:"https://pypi.org/project/openrag/",children:"PyPI"}),".\nAfter upgrading the Python package, you should also ",(0,i.jsx)(n.a,{href:"#upgrade-openrag-containers-with-the-tui",children:"upgrade your OpenRAG containers"}),"."]}),"\n",(0,i.jsxs)(o.A,{groupId:"Installation method",children:[(0,i.jsxs)(l.A,{value:"installer",label:"Automatic installer / uvx",default:!0,children:[(0,i.jsxs)(n.p,{children:["If you installed OpenRAG using the ",(0,i.jsx)(n.a,{href:"#install",children:"automatic installer"})," or ",(0,i.jsx)(n.a,{href:"#install",children:"uvx"}),", follow these steps to upgrade:"]}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Navigate to your OpenRAG workspace directory:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"cd openrag-workspace\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Upgrade the OpenRAG package:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uvx --from openrag openrag\n"})}),"\n",(0,i.jsx)(n.p,{children:"To upgrade to a specific version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uvx --from openrag==0.1.33 openrag\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["After upgrading the Python package, ",(0,i.jsx)(n.a,{href:"#upgrade-openrag-containers-with-the-tui",children:"upgrade your containers"}),"."]}),"\n"]}),"\n"]})]}),(0,i.jsx)(l.A,{value:"uv-add",label:"Python project with uv add",children:(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Navigate to your project directory:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"cd YOUR_PROJECT_NAME\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Update OpenRAG to the latest version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv add --upgrade openrag\n"})}),"\n",(0,i.jsx)(n.p,{children:"To upgrade to a specific version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv add --upgrade openrag==0.1.33\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Start the OpenRAG TUI:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv run openrag\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["After upgrading the Python package, ",(0,i.jsx)(n.a,{href:"#upgrade-openrag-containers-with-the-tui",children:"upgrade your containers"}),"."]}),"\n"]}),"\n"]})}),(0,i.jsx)(l.A,{value:"uv-pip",label:"Existing virtual environment with uv pip install",children:(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Activate your virtual environment."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Upgrade OpenRAG:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv pip install --upgrade openrag\n"})}),"\n",(0,i.jsx)(n.p,{children:"To upgrade to a specific version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv pip install --upgrade openrag==0.1.33\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Start the OpenRAG TUI:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv run openrag\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["After upgrading the Python package, ",(0,i.jsx)(n.a,{href:"#upgrade-openrag-containers-with-the-tui",children:"upgrade your containers"}),"."]}),"\n"]}),"\n"]})})]}),"\n",(0,i.jsx)(n.h3,{id:"upgrade-openrag-containers-with-the-tui",children:"Upgrade OpenRAG containers with the TUI"}),"\n",(0,i.jsxs)(n.p,{children:["After upgrading the OpenRAG Python package, upgrade your containers to ensure they match the ",(0,i.jsx)(n.code,{children:"latest"})," version.\n",(0,i.jsx)(n.strong,{children:"Upgrade"})," runs ",(0,i.jsx)(n.code,{children:"docker compose pull"}),", which pulls container images based on versions specified in your ",(0,i.jsx)(n.code,{children:".env"})," file.\n",(0,i.jsx)(n.code,{children:"OPENRAG_VERSION"})," is set to ",(0,i.jsx)(n.code,{children:"latest"})," by default, so it pulls the ",(0,i.jsx)(n.code,{children:"latest"})," available container images."]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["In the OpenRAG TUI, click ",(0,i.jsx)(n.strong,{children:"Status"}),", and then click ",(0,i.jsx)(n.strong,{children:"Upgrade"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:["When the upgrade completes, close the ",(0,i.jsx)(n.strong,{children:"Status"})," window and continue using OpenRAG."]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["If you encounter a ",(0,i.jsx)(n.code,{children:"langflow container already exists"})," error during upgrade, see ",(0,i.jsx)(n.a,{href:"/support/troubleshoot#langflow-container-already-exists-during-upgrade",children:"Langflow container already exists during upgrade"})," in the troubleshooting guide."]}),"\n",(0,i.jsxs)(n.p,{children:["To pin container versions to a specific release other than ",(0,i.jsx)(n.code,{children:"latest"}),", set the ",(0,i.jsx)(n.code,{children:"OPENRAG_VERSION"})," in your ",(0,i.jsx)(n.code,{children:".env"})," file:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"OPENRAG_VERSION=0.1.33\n"})}),"\n",(0,i.jsxs)(n.p,{children:["For more information, see ",(0,i.jsx)(n.a,{href:"/reference/configuration#system-settings",children:"System settings environment variables"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"diagnostics",children:"Diagnostics"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.strong,{children:"Diagnostics"})," menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security."]}),"\n",(0,i.jsx)(n.h2,{id:"reinstall",children:"Reinstall OpenRAG"}),"\n",(0,i.jsx)(n.p,{children:"To reinstall OpenRAG with a completely fresh setup:"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Reset your containers using the ",(0,i.jsx)(n.strong,{children:"Reset"})," button in the ",(0,i.jsx)(n.a,{href:"#status",children:"TUI status"})," menu.\nThis removes all containers, volumes, and data."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Optional: Delete your project's ",(0,i.jsx)(n.code,{children:".env"})," file.\nThe Reset operation doesn't remove your project's ",(0,i.jsx)(n.code,{children:".env"})," file, so your passwords, API keys, and OAuth settings can be preserved.\nIf you delete the ",(0,i.jsx)(n.code,{children:".env"})," file, run the ",(0,i.jsx)(n.a,{href:"#setup",children:"Set up OpenRAG with the TUI"})," process again to create a new configuration."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["In the TUI Setup menu, follow these steps from ",(0,i.jsx)(n.a,{href:"#setup",children:"Basic Setup"}),":"]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["Click ",(0,i.jsx)(n.strong,{children:"Start All Services"})," to pull container images and start them."]}),"\n",(0,i.jsxs)(n.li,{children:["Under ",(0,i.jsx)(n.strong,{children:"Native Services"}),", click ",(0,i.jsx)(n.strong,{children:"Start"})," to start the Docling service."]}),"\n",(0,i.jsxs)(n.li,{children:["Click ",(0,i.jsx)(n.strong,{children:"Open App"})," to open the OpenRAG application."]}),"\n",(0,i.jsxs)(n.li,{children:["Continue with ",(0,i.jsx)(n.a,{href:"#application-onboarding",children:"application onboarding"}),"."]}),"\n"]}),"\n"]}),"\n"]})]})}function j(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(x,{...e})}):x(e)}},5689:(e,n,s)=>{s.d(n,{A:()=>r});const r=s.p+"assets/images/OpenRAG_TUI_2025-09-10T13_04_11_757637-9441c53ba39162a88ac6c11cbeaed0e0.svg"}}]); \ No newline at end of file diff --git a/assets/js/d0314b07.7b0b4caa.js b/assets/js/d0314b07.7b0b4caa.js new file mode 100644 index 00000000..14ce26e4 --- /dev/null +++ b/assets/js/d0314b07.7b0b4caa.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkopenrag_docs=self.webpackChunkopenrag_docs||[]).push([[5750],{3656:(e,n,s)=>{s.d(n,{Ay:()=>p,RM:()=>d});var r=s(4848),i=s(8453),t=s(1610),o=s(1470),l=s(9365);function a(e){const n={a:"a",code:"code",li:"li",ol:"ol",p:"p",strong:"strong",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.p,{children:"Using Ollama for your OpenRAG language model provider offers greater flexibility and configuration, but can also be overwhelming to start.\nThese recommendations are a reasonable starting point for users with at least one GPU and experience running LLMs locally."}),"\n",(0,r.jsxs)(n.p,{children:["For best performance, OpenRAG recommends OpenAI's ",(0,r.jsx)(n.code,{children:"gpt-oss:20b"})," language model. However, this model uses 16GB of RAM, so consider using Ollama Cloud or running Ollama on a remote machine."]}),"\n",(0,r.jsxs)(n.p,{children:["For generating embeddings, OpenRAG recommends the ",(0,r.jsx)(n.a,{href:"https://ollama.com/library/nomic-embed-text",children:(0,r.jsx)(n.code,{children:"nomic-embed-text"})})," embedding model, which provides high-quality embeddings optimized for retrieval tasks."]}),"\n",(0,r.jsxs)(n.p,{children:["To run models in ",(0,r.jsx)(n.a,{href:"https://docs.ollama.com/cloud",children:(0,r.jsx)(n.strong,{children:"Ollama Cloud"})}),", follow these steps:"]}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Sign in to Ollama Cloud.\nIn a terminal, enter ",(0,r.jsx)(n.code,{children:"ollama signin"})," to connect your local environment with Ollama Cloud."]}),"\n",(0,r.jsxs)(n.li,{children:["To run the model, in Ollama, select the ",(0,r.jsx)(n.code,{children:"gpt-oss:20b-cloud"})," model, or run ",(0,r.jsx)(n.code,{children:"ollama run gpt-oss:20b-cloud"})," in a terminal.\nOllama Cloud models are run at the same URL as your local Ollama server at ",(0,r.jsx)(n.code,{children:"http://localhost:11434"}),", and automatically offloaded to Ollama's cloud service."]}),"\n",(0,r.jsxs)(n.li,{children:["Connect OpenRAG to the same local Ollama server as you would for local models in onboarding, using the default address of ",(0,r.jsx)(n.code,{children:"http://localhost:11434"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["In the ",(0,r.jsx)(n.strong,{children:"Language model"})," field, select the ",(0,r.jsx)(n.code,{children:"gpt-oss:20b-cloud"})," model."]}),"\n"]}),"\n",(0,r.jsx)("br",{}),"\n",(0,r.jsxs)(n.p,{children:["To run models on a ",(0,r.jsx)(n.strong,{children:"remote Ollama server"}),", follow these steps:"]}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsx)(n.li,{children:"Ensure your remote Ollama server is accessible from your OpenRAG instance."}),"\n",(0,r.jsxs)(n.li,{children:["In the ",(0,r.jsx)(n.strong,{children:"Ollama Base URL"})," field, enter your remote Ollama server's base URL, such as ",(0,r.jsx)(n.code,{children:"http://your-remote-server:11434"}),".\nOpenRAG connects to the remote Ollama server and populates the lists with the server's available models."]}),"\n",(0,r.jsxs)(n.li,{children:["Select your ",(0,r.jsx)(n.strong,{children:"Embedding model"})," and ",(0,r.jsx)(n.strong,{children:"Language model"})," from the available options."]}),"\n"]})]})}function c(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(a,{...e})}):a(e)}const d=[{value:"Application onboarding",id:"application-onboarding",level:2}];function h(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",li:"li",ol:"ol",p:"p",strong:"strong",...(0,i.R)(),...e.components},{Details:s}=n;return s||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.h2,{id:"application-onboarding",children:"Application onboarding"}),"\n",(0,r.jsx)(n.p,{children:"The first time you start OpenRAG, regardless of how you installed it, you must complete application onboarding."}),"\n",(0,r.jsxs)(n.p,{children:["Some of these variables, such as the embedding models, can be changed seamlessly after onboarding.\nOthers are immutable and require you to destroy and recreate the OpenRAG containers.\nFor more information, see ",(0,r.jsx)(n.a,{href:"/reference/configuration",children:"Environment variables"}),"."]}),"\n",(0,r.jsx)(n.p,{children:"You can use different providers for your language model and embedding model, such as Anthropic for the language model and OpenAI for the embeddings model.\nAdditionally, you can set multiple embedding models."}),"\n",(0,r.jsx)(n.p,{children:"You only need to complete onboarding for your preferred providers."}),"\n",(0,r.jsxs)(o.A,{groupId:"Provider",children:[(0,r.jsxs)(l.A,{value:"Anthropic",label:"Anthropic",default:!0,children:[(0,r.jsx)(n.admonition,{type:"info",children:(0,r.jsx)(n.p,{children:"Anthropic doesn't provide embedding models. If you select Anthropic for your language model, you must select a different provider for embeddings."})}),(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Enable ",(0,r.jsx)(n.strong,{children:"Use environment Anthropic API key"})," to automatically use your key from the ",(0,r.jsx)(n.code,{children:".env"})," file.\nAlternatively, paste an Anthropic API key into the field."]}),"\n",(0,r.jsxs)(n.li,{children:["Under ",(0,r.jsx)(n.strong,{children:"Advanced settings"}),", select your ",(0,r.jsx)(n.strong,{children:"Language Model"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Click ",(0,r.jsx)(n.strong,{children:"Complete"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["In the second onboarding panel, select a provider for embeddings and select your ",(0,r.jsx)(n.strong,{children:"Embedding Model"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["To complete the onboarding tasks, click ",(0,r.jsx)(n.strong,{children:"What is OpenRAG"}),", and then click ",(0,r.jsx)(n.strong,{children:"Add a Document"}),".\nAlternatively, click ",(0,r.jsx)(t.A,{name:"ArrowRight","aria-hidden":"true"})," ",(0,r.jsx)(n.strong,{children:"Skip overview"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Continue with the ",(0,r.jsx)(n.a,{href:"/quickstart",children:"Quickstart"}),"."]}),"\n"]})]}),(0,r.jsx)(l.A,{value:"OpenAI",label:"OpenAI",children:(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Enable ",(0,r.jsx)(n.strong,{children:"Get API key from environment variable"})," to automatically enter your key from the TUI-generated ",(0,r.jsx)(n.code,{children:".env"})," file.\nAlternatively, paste an OpenAI API key into the field."]}),"\n",(0,r.jsxs)(n.li,{children:["Under ",(0,r.jsx)(n.strong,{children:"Advanced settings"}),", select your ",(0,r.jsx)(n.strong,{children:"Language Model"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Click ",(0,r.jsx)(n.strong,{children:"Complete"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["In the second onboarding panel, select a provider for embeddings and select your ",(0,r.jsx)(n.strong,{children:"Embedding Model"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["To complete the onboarding tasks, click ",(0,r.jsx)(n.strong,{children:"What is OpenRAG"}),", and then click ",(0,r.jsx)(n.strong,{children:"Add a Document"}),".\nAlternatively, click ",(0,r.jsx)(t.A,{name:"ArrowRight","aria-hidden":"true"})," ",(0,r.jsx)(n.strong,{children:"Skip overview"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Continue with the ",(0,r.jsx)(n.a,{href:"/quickstart",children:"Quickstart"}),"."]}),"\n"]})}),(0,r.jsx)(l.A,{value:"IBM watsonx.ai",label:"IBM watsonx.ai",children:(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Complete the fields for ",(0,r.jsx)(n.strong,{children:"watsonx.ai API Endpoint"}),", ",(0,r.jsx)(n.strong,{children:"IBM Project ID"}),", and ",(0,r.jsx)(n.strong,{children:"IBM API key"}),".\nThese values are found in your IBM watsonx deployment."]}),"\n",(0,r.jsxs)(n.li,{children:["Under ",(0,r.jsx)(n.strong,{children:"Advanced settings"}),", select your ",(0,r.jsx)(n.strong,{children:"Language Model"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Click ",(0,r.jsx)(n.strong,{children:"Complete"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["In the second onboarding panel, select a provider for embeddings and select your ",(0,r.jsx)(n.strong,{children:"Embedding Model"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["To complete the onboarding tasks, click ",(0,r.jsx)(n.strong,{children:"What is OpenRAG"}),", and then click ",(0,r.jsx)(n.strong,{children:"Add a Document"}),".\nAlternatively, click ",(0,r.jsx)(t.A,{name:"ArrowRight","aria-hidden":"true"})," ",(0,r.jsx)(n.strong,{children:"Skip overview"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Continue with the ",(0,r.jsx)(n.a,{href:"/quickstart",children:"Quickstart"}),"."]}),"\n"]})}),(0,r.jsxs)(l.A,{value:"Ollama",label:"Ollama",children:[(0,r.jsx)(n.admonition,{type:"info",children:(0,r.jsxs)(n.p,{children:["Ollama isn't installed with OpenRAG. To install Ollama, see the ",(0,r.jsx)(n.a,{href:"https://docs.ollama.com/",children:"Ollama documentation"}),"."]})}),(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["To connect to an Ollama server running on your local machine, enter your Ollama server's base URL address.\nThe default Ollama server address is ",(0,r.jsx)(n.code,{children:"http://localhost:11434"}),".\nOpenRAG connects to the Ollama server and populates the model lists with the server's available models."]}),"\n",(0,r.jsxs)(n.li,{children:["Select the ",(0,r.jsx)(n.strong,{children:"Embedding Model"})," and ",(0,r.jsx)(n.strong,{children:"Language Model"})," your Ollama server is running.","\n",(0,r.jsxs)(s,{closed:!0,children:[(0,r.jsx)("summary",{children:"Ollama model selection and external server configuration"}),(0,r.jsx)(c,{})]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["Click ",(0,r.jsx)(n.strong,{children:"Complete"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["To complete the onboarding tasks, click ",(0,r.jsx)(n.strong,{children:"What is OpenRAG"}),", and then click ",(0,r.jsx)(n.strong,{children:"Add a Document"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["Continue with the ",(0,r.jsx)(n.a,{href:"/quickstart",children:"Quickstart"}),"."]}),"\n"]})]})]})]})}function p(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(h,{...e})}):h(e)}},3862:(e,n,s)=>{s.d(n,{Ay:()=>l,RM:()=>t});var r=s(4848),i=s(8453);const t=[];function o(e){const n={a:"a",admonition:"admonition",code:"code",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install",children:"Install WSL"})," with the Ubuntu distribution using WSL 2:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-powershell",children:"wsl --install -d Ubuntu\n"})}),"\n",(0,r.jsxs)(n.p,{children:["For new installations, the ",(0,r.jsx)(n.code,{children:"wsl --install"})," command uses WSL 2 and Ubuntu by default."]}),"\n",(0,r.jsxs)(n.p,{children:["For existing WSL installations, you can ",(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install#change-the-default-linux-distribution-installed",children:"change the distribution"})," and ",(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install#upgrade-version-from-wsl-1-to-wsl-2",children:"check the WSL version"}),"."]}),"\n",(0,r.jsx)(n.admonition,{title:"Known limitation",type:"warning",children:(0,r.jsx)(n.p,{children:"OpenRAG isn't compatible with nested virtualization, which can cause networking issues.\nDon't install OpenRAG on a WSL distribution that is installed inside a Windows VM.\nInstead, install OpenRAG on your base OS or a non-nested Linux VM."})}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install#ways-to-run-multiple-linux-distributions-with-wsl",children:"Start your WSL Ubuntu distribution"})," if it doesn't start automatically."]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-your-linux-username-and-password",children:"Set up a username and password for your WSL distribution"}),"."]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers",children:"Install Docker Desktop for Windows with WSL 2"}),". When you reach the Docker Desktop ",(0,r.jsx)(n.strong,{children:"WSL integration"})," settings, make sure your Ubuntu distribution is enabled, and then click ",(0,r.jsx)(n.strong,{children:"Apply & Restart"})," to enable Docker support in WSL."]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:"Install and run OpenRAG from within your WSL Ubuntu distribution."}),"\n"]}),"\n"]}),"\n",(0,r.jsx)("br",{}),"\n",(0,r.jsxs)(n.p,{children:["If you encounter issues with port forwarding or the Windows Firewall, you might need to adjust the ",(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall",children:"Hyper-V firewall settings"})," to allow communication between your WSL distribution and the Windows host. For more troubleshooting advice for networking issues, see ",(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#common-issues",children:"Troubleshooting WSL common issues"}),"."]})]})}function l(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(o,{...e})}):o(e)}},4398:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>p,contentTitle:()=>h,default:()=>j,frontMatter:()=>d,metadata:()=>r,toc:()=>u});const r=JSON.parse('{"id":"get-started/install","title":"Install OpenRAG with TUI","description":"Install OpenRAG and then run the OpenRAG Terminal User Interface(TUI) to start your OpenRAG deployment with a guided setup process.","source":"@site/docs/get-started/install.mdx","sourceDirName":"get-started","slug":"/install","permalink":"/install","draft":false,"unlisted":false,"editUrl":"https://github.com/openrag/openrag/tree/main/docs/docs/get-started/install.mdx","tags":[],"version":"current","frontMatter":{"title":"Install OpenRAG with TUI","slug":"/install"},"sidebar":"tutorialSidebar","previous":{"title":"Quickstart","permalink":"/quickstart"},"next":{"title":"Install OpenRAG containers","permalink":"/docker"}}');var i=s(4848),t=s(8453),o=s(1470),l=s(9365),a=s(3656),c=s(3862);const d={title:"Install OpenRAG with TUI",slug:"/install"},h=void 0,p={},u=[{value:"Prerequisites",id:"prerequisites",level:2},...c.RM,{value:"Install OpenRAG",id:"install",level:2},{value:"Set up OpenRAG with the TUI",id:"setup",level:2},...a.RM,{value:"Exit the OpenRAG TUI",id:"exit-the-openrag-tui",level:2},{value:"Manage OpenRAG containers with the TUI",id:"tui-container-management",level:2},{value:"Diagnostics",id:"diagnostics",level:3},{value:"Status",id:"status",level:3},{value:"Reset containers",id:"reset-containers",level:3},{value:"Start all services",id:"start-all-services",level:3},{value:"Upgrade OpenRAG",id:"upgrade",level:2},{value:"Reinstall OpenRAG",id:"reinstall",level:2}];function x(e){const n={a:"a",admonition:"admonition",code:"code",em:"em",h2:"h2",h3:"h3",img:"img",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components},{Details:r}=n;return r||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,i.jsxs)(i.Fragment,{children:[(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.a,{href:"#install",children:"Install OpenRAG"})," and then run the ",(0,i.jsx)(n.a,{href:"#setup",children:"OpenRAG Terminal User Interface(TUI)"})," to start your OpenRAG deployment with a guided setup process."]}),"\n",(0,i.jsx)(n.p,{children:"The OpenRAG Terminal User Interface (TUI) allows you to set up, configure, and monitor your OpenRAG deployment directly from the terminal."}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.img,{alt:"OpenRAG TUI Interface",src:s(5689).A+"",width:"1995",height:"1099"})}),"\n",(0,i.jsxs)(n.p,{children:["Instead of starting OpenRAG using Docker commands and manually editing values in the ",(0,i.jsx)(n.code,{children:".env"})," file, the TUI walks you through the setup. It prompts for variables where required, creates a ",(0,i.jsx)(n.code,{children:".env"})," file for you, and then starts OpenRAG."]}),"\n",(0,i.jsx)(n.p,{children:"Once OpenRAG is running, use the TUI to monitor your application, control your containers, and retrieve logs."}),"\n",(0,i.jsxs)(n.p,{children:["If you prefer running Podman or Docker containers and manually editing ",(0,i.jsx)(n.code,{children:".env"})," files, see ",(0,i.jsx)(n.a,{href:"/docker",children:"Install OpenRAG Containers"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["All OpenRAG installations require ",(0,i.jsx)(n.a,{href:"https://www.python.org/downloads/release/python-3100/",children:"Python"})," version 3.13 or later."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"If you aren't using the automatic installer script, install the following:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"https://docs.astral.sh/uv/getting-started/installation/",children:"uv"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"https://podman.io/docs/installation",children:"Podman"})," (recommended) or ",(0,i.jsx)(n.a,{href:"https://docs.docker.com/get-docker/",children:"Docker"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"https://docs.podman.io/en/latest/markdown/podman-compose.1.html",children:(0,i.jsx)(n.code,{children:"podman-compose"})})," or ",(0,i.jsx)(n.a,{href:"https://docs.docker.com/compose/install/",children:"Docker Compose"}),". To use Docker Compose with Podman, you must alias Docker Compose commands to Podman commands."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Microsoft Windows only: To run OpenRAG on Windows, you must use the Windows Subsystem for Linux (WSL)."}),"\n",(0,i.jsxs)(r,{children:[(0,i.jsx)("summary",{children:"Install WSL for OpenRAG"}),(0,i.jsx)(c.Ay,{})]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Prepare model providers and credentials."}),"\n",(0,i.jsxs)(n.p,{children:["During ",(0,i.jsx)(n.a,{href:"#application-onboarding",children:"application onboarding"}),", you must select language model and embedding model providers.\nIf your chosen provider offers both types, you can use the same provider for both selections.\nIf your provider offers only one type, such as Anthropic, you must select two providers."]}),"\n",(0,i.jsx)(n.p,{children:"Gather the credentials and connection details for your chosen model providers before starting onboarding:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["OpenAI: Create an ",(0,i.jsx)(n.a,{href:"https://platform.openai.com/api-keys",children:"OpenAI API key"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:["Anthropic language models: Create an ",(0,i.jsx)(n.a,{href:"https://www.anthropic.com/docs/api/reference",children:"Anthropic API key"}),"."]}),"\n",(0,i.jsx)(n.li,{children:"IBM watsonx.ai: Get your watsonx.ai API endpoint, IBM project ID, and IBM API key from your watsonx deployment."}),"\n",(0,i.jsxs)(n.li,{children:["Ollama: Use the ",(0,i.jsx)(n.a,{href:"https://docs.ollama.com/",children:"Ollama documentation"})," to set up your Ollama instance locally, in the cloud, or on a remote server, and then get your Ollama server's base URL."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Optional: Install GPU support with an NVIDIA GPU, ",(0,i.jsx)(n.a,{href:"https://docs.nvidia.com/cuda/",children:"CUDA"})," support, and compatible NVIDIA drivers on the OpenRAG host machine. If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"install",children:"Install OpenRAG"}),"\n",(0,i.jsx)(n.p,{children:"Choose an installation method based on your needs:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"For new users, the automatic installer script detects and installs prerequisites and then runs OpenRAG."}),"\n",(0,i.jsxs)(n.li,{children:["For a quick test, use ",(0,i.jsx)(n.code,{children:"uvx"})," to run OpenRAG without creating a project or modifying files."]}),"\n",(0,i.jsxs)(n.li,{children:["Use ",(0,i.jsx)(n.code,{children:"uv add"})," to install OpenRAG as a managed dependency in a new or existing Python project."]}),"\n",(0,i.jsxs)(n.li,{children:["Use ",(0,i.jsx)(n.code,{children:"uv pip install"})," to install OpenRAG into an existing virtual environment."]}),"\n"]}),"\n",(0,i.jsxs)(o.A,{groupId:"Installation method",children:[(0,i.jsxs)(l.A,{value:"installer",label:"Automatic installer",default:!0,children:[(0,i.jsxs)(n.p,{children:["The script detects and installs uv, Docker/Podman, and Docker Compose prerequisites, then runs OpenRAG with ",(0,i.jsx)(n.code,{children:"uvx"}),"."]}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Create a directory to store the OpenRAG configuration files:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"mkdir openrag-workspace\ncd openrag-workspace\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Run the installer:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"curl -fsSL https://docs.openr.ag/files/run_openrag_with_prereqs.sh | bash\n"})}),"\n"]}),"\n"]}),(0,i.jsxs)(n.p,{children:["The TUI creates a ",(0,i.jsx)(n.code,{children:".env"})," file and docker-compose files in the current working directory."]})]}),(0,i.jsxs)(l.A,{value:"uvx",label:"Quick test with uvx",children:[(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"uvx"})," to quickly run OpenRAG without creating a project or modifying any files."]}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Create a directory to store the OpenRAG configuration files:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"mkdir openrag-workspace\ncd openrag-workspace\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Run OpenRAG:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uvx openrag\n"})}),"\n",(0,i.jsx)(n.p,{children:"To run a specific version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uvx --from openrag==0.1.30 openrag\n"})}),"\n"]}),"\n"]}),(0,i.jsxs)(n.p,{children:["The TUI creates a ",(0,i.jsx)(n.code,{children:".env"})," file and docker-compose files in the current working directory."]})]}),(0,i.jsxs)(l.A,{value:"uv-add",label:"Python project with uv add",children:[(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"uv add"})," to install OpenRAG as a dependency in your Python project. This adds OpenRAG to your ",(0,i.jsx)(n.code,{children:"pyproject.toml"})," and lockfile, making your installation reproducible and version-controlled."]}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Create a new project with a virtual environment:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv init YOUR_PROJECT_NAME\ncd YOUR_PROJECT_NAME\n"})}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"(venv)"})," prompt doesn't change, but ",(0,i.jsx)(n.code,{children:"uv"})," commands will automatically use the project's virtual environment."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Add OpenRAG to your project:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv add openrag\n"})}),"\n",(0,i.jsx)(n.p,{children:"To add a specific version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv add openrag==0.1.30\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Start the OpenRAG TUI:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv run openrag\n"})}),"\n"]}),"\n"]}),(0,i.jsxs)(r,{closed:!0,children:[(0,i.jsx)("summary",{children:"Install a local wheel"}),(0,i.jsx)(n.p,{children:"If you downloaded the OpenRAG wheel to your local machine, install it by specifying its path:"}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Add the wheel to your project:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv add PATH/TO/openrag-VERSION-py3-none-any.whl\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Replace ",(0,i.jsx)(n.code,{children:"PATH/TO/"})," and ",(0,i.jsx)(n.code,{children:"VERSION"})," with the path and version of your downloaded OpenRAG ",(0,i.jsx)(n.code,{children:".whl"})," file."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Run OpenRAG:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv run openrag\n"})}),"\n"]}),"\n"]})]})]}),(0,i.jsxs)(l.A,{value:"uv-pip",label:"Existing virtual environment with uv pip install",children:[(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"uv pip install"})," to install OpenRAG into an existing virtual environment that isn't managed by ",(0,i.jsx)(n.code,{children:"uv"}),"."]}),(0,i.jsx)(n.admonition,{type:"tip",children:(0,i.jsxs)(n.p,{children:["For new projects, ",(0,i.jsx)(n.code,{children:"uv add"})," is recommended as it manages dependencies in your project's lockfile."]})}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Activate your virtual environment."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Install OpenRAG:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv pip install openrag\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Run OpenRAG:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv run openrag\n"})}),"\n"]}),"\n"]})]})]}),"\n",(0,i.jsxs)(n.p,{children:["Continue with ",(0,i.jsx)(n.a,{href:"#setup",children:"Set up OpenRAG with the TUI"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["If you encounter errors during installation, see ",(0,i.jsx)(n.a,{href:"/support/troubleshoot",children:"Troubleshoot OpenRAG"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"setup",children:"Set up OpenRAG with the TUI"}),"\n",(0,i.jsxs)(n.p,{children:["The OpenRAG setup process creates a ",(0,i.jsx)(n.code,{children:".env"})," file at the root of your OpenRAG directory, and then starts OpenRAG.\nIf it detects a ",(0,i.jsx)(n.code,{children:".env"})," file in the OpenRAG root directory, it sources any variables from the ",(0,i.jsx)(n.code,{children:".env"})," file."]}),"\n",(0,i.jsxs)(n.p,{children:["The TUI offers two setup methods to populate the required values. ",(0,i.jsx)(n.strong,{children:"Basic Setup"})," can generate all minimum required values for OpenRAG. However, ",(0,i.jsx)(n.strong,{children:"Basic Setup"})," doesn't enable ",(0,i.jsx)(n.a,{href:"/knowledge#auth",children:"OAuth connectors for cloud storage"}),". If you want to use OAuth connectors to upload documents from cloud storage, select ",(0,i.jsx)(n.strong,{children:"Advanced Setup"}),".\nIf OpenRAG detects OAuth credentials, it recommends ",(0,i.jsx)(n.strong,{children:"Advanced Setup"}),"."]}),"\n",(0,i.jsxs)(o.A,{groupId:"Setup method",children:[(0,i.jsx)(l.A,{value:"Basic setup",label:"Basic setup",default:!0,children:(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To install OpenRAG with ",(0,i.jsx)(n.strong,{children:"Basic Setup"}),", click ",(0,i.jsx)(n.strong,{children:"Basic Setup"})," or press ",(0,i.jsx)("kbd",{children:"1"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Generate Passwords"})," to generate passwords for OpenSearch and Langflow."]}),"\n",(0,i.jsxs)(n.p,{children:["The OpenSearch password is required. The Langflow admin password is optional.\nIf no Langflow admin password is generated, Langflow runs in ",(0,i.jsx)(n.a,{href:"https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login",children:"autologin mode"})," with no password required."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Optional: Paste your OpenAI API key in the OpenAI API key field. You can also provide this during onboarding or choose a different model provider."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Save Configuration"}),".\nYour passwords are saved in the ",(0,i.jsx)(n.code,{children:".env"})," file used to start OpenRAG."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To start OpenRAG, click ",(0,i.jsx)(n.strong,{children:"Start All Services"}),".\nStartup pulls container images and runs them, so it can take some time.\nWhen startup is complete, the TUI displays the following:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"Services started successfully\nCommand completed successfully\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To start the Docling service, under ",(0,i.jsx)(n.strong,{children:"Native Services"}),", click ",(0,i.jsx)(n.strong,{children:"Start"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To open the OpenRAG application, navigate to the TUI main menu, and then click ",(0,i.jsx)(n.strong,{children:"Open App"}),".\nAlternatively, in your browser, navigate to ",(0,i.jsx)(n.code,{children:"localhost:3000"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Continue with ",(0,i.jsx)(n.a,{href:"#application-onboarding",children:"application onboarding"}),"."]}),"\n"]}),"\n"]})}),(0,i.jsx)(l.A,{value:"Advanced setup",label:"Advanced setup",children:(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To install OpenRAG with ",(0,i.jsx)(n.strong,{children:"Advanced Setup"}),", click ",(0,i.jsx)(n.strong,{children:"Advanced Setup"})," or press ",(0,i.jsx)("kbd",{children:"2"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Generate Passwords"})," to generate passwords for OpenSearch and Langflow."]}),"\n",(0,i.jsxs)(n.p,{children:["The OpenSearch password is required. The Langflow admin password is optional.\nIf no Langflow admin password is generated, Langflow runs in ",(0,i.jsx)(n.a,{href:"https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login",children:"autologin mode"})," with no password required."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Paste your OpenAI API key in the OpenAI API key field."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["If you want to upload documents from external storage, such as Google Drive, add the required OAuth credentials for the connectors that you want to use. These settings can be populated automatically if OpenRAG detects these credentials in a ",(0,i.jsx)(n.code,{children:".env"})," file in the OpenRAG installation directory."]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Amazon"}),": Provide your AWS Access Key ID and AWS Secret Access Key with access to your S3 instance. For more information, see the AWS documentation on ",(0,i.jsx)(n.a,{href:"https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-applications.html",children:"Configuring access to AWS applications"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Google"}),": Provide your Google OAuth Client ID and Google OAuth Client Secret. You can generate these in the ",(0,i.jsx)(n.a,{href:"https://console.cloud.google.com/apis/credentials",children:"Google Cloud Console"}),". For more information, see the ",(0,i.jsx)(n.a,{href:"https://developers.google.com/identity/protocols/oauth2",children:"Google OAuth client documentation"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Microsoft"}),": For the Microsoft OAuth Client ID and Microsoft OAuth Client Secret, provide ",(0,i.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/app-registration?view=odsp-graph-online",children:"Azure application registration credentials for SharePoint and OneDrive"}),". For more information, see the ",(0,i.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/graph-oauth",children:"Microsoft Graph OAuth client documentation"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["You can ",(0,i.jsx)(n.a,{href:"/ingestion#oauth-ingestion",children:"manage OAuth credentials"})," later, but it is recommended to configure them during initial set up."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"The OpenRAG TUI presents redirect URIs for your OAuth app.\nThese are the URLs your OAuth provider will redirect back to after user sign-in.\nRegister these redirect values with your OAuth provider as they are presented in the TUI."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Save Configuration"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To start OpenRAG, click ",(0,i.jsx)(n.strong,{children:"Start All Services"}),".\nStartup pulls container images and runs them, so it can take some time.\nWhen startup is complete, the TUI displays the following:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"Services started successfully\nCommand completed successfully\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To start the Docling service, under ",(0,i.jsx)(n.strong,{children:"Native Services"}),", click ",(0,i.jsx)(n.strong,{children:"Start"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["To open the OpenRAG application, navigate to the TUI main menu, and then click ",(0,i.jsx)(n.strong,{children:"Open App"}),".\nAlternatively, in your browser, navigate to ",(0,i.jsx)(n.code,{children:"localhost:3000"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"If you enabled OAuth connectors, you must sign in to your OAuth provider before being redirected to your OpenRAG instance."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Two additional variables are available for ",(0,i.jsx)(n.strong,{children:"Advanced Setup"})," at this point.\nOnly change these variables if you have a non-default network configuration for your deployment, such as using a reverse proxy or custom domain."]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"LANGFLOW_PUBLIC_URL"}),": Sets the base address to access the Langflow web interface. This is where users interact with flows in a browser."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"WEBHOOK_BASE_URL"}),": Sets the base address of the OpenRAG OAuth connector endpoint.\nSupported webhook endpoints:"]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Amazon S3: Not applicable."}),"\n",(0,i.jsxs)(n.li,{children:["Google Drive: ",(0,i.jsx)(n.code,{children:"/connectors/google_drive/webhook"})]}),"\n",(0,i.jsxs)(n.li,{children:["OneDrive: ",(0,i.jsx)(n.code,{children:"/connectors/onedrive/webhook"})]}),"\n",(0,i.jsxs)(n.li,{children:["SharePoint: ",(0,i.jsx)(n.code,{children:"/connectors/sharepoint/webhook"})]}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Continue with ",(0,i.jsx)(n.a,{href:"#application-onboarding",children:"application onboarding"}),"."]}),"\n"]}),"\n"]})})]}),"\n",(0,i.jsx)(a.Ay,{}),"\n",(0,i.jsx)(n.h2,{id:"exit-the-openrag-tui",children:"Exit the OpenRAG TUI"}),"\n",(0,i.jsxs)(n.p,{children:["To exit the OpenRAG TUI, navigate to the main menu, and then press ",(0,i.jsx)("kbd",{children:"q"}),".\nThe OpenRAG containers continue to run until they are stopped.\nFor more information, see ",(0,i.jsx)(n.a,{href:"#tui-container-management",children:"Manage OpenRAG containers with the TUI "}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["To relaunch the TUI, run ",(0,i.jsx)(n.code,{children:"uv run openrag"}),".\nIf you installed OpenRAG with ",(0,i.jsx)(n.code,{children:"uvx"}),", run ",(0,i.jsx)(n.code,{children:"uvx openrag"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"tui-container-management",children:"Manage OpenRAG containers with the TUI"}),"\n",(0,i.jsx)(n.p,{children:"After installation, the TUI can deploy, manage, and upgrade your OpenRAG containers."}),"\n",(0,i.jsx)(n.h3,{id:"diagnostics",children:"Diagnostics"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.strong,{children:"Diagnostics"})," menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security."]}),"\n",(0,i.jsx)(n.h3,{id:"status",children:"Status"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.strong,{children:"Status"})," menu displays information on your container deployment.\nHere you can check container health, find your service ports, view logs, and upgrade your containers."]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Logs"}),": To view streaming logs, select the container you want to view, and press ",(0,i.jsx)("kbd",{children:"l"}),".\nTo copy the logs, click ",(0,i.jsx)(n.strong,{children:"Copy to Clipboard"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Upgrade"}),": Check for updates. For more information, see ",(0,i.jsx)(n.a,{href:"#upgrade",children:"upgrade OpenRAG"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Reset"}),": This is a destructive action that ",(0,i.jsx)(n.a,{href:"#reset-containers",children:"resets your containers"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Native services"}),": From the ",(0,i.jsx)(n.strong,{children:"Status"})," menu, you can view the status, port, and process ID (PID) of the OpenRAG native services.\nYou can also click ",(0,i.jsx)(n.strong,{children:"Stop"})," or ",(0,i.jsx)(n.strong,{children:"Restart"})," to stop and start OpenRAG native services."]}),"\n",(0,i.jsxs)(n.p,{children:["A ",(0,i.jsx)(n.em,{children:"native service"})," in OpenRAG is a service that runs locally on your machine, not within a container. For example, the ",(0,i.jsx)(n.code,{children:"docling serve"})," process is an OpenRAG native service because this document processing service runs on your local machine, separate from the OpenRAG containers."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"reset-containers",children:"Reset containers"}),"\n",(0,i.jsx)(n.admonition,{type:"warning",children:(0,i.jsx)(n.p,{children:"This is a destructive action that destroys and recreates all of your OpenRAG containers."})}),"\n",(0,i.jsxs)(n.p,{children:["To destroy and recreate your OpenRAG containers, go to the TUI ",(0,i.jsxs)(n.a,{href:"#status",children:[(0,i.jsx)(n.strong,{children:"Status"})," menu"]}),", and then click ",(0,i.jsx)(n.strong,{children:"Reset"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.strong,{children:"Reset"})," function runs two commands. First, it stops and removes all containers, volumes, and local images:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"docker compose down --volumes --remove-orphans --rmi local\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Then, it removes any additional Docker objects with ",(0,i.jsx)(n.code,{children:"docker system prune -f"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["If you reset your containers as part of reinstalling OpenRAG, continue the ",(0,i.jsx)(n.a,{href:"#reinstall",children:"reinstallation process"})," after resetting the containers."]}),"\n",(0,i.jsx)(n.h3,{id:"start-all-services",children:"Start all services"}),"\n",(0,i.jsxs)(n.p,{children:["On the TUI main page, click ",(0,i.jsx)(n.strong,{children:"Start All Services"})," to start the OpenRAG containers and launch OpenRAG itself."]}),"\n",(0,i.jsx)(n.p,{children:"When you start all services, the following processes happen:"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["OpenRAG automatically detects your container runtime, and then checks if your machine has compatible GPU support by checking for ",(0,i.jsx)(n.code,{children:"CUDA"}),", ",(0,i.jsx)(n.code,{children:"NVIDIA_SMI"}),", and Docker/Podman runtime support. This check determines which Docker Compose file OpenRAG uses."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["OpenRAG pulls the OpenRAG container images with ",(0,i.jsx)(n.code,{children:"docker compose pull"})," if any images are missing."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["OpenRAG deploys the containers with ",(0,i.jsx)(n.code,{children:"docker compose up -d"}),"."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"upgrade",children:"Upgrade OpenRAG"}),"\n",(0,i.jsx)(n.p,{children:"To upgrade OpenRAG, upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers."}),"\n",(0,i.jsxs)(n.p,{children:["This is a two part process because upgrading the OpenRAG Python package updates the TUI and Python code, but the container versions are controlled by environment variables in your ",(0,i.jsx)(n.code,{children:".env"})," file."]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Stop your OpenRAG containers: In the OpenRAG TUI, go to the ",(0,i.jsx)(n.strong,{children:"Status"})," menu, and then click ",(0,i.jsx)(n.strong,{children:"Stop Services"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Upgrade the OpenRAG Python package to the latest version from ",(0,i.jsx)(n.a,{href:"https://pypi.org/project/openrag/",children:"PyPI"}),"."]}),"\n",(0,i.jsxs)(o.A,{groupId:"Installation method",children:[(0,i.jsxs)(l.A,{value:"installer",label:"Automatic installer or uvx",default:!0,children:[(0,i.jsxs)(n.p,{children:["Use these steps to upgrade the Python package if you installed OpenRAG using the automatic installer or ",(0,i.jsx)(n.code,{children:"uvx"}),":"]}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Navigate to your OpenRAG workspace directory:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"cd openrag-workspace\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Upgrade the OpenRAG package:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uvx --from openrag openrag\n"})}),"\n",(0,i.jsx)(n.p,{children:"To upgrade to a specific version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uvx --from openrag==0.1.33 openrag\n"})}),"\n"]}),"\n"]})]}),(0,i.jsxs)(l.A,{value:"uv-add",label:"Python project (uv add)",children:[(0,i.jsxs)(n.p,{children:["Use these steps to upgrade the Python package if you installed OpenRAG in a Python project with ",(0,i.jsx)(n.code,{children:"uv add"}),":"]}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Navigate to your project directory:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"cd YOUR_PROJECT_NAME\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Update OpenRAG to the latest version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv add --upgrade openrag\n"})}),"\n",(0,i.jsx)(n.p,{children:"To upgrade to a specific version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv add --upgrade openrag==0.1.33\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Start the OpenRAG TUI:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv run openrag\n"})}),"\n"]}),"\n"]})]}),(0,i.jsxs)(l.A,{value:"uv-pip",label:"Virtual environment (uv pip install)",children:[(0,i.jsxs)(n.p,{children:["Use these steps to upgrade the Python package if you installed OpenRAG in a venv with ",(0,i.jsx)(n.code,{children:"uv pip install"}),":"]}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Activate your virtual environment."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Upgrade OpenRAG:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv pip install --upgrade openrag\n"})}),"\n",(0,i.jsx)(n.p,{children:"To upgrade to a specific version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv pip install --upgrade openrag==0.1.33\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Start the OpenRAG TUI:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv run openrag\n"})}),"\n"]}),"\n"]})]})]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Start the upgraded OpenRAG containers: In the OpenRAG TUI, click ",(0,i.jsx)(n.strong,{children:"Start All Services"}),", and then wait while the containers start."]}),"\n",(0,i.jsxs)(n.p,{children:["After upgrading the Python package, OpenRAG runs ",(0,i.jsx)(n.code,{children:"docker compose pull"})," to get the appropriate container images matching the version specified in your OpenRAG ",(0,i.jsx)(n.code,{children:".env"})," file. Then, it recreates the containers with the new images using ",(0,i.jsx)(n.code,{children:"docker compose up -d --force-recreate"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["In the ",(0,i.jsx)(n.code,{children:".env"})," file, the ",(0,i.jsx)(n.code,{children:"OPENRAG_VERSION"})," ",(0,i.jsx)(n.a,{href:"/reference/configuration#system-settings",children:"environment variable"})," is set to ",(0,i.jsx)(n.code,{children:"latest"})," by default, which it pulls the ",(0,i.jsx)(n.code,{children:"latest"})," available container images.\nTo pin a specific container image version, you can set ",(0,i.jsx)(n.code,{children:"OPENRAG_VERSION"})," to the desired container image version, such as ",(0,i.jsx)(n.code,{children:"OPENRAG_VERSION=0.1.33"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["However, when you upgrade the Python package, OpenRAG automatically attempts to keep the ",(0,i.jsx)(n.code,{children:"OPENRAG_VERSION"})," synchronized with the Python package version.\nYou might need to edit the ",(0,i.jsx)(n.code,{children:".env"})," file after upgrading the Python package to enforce a different container version.\nThe TUI warns you if it detects a version mismatch."]}),"\n",(0,i.jsxs)(n.p,{children:["If you get an error that ",(0,i.jsx)(n.code,{children:"langflow container already exists"})," error during upgrade, see ",(0,i.jsx)(n.a,{href:"/support/troubleshoot#langflow-container-already-exists-during-upgrade",children:"Langflow container already exists during upgrade"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["When the upgrade process is complete, you can close the ",(0,i.jsx)(n.strong,{children:"Status"})," window and continue using OpenRAG."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"reinstall",children:"Reinstall OpenRAG"}),"\n",(0,i.jsx)(n.p,{children:"To reinstall OpenRAG with a completely fresh setup:"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["In the TUI ",(0,i.jsx)(n.strong,{children:"Status"})," menu, ",(0,i.jsx)(n.a,{href:"#reset-containers",children:"reset your containers"})," to destroy the existing OpenRAG containers and their data."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Optional: Delete your project's ",(0,i.jsx)(n.code,{children:".env"})," file."]}),"\n",(0,i.jsxs)(n.p,{children:["The Reset operation doesn't remove your project's ",(0,i.jsx)(n.code,{children:".env"})," file, so your passwords, API keys, and OAuth settings can be preserved.\nIf you delete the ",(0,i.jsx)(n.code,{children:".env"})," file, you must run the ",(0,i.jsx)(n.a,{href:"#setup",children:"Set up OpenRAG with the TUI"})," process again to create a new configuration file."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Optional: Delete your OpenSearch knowledge base by deleting the contents of the ",(0,i.jsx)(n.code,{children:"./opensearch-data"})," folder in your OpenRAG installation directory."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["In the TUI ",(0,i.jsx)(n.strong,{children:"Setup"})," menu, repeat the ",(0,i.jsx)(n.a,{href:"#setup",children:"Basic Setup"})," process:"]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["Click ",(0,i.jsx)(n.strong,{children:"Start All Services"})," to pull container images and start them."]}),"\n",(0,i.jsxs)(n.li,{children:["Under ",(0,i.jsx)(n.strong,{children:"Native Services"}),", click ",(0,i.jsx)(n.strong,{children:"Start"})," to start the Docling service."]}),"\n",(0,i.jsxs)(n.li,{children:["Click ",(0,i.jsx)(n.strong,{children:"Open App"})," to open the OpenRAG application."]}),"\n",(0,i.jsxs)(n.li,{children:["Continue with ",(0,i.jsx)(n.a,{href:"#application-onboarding",children:"application onboarding"}),"."]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["If reinstalling OpenRAG and deleting the ",(0,i.jsx)(n.code,{children:".env"})," file doesn't reset setup or onboarding, see ",(0,i.jsx)(n.a,{href:"/support/troubleshoot#reinstalling-openrag-doesnt-reset-onboarding",children:"Reinstalling OpenRAG doesn't reset onboarding"}),"."]})]})}function j(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(x,{...e})}):x(e)}},5689:(e,n,s)=>{s.d(n,{A:()=>r});const r=s.p+"assets/images/OpenRAG_TUI_2025-09-10T13_04_11_757637-9441c53ba39162a88ac6c11cbeaed0e0.svg"}}]); \ No newline at end of file diff --git a/assets/js/eb5b356a.5256f349.js b/assets/js/eb5b356a.5256f349.js new file mode 100644 index 00000000..0ef3e752 --- /dev/null +++ b/assets/js/eb5b356a.5256f349.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkopenrag_docs=self.webpackChunkopenrag_docs||[]).push([[2668],{5014:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>d,contentTitle:()=>c,default:()=>u,frontMatter:()=>t,metadata:()=>r,toc:()=>h});const r=JSON.parse('{"id":"support/troubleshoot","title":"Troubleshoot OpenRAG","description":"This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG.","source":"@site/docs/support/troubleshoot.mdx","sourceDirName":"support","slug":"/support/troubleshoot","permalink":"/support/troubleshoot","draft":false,"unlisted":false,"editUrl":"https://github.com/openrag/openrag/tree/main/docs/docs/support/troubleshoot.mdx","tags":[],"version":"current","frontMatter":{"title":"Troubleshoot OpenRAG","slug":"/support/troubleshoot"},"sidebar":"tutorialSidebar","previous":{"title":"Environment variables","permalink":"/reference/configuration"}}');var o=s(4848),i=s(8453),a=s(1470),l=s(9365);const t={title:"Troubleshoot OpenRAG",slug:"/support/troubleshoot"},c=void 0,d={},h=[{value:"OpenSearch fails to start",id:"opensearch-fails-to-start",level:2},{value:"OpenRAG fails to start from the TUI with operation not supported",id:"openrag-fails-to-start-from-the-tui-with-operation-not-supported",level:2},{value:"OpenRAG installation fails with unable to get local issuer certificate",id:"openrag-installation-fails-with-unable-to-get-local-issuer-certificate",level:2},{value:"Langflow connection issues",id:"langflow-connection-issues",level:2},{value:"Container out of memory errors",id:"container-out-of-memory-errors",level:2},{value:"Memory issue with Podman on macOS",id:"memory-issue-with-podman-on-macos",level:2},{value:"Port conflicts",id:"port-conflicts",level:2},{value:"OCR ingestion fails (easyocr not installed)",id:"ocr-ingestion-fails-easyocr-not-installed",level:2},{value:"Upgrade fails due to Langflow container already exists",id:"langflow-container-already-exists-during-upgrade",level:2},{value:"Reinstalling OpenRAG doesn't reset onboarding",id:"reinstalling-openrag-doesnt-reset-onboarding",level:2},{value:"Document ingestion or similarity search issues",id:"document-ingestion-or-similarity-search-issues",level:2}];function p(e){const n={a:"a",admonition:"admonition",code:"code",em:"em",h2:"h2",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",...(0,i.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.p,{children:"This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG."}),"\n",(0,o.jsx)(n.h2,{id:"opensearch-fails-to-start",children:"OpenSearch fails to start"}),"\n",(0,o.jsxs)(n.p,{children:["Check that ",(0,o.jsx)(n.code,{children:"OPENSEARCH_PASSWORD"})," set in ",(0,o.jsx)(n.a,{href:"/reference/configuration",children:"Environment variables"})," meets requirements.\nThe password must contain at least 8 characters, and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character that is strong."]}),"\n",(0,o.jsx)(n.h2,{id:"openrag-fails-to-start-from-the-tui-with-operation-not-supported",children:"OpenRAG fails to start from the TUI with operation not supported"}),"\n",(0,o.jsxs)(n.p,{children:["This error occurs when starting OpenRAG with the TUI in ",(0,o.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install",children:"WSL (Windows Subsystem for Linux)"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["The error occurs because OpenRAG is running within a WSL environment, so ",(0,o.jsx)(n.code,{children:"webbrowser.open()"})," can't launch a browser automatically."]}),"\n",(0,o.jsxs)(n.p,{children:["To access the OpenRAG application, open a web browser and enter ",(0,o.jsx)(n.code,{children:"http://localhost:3000"})," in the address bar."]}),"\n",(0,o.jsx)(n.h2,{id:"openrag-installation-fails-with-unable-to-get-local-issuer-certificate",children:"OpenRAG installation fails with unable to get local issuer certificate"}),"\n",(0,o.jsxs)(n.p,{children:["If you are installing OpenRAG on macOS, and the installation fails with ",(0,o.jsx)(n.code,{children:"unable to get local issuer certificate"}),", run the following command, and then retry the installation:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:'open "/Applications/Python VERSION/Install Certificates.command"\n'})}),"\n",(0,o.jsxs)(n.p,{children:["Replace ",(0,o.jsx)(n.code,{children:"VERSION"})," with your installed Python version, such as ",(0,o.jsx)(n.code,{children:"3.13"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"langflow-connection-issues",children:"Langflow connection issues"}),"\n",(0,o.jsxs)(n.p,{children:["Verify the ",(0,o.jsx)(n.code,{children:"LANGFLOW_SUPERUSER"})," credentials set in ",(0,o.jsx)(n.a,{href:"/reference/configuration",children:"Environment variables"})," are correct."]}),"\n",(0,o.jsx)(n.h2,{id:"container-out-of-memory-errors",children:"Container out of memory errors"}),"\n",(0,o.jsxs)(n.p,{children:["Increase Docker memory allocation or use ",(0,o.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/docker-compose-cpu.yml",children:"docker-compose-cpu.yml"})," to deploy OpenRAG."]}),"\n",(0,o.jsx)(n.h2,{id:"memory-issue-with-podman-on-macos",children:"Memory issue with Podman on macOS"}),"\n",(0,o.jsx)(n.p,{children:"If you're using Podman on macOS, you might need to increase VM memory on your Podman machine.\nThis example increases the machine size to 8 GB of RAM, which should be sufficient to run OpenRAG."}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman machine stop\npodman machine rm\npodman machine init --memory 8192 # 8 GB example\npodman machine start\n"})}),"\n",(0,o.jsx)(n.h2,{id:"port-conflicts",children:"Port conflicts"}),"\n",(0,o.jsx)(n.p,{children:"Ensure ports 3000, 7860, 8000, 9200, 5601 are available."}),"\n",(0,o.jsx)(n.h2,{id:"ocr-ingestion-fails-easyocr-not-installed",children:"OCR ingestion fails (easyocr not installed)"}),"\n",(0,o.jsxs)(n.p,{children:["If Docling ingestion fails with an OCR-related error and mentions ",(0,o.jsx)(n.code,{children:"easyocr"})," is missing, this is likely due to a stale ",(0,o.jsx)(n.code,{children:"uv"})," cache."]}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.code,{children:"easyocr"})," is already included as a dependency in OpenRAG's ",(0,o.jsx)(n.code,{children:"pyproject.toml"}),". Project-managed installations using ",(0,o.jsx)(n.code,{children:"uv sync"})," and ",(0,o.jsx)(n.code,{children:"uv run"})," always sync dependencies directly from your ",(0,o.jsx)(n.code,{children:"pyproject.toml"}),", so they should have ",(0,o.jsx)(n.code,{children:"easyocr"})," installed."]}),"\n",(0,o.jsxs)(n.p,{children:["If you're running OpenRAG with ",(0,o.jsx)(n.code,{children:"uvx openrag"}),", ",(0,o.jsx)(n.code,{children:"uvx"})," creates a cached, ephemeral environment that doesn't modify your project. This cache can become stale."]}),"\n",(0,o.jsxs)(n.p,{children:["On macOS, this cache directory is typically a user cache directory such as ",(0,o.jsx)(n.code,{children:"/Users/USER_NAME/.cache/uv"}),"."]}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"To clear the uv cache, run:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"uv cache clean\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Start OpenRAG:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"uvx openrag\n"})}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["If you don't need OCR, you can disable OCR-based processing in your ingestion settings to avoid requiring ",(0,o.jsx)(n.code,{children:"easyocr"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"langflow-container-already-exists-during-upgrade",children:"Upgrade fails due to Langflow container already exists"}),"\n",(0,o.jsxs)(n.p,{children:["If you encounter a ",(0,o.jsx)(n.code,{children:"langflow container already exists"})," error when upgrading OpenRAG, this typically means you upgraded OpenRAG with ",(0,o.jsx)(n.code,{children:"uv"}),", but you didn't remove or upgrade containers from a previous installation."]}),"\n",(0,o.jsx)(n.p,{children:"To resolve this issue, do the following:"}),"\n",(0,o.jsxs)(n.p,{children:["First, try removing only the Langflow container, and then retry the upgrade in the OpenRAG TUI by clicking ",(0,o.jsx)(n.strong,{children:"Status"})," and then ",(0,o.jsx)(n.strong,{children:"Upgrade"}),"."]}),"\n",(0,o.jsxs)(a.A,{groupId:"Container software",children:[(0,o.jsx)(l.A,{value:"Podman",label:"Podman",children:(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Stop the Langflow container:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman stop langflow\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove the Langflow container:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman rm langflow --force\n"})}),"\n"]}),"\n"]})}),(0,o.jsx)(l.A,{value:"Docker",label:"Docker",default:!0,children:(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Stop the Langflow container:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker stop langflow\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove the Langflow container:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker rm langflow --force\n"})}),"\n"]}),"\n"]})})]}),"\n",(0,o.jsx)(n.p,{children:"If reinstalling the Langflow container doesn't resolve the issue, you must reset to a fresh installation by removing all OpenRAG containers and data.\nThen, you can retry the upgrade."}),"\n",(0,o.jsx)(n.admonition,{type:"warning",children:(0,o.jsxs)(n.p,{children:["This is a destructive operation that destroys your OpenRAG containers and their contents.\nHowever, your ",(0,o.jsx)(n.code,{children:".env"})," file (configuration settings) and ",(0,o.jsx)(n.code,{children:"./opensearch-data"})," (OpenSearch knowledge base) are preserved."]})}),"\n",(0,o.jsxs)(n.p,{children:["To reset your installation, stop your containers, and then completely remove them.\nAfter removing the containers, retry the upgrade in the OpenRAG TUI by clicking ",(0,o.jsx)(n.strong,{children:"Status"})," and then ",(0,o.jsx)(n.strong,{children:"Upgrade"}),"."]}),"\n",(0,o.jsxs)(a.A,{groupId:"Container software",children:[(0,o.jsx)(l.A,{value:"Podman",label:"Podman",children:(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Stop all running containers:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman stop --all\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all containers, including stopped containers:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman rm --all --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all images:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman rmi --all --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all volumes:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman volume prune --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all networks except the default network:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman network prune --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Clean up any leftover data:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman system prune --all --force --volumes\n"})}),"\n"]}),"\n"]})}),(0,o.jsx)(l.A,{value:"Docker",label:"Docker",default:!0,children:(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Stop all running containers:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker stop $(docker ps -q)\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all containers, including stopped containers:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker rm --force $(docker ps -aq)\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all images:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker rmi --force $(docker images -q)\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all volumes:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker volume prune --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all networks except the default network:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker network prune --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Clean up any leftover data:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker system prune --all --force --volumes\n"})}),"\n"]}),"\n"]})})]}),"\n",(0,o.jsx)(n.h2,{id:"reinstalling-openrag-doesnt-reset-onboarding",children:"Reinstalling OpenRAG doesn't reset onboarding"}),"\n",(0,o.jsxs)(n.p,{children:["If you ",(0,o.jsx)(n.a,{href:"/install#reinstall",children:"reinstall OpenRAG"}),", you can restore your installation to it's original, default state by resetting the containers ",(0,o.jsx)(n.em,{children:"and"})," deleting the ",(0,o.jsx)(n.code,{children:".env"})," file."]}),"\n",(0,o.jsx)(n.p,{children:"When you start OpenRAG after doing this, you should be prompted to go through the initial setup and onboarding process again."}),"\n",(0,o.jsxs)(n.p,{children:["Due to a known issue, the onboarding process might not reset when you reinstall OpenRAG.\nIf this occurs, ",(0,o.jsx)(n.a,{href:"/install#install",children:"install OpenRAG in a new Python project directory"})," (with ",(0,o.jsx)(n.code,{children:"uv init"})," and ",(0,o.jsx)(n.code,{children:"uv add openrag"}),")."]}),"\n",(0,o.jsx)(n.h2,{id:"document-ingestion-or-similarity-search-issues",children:"Document ingestion or similarity search issues"}),"\n",(0,o.jsxs)(n.p,{children:["See ",(0,o.jsx)(n.a,{href:"/ingestion#troubleshoot-ingestion",children:"Troubleshoot ingestion"}),"."]})]})}function u(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(p,{...e})}):p(e)}}}]); \ No newline at end of file diff --git a/assets/js/eb5b356a.5a0abd05.js b/assets/js/eb5b356a.5a0abd05.js deleted file mode 100644 index 75c00bc5..00000000 --- a/assets/js/eb5b356a.5a0abd05.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkopenrag_docs=self.webpackChunkopenrag_docs||[]).push([[2668],{5014:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>d,contentTitle:()=>c,default:()=>u,frontMatter:()=>t,metadata:()=>r,toc:()=>h});const r=JSON.parse('{"id":"support/troubleshoot","title":"Troubleshoot OpenRAG","description":"This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG.","source":"@site/docs/support/troubleshoot.mdx","sourceDirName":"support","slug":"/support/troubleshoot","permalink":"/support/troubleshoot","draft":false,"unlisted":false,"editUrl":"https://github.com/openrag/openrag/tree/main/docs/docs/support/troubleshoot.mdx","tags":[],"version":"current","frontMatter":{"title":"Troubleshoot OpenRAG","slug":"/support/troubleshoot"},"sidebar":"tutorialSidebar","previous":{"title":"Environment variables","permalink":"/reference/configuration"}}');var o=s(4848),i=s(8453),a=s(1470),l=s(9365);const t={title:"Troubleshoot OpenRAG",slug:"/support/troubleshoot"},c=void 0,d={},h=[{value:"OpenSearch fails to start",id:"opensearch-fails-to-start",level:2},{value:"OpenRAG fails to start from the TUI with operation not supported",id:"openrag-fails-to-start-from-the-tui-with-operation-not-supported",level:2},{value:"OpenRAG installation fails with unable to get local issuer certificate",id:"openrag-installation-fails-with-unable-to-get-local-issuer-certificate",level:2},{value:"Langflow connection issues",id:"langflow-connection-issues",level:2},{value:"Container out of memory errors",id:"container-out-of-memory-errors",level:2},{value:"Memory issue with Podman on macOS",id:"memory-issue-with-podman-on-macos",level:2},{value:"Port conflicts",id:"port-conflicts",level:2},{value:"OCR ingestion fails (easyocr not installed)",id:"ocr-ingestion-fails-easyocr-not-installed",level:2},{value:"Upgrade fails due to Langflow container already exists",id:"langflow-container-already-exists-during-upgrade",level:2},{value:"Document ingestion or similarity search issues",id:"document-ingestion-or-similarity-search-issues",level:2}];function p(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",...(0,i.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.p,{children:"This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG."}),"\n",(0,o.jsx)(n.h2,{id:"opensearch-fails-to-start",children:"OpenSearch fails to start"}),"\n",(0,o.jsxs)(n.p,{children:["Check that ",(0,o.jsx)(n.code,{children:"OPENSEARCH_PASSWORD"})," set in ",(0,o.jsx)(n.a,{href:"/reference/configuration",children:"Environment variables"})," meets requirements.\nThe password must contain at least 8 characters, and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character that is strong."]}),"\n",(0,o.jsx)(n.h2,{id:"openrag-fails-to-start-from-the-tui-with-operation-not-supported",children:"OpenRAG fails to start from the TUI with operation not supported"}),"\n",(0,o.jsxs)(n.p,{children:["This error occurs when starting OpenRAG with the TUI in ",(0,o.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install",children:"WSL (Windows Subsystem for Linux)"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["The error occurs because OpenRAG is running within a WSL environment, so ",(0,o.jsx)(n.code,{children:"webbrowser.open()"})," can't launch a browser automatically."]}),"\n",(0,o.jsxs)(n.p,{children:["To access the OpenRAG application, open a web browser and enter ",(0,o.jsx)(n.code,{children:"http://localhost:3000"})," in the address bar."]}),"\n",(0,o.jsx)(n.h2,{id:"openrag-installation-fails-with-unable-to-get-local-issuer-certificate",children:"OpenRAG installation fails with unable to get local issuer certificate"}),"\n",(0,o.jsxs)(n.p,{children:["If you are installing OpenRAG on macOS, and the installation fails with ",(0,o.jsx)(n.code,{children:"unable to get local issuer certificate"}),", run the following command, and then retry the installation:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:'open "/Applications/Python VERSION/Install Certificates.command"\n'})}),"\n",(0,o.jsxs)(n.p,{children:["Replace ",(0,o.jsx)(n.code,{children:"VERSION"})," with your installed Python version, such as ",(0,o.jsx)(n.code,{children:"3.13"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"langflow-connection-issues",children:"Langflow connection issues"}),"\n",(0,o.jsxs)(n.p,{children:["Verify the ",(0,o.jsx)(n.code,{children:"LANGFLOW_SUPERUSER"})," credentials set in ",(0,o.jsx)(n.a,{href:"/reference/configuration",children:"Environment variables"})," are correct."]}),"\n",(0,o.jsx)(n.h2,{id:"container-out-of-memory-errors",children:"Container out of memory errors"}),"\n",(0,o.jsxs)(n.p,{children:["Increase Docker memory allocation or use ",(0,o.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/docker-compose-cpu.yml",children:"docker-compose-cpu.yml"})," to deploy OpenRAG."]}),"\n",(0,o.jsx)(n.h2,{id:"memory-issue-with-podman-on-macos",children:"Memory issue with Podman on macOS"}),"\n",(0,o.jsx)(n.p,{children:"If you're using Podman on macOS, you might need to increase VM memory on your Podman machine.\nThis example increases the machine size to 8 GB of RAM, which should be sufficient to run OpenRAG."}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman machine stop\npodman machine rm\npodman machine init --memory 8192 # 8 GB example\npodman machine start\n"})}),"\n",(0,o.jsx)(n.h2,{id:"port-conflicts",children:"Port conflicts"}),"\n",(0,o.jsx)(n.p,{children:"Ensure ports 3000, 7860, 8000, 9200, 5601 are available."}),"\n",(0,o.jsx)(n.h2,{id:"ocr-ingestion-fails-easyocr-not-installed",children:"OCR ingestion fails (easyocr not installed)"}),"\n",(0,o.jsxs)(n.p,{children:["If Docling ingestion fails with an OCR-related error and mentions ",(0,o.jsx)(n.code,{children:"easyocr"})," is missing, this is likely due to a stale ",(0,o.jsx)(n.code,{children:"uv"})," cache."]}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.code,{children:"easyocr"})," is already included as a dependency in OpenRAG's ",(0,o.jsx)(n.code,{children:"pyproject.toml"}),". Project-managed installations using ",(0,o.jsx)(n.code,{children:"uv sync"})," and ",(0,o.jsx)(n.code,{children:"uv run"})," always sync dependencies directly from your ",(0,o.jsx)(n.code,{children:"pyproject.toml"}),", so they should have ",(0,o.jsx)(n.code,{children:"easyocr"})," installed."]}),"\n",(0,o.jsxs)(n.p,{children:["If you're running OpenRAG with ",(0,o.jsx)(n.code,{children:"uvx openrag"}),", ",(0,o.jsx)(n.code,{children:"uvx"})," creates a cached, ephemeral environment that doesn't modify your project. This cache can become stale."]}),"\n",(0,o.jsxs)(n.p,{children:["On macOS, this cache directory is typically a user cache directory such as ",(0,o.jsx)(n.code,{children:"/Users/USER_NAME/.cache/uv"}),"."]}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"To clear the uv cache, run:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"uv cache clean\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Start OpenRAG:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"uvx openrag\n"})}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["If you don't need OCR, you can disable OCR-based processing in your ingestion settings to avoid requiring ",(0,o.jsx)(n.code,{children:"easyocr"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"langflow-container-already-exists-during-upgrade",children:"Upgrade fails due to Langflow container already exists"}),"\n",(0,o.jsxs)(n.p,{children:["If you encounter a ",(0,o.jsx)(n.code,{children:"langflow container already exists"})," error when upgrading OpenRAG, this typically means you upgraded OpenRAG with ",(0,o.jsx)(n.code,{children:"uv"}),", but you didn't remove or upgrade containers from a previous installation."]}),"\n",(0,o.jsx)(n.p,{children:"To resolve this issue, do the following:"}),"\n",(0,o.jsxs)(n.p,{children:["First, try removing only the Langflow container, and then retry the upgrade in the OpenRAG TUI by clicking ",(0,o.jsx)(n.strong,{children:"Status"})," and then ",(0,o.jsx)(n.strong,{children:"Upgrade"}),"."]}),"\n",(0,o.jsxs)(a.A,{groupId:"Container software",children:[(0,o.jsx)(l.A,{value:"Podman",label:"Podman",children:(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Stop the Langflow container:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman stop langflow\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove the Langflow container:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman rm langflow --force\n"})}),"\n"]}),"\n"]})}),(0,o.jsx)(l.A,{value:"Docker",label:"Docker",default:!0,children:(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Stop the Langflow container:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker stop langflow\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove the Langflow container:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker rm langflow --force\n"})}),"\n"]}),"\n"]})})]}),"\n",(0,o.jsx)(n.p,{children:"If reinstalling the Langflow container doesn't resolve the issue, you must reset to a fresh installation by removing all OpenRAG containers and data.\nThen, you can retry the upgrade."}),"\n",(0,o.jsx)(n.admonition,{type:"warning",children:(0,o.jsxs)(n.p,{children:["This is a destructive operation that completely resets your OpenRAG containers and removes all OpenRAG data, including OpenSearch data, uploaded documents, and authentication details.\nYour ",(0,o.jsx)(n.code,{children:".env"})," file is preserved, so your configuration settings remain intact, but all other data is lost."]})}),"\n",(0,o.jsxs)(n.p,{children:["To reset your installation, stop your containers, and then completely remove them.\nAfter removing the containers, retry the upgrade in the OpenRAG TUI by clicking ",(0,o.jsx)(n.strong,{children:"Status"})," and then ",(0,o.jsx)(n.strong,{children:"Upgrade"}),"."]}),"\n",(0,o.jsxs)(a.A,{groupId:"Container software",children:[(0,o.jsx)(l.A,{value:"Podman",label:"Podman",children:(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Stop all running containers:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman stop --all\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all containers, including stopped containers:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman rm --all --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all images:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman rmi --all --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all volumes:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman volume prune --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all networks except the default network:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman network prune --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Clean up any leftover data:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman system prune --all --force --volumes\n"})}),"\n"]}),"\n"]})}),(0,o.jsx)(l.A,{value:"Docker",label:"Docker",default:!0,children:(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Stop all running containers:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker stop $(docker ps -q)\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all containers, including stopped containers:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker rm --force $(docker ps -aq)\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all images:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker rmi --force $(docker images -q)\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all volumes:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker volume prune --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all networks except the default network:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker network prune --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Clean up any leftover data:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker system prune --all --force --volumes\n"})}),"\n"]}),"\n"]})})]}),"\n",(0,o.jsx)(n.h2,{id:"document-ingestion-or-similarity-search-issues",children:"Document ingestion or similarity search issues"}),"\n",(0,o.jsxs)(n.p,{children:["See ",(0,o.jsx)(n.a,{href:"/ingestion#troubleshoot-ingestion",children:"Troubleshoot ingestion"}),"."]})]})}function u(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(p,{...e})}):p(e)}}}]); \ No newline at end of file diff --git a/assets/js/runtime~main.ce59c02b.js b/assets/js/runtime~main.e45e845e.js similarity index 93% rename from assets/js/runtime~main.ce59c02b.js rename to assets/js/runtime~main.e45e845e.js index 178d09f2..af8f022b 100644 --- a/assets/js/runtime~main.ce59c02b.js +++ b/assets/js/runtime~main.e45e845e.js @@ -1 +1 @@ -(()=>{"use strict";var e,a,t,r,o,c={},n={};function d(e){var a=n[e];if(void 0!==a)return a.exports;var t=n[e]={id:e,loaded:!1,exports:{}};return c[e].call(t.exports,t,t.exports,d),t.loaded=!0,t.exports}d.m=c,d.c=n,e=[],d.O=(a,t,r,o)=>{if(!t){var c=1/0;for(b=0;b=o)&&Object.keys(d.O).every(e=>d.O[e](t[f]))?t.splice(f--,1):(n=!1,o0&&e[b-1][2]>o;b--)e[b]=e[b-1];e[b]=[t,r,o]},d.n=e=>{var a=e&&e.__esModule?()=>e.default:()=>e;return d.d(a,{a:a}),a},t=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,d.t=function(e,r){if(1&r&&(e=this(e)),8&r)return e;if("object"==typeof e&&e){if(4&r&&e.__esModule)return e;if(16&r&&"function"==typeof e.then)return e}var o=Object.create(null);d.r(o);var c={};a=a||[null,t({}),t([]),t(t)];for(var n=2&r&&e;("object"==typeof n||"function"==typeof n)&&!~a.indexOf(n);n=t(n))Object.getOwnPropertyNames(n).forEach(a=>c[a]=()=>e[a]);return c.default=()=>e,d.d(o,c),o},d.d=(e,a)=>{for(var t in a)d.o(a,t)&&!d.o(e,t)&&Object.defineProperty(e,t,{enumerable:!0,get:a[t]})},d.f={},d.e=e=>Promise.all(Object.keys(d.f).reduce((a,t)=>(d.f[t](e,a),a),[])),d.u=e=>"assets/js/"+({98:"af920ffe",571:"0ba6a408",1567:"22dd74f7",2076:"common",2272:"749371cc",2668:"eb5b356a",3207:"27b4a875",5490:"71478a5d",5742:"aba21aa0",5750:"d0314b07",6919:"ca2c3c0c",7098:"a7bd4aaa",8401:"17896441",9026:"c8078f0a",9048:"a94703ab",9172:"e633a5ea",9532:"33362219",9647:"5e95c892"}[e]||e)+"."+{98:"bef0ec8d",165:"c26d6a3e",291:"cd97fb9c",571:"dd2959ac",617:"1447cf1d",1e3:"3d4d9f77",1203:"6c86c874",1567:"b9173093",1741:"070da722",1746:"4b809a87",2076:"0dd27f1f",2130:"0c95b4e7",2237:"b77c091f",2272:"6ea54965",2279:"0f9c36da",2291:"8a38f6d3",2325:"d0a48f1d",2334:"dbc94d93",2668:"5a0abd05",2821:"5850139d",3207:"26de3408",3488:"7023792e",3490:"618f86cf",3815:"503d6709",4250:"12e4bf74",4379:"c2ae56a8",4616:"28af5598",4802:"bbffcf8d",4981:"1178b3ff",5480:"82213497",5490:"3a49b919",5742:"35622335",5750:"788dda5b",5901:"a84db486",5955:"6630df13",5996:"aa2ae341",6241:"70145387",6319:"c05e2240",6366:"03bf2589",6567:"44bf886a",6919:"e8524bce",6992:"ce79b8a2",7098:"bc099609",7592:"35906688",7873:"ad98bc5d",7928:"25b35ee3",8142:"538be8cd",8249:"7b519ea1",8401:"11b57c0a",8565:"cea3e8a9",8756:"a32f496b",9026:"d456318f",9032:"8d15afa4",9048:"bfa519e3",9172:"6a095ec9",9412:"74eee71d",9510:"f78dc8f8",9532:"356477a0",9647:"251a99dd"}[e]+".js",d.miniCssF=e=>{},d.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),d.o=(e,a)=>Object.prototype.hasOwnProperty.call(e,a),r={},o="openrag-docs:",d.l=(e,a,t,c)=>{if(r[e])r[e].push(a);else{var n,f;if(void 0!==t)for(var i=document.getElementsByTagName("script"),b=0;b{n.onerror=n.onload=null,clearTimeout(s);var o=r[e];if(delete r[e],n.parentNode&&n.parentNode.removeChild(n),o&&o.forEach(e=>e(t)),a)return a(t)},s=setTimeout(l.bind(null,void 0,{type:"timeout",target:n}),12e4);n.onerror=l.bind(null,n.onerror),n.onload=l.bind(null,n.onload),f&&document.head.appendChild(n)}},d.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},d.p="/",d.gca=function(e){return e={17896441:"8401",33362219:"9532",af920ffe:"98","0ba6a408":"571","22dd74f7":"1567",common:"2076","749371cc":"2272",eb5b356a:"2668","27b4a875":"3207","71478a5d":"5490",aba21aa0:"5742",d0314b07:"5750",ca2c3c0c:"6919",a7bd4aaa:"7098",c8078f0a:"9026",a94703ab:"9048",e633a5ea:"9172","5e95c892":"9647"}[e]||e,d.p+d.u(e)},(()=>{var e={5354:0,1869:0};d.f.j=(a,t)=>{var r=d.o(e,a)?e[a]:void 0;if(0!==r)if(r)t.push(r[2]);else if(/^(1869|5354)$/.test(a))e[a]=0;else{var o=new Promise((t,o)=>r=e[a]=[t,o]);t.push(r[2]=o);var c=d.p+d.u(a),n=new Error;d.l(c,t=>{if(d.o(e,a)&&(0!==(r=e[a])&&(e[a]=void 0),r)){var o=t&&("load"===t.type?"missing":t.type),c=t&&t.target&&t.target.src;n.message="Loading chunk "+a+" failed.\n("+o+": "+c+")",n.name="ChunkLoadError",n.type=o,n.request=c,r[1](n)}},"chunk-"+a,a)}},d.O.j=a=>0===e[a];var a=(a,t)=>{var r,o,c=t[0],n=t[1],f=t[2],i=0;if(c.some(a=>0!==e[a])){for(r in n)d.o(n,r)&&(d.m[r]=n[r]);if(f)var b=f(d)}for(a&&a(t);i{"use strict";var e,a,t,r,o,c={},n={};function d(e){var a=n[e];if(void 0!==a)return a.exports;var t=n[e]={id:e,loaded:!1,exports:{}};return c[e].call(t.exports,t,t.exports,d),t.loaded=!0,t.exports}d.m=c,d.c=n,e=[],d.O=(a,t,r,o)=>{if(!t){var c=1/0;for(b=0;b=o)&&Object.keys(d.O).every(e=>d.O[e](t[f]))?t.splice(f--,1):(n=!1,o0&&e[b-1][2]>o;b--)e[b]=e[b-1];e[b]=[t,r,o]},d.n=e=>{var a=e&&e.__esModule?()=>e.default:()=>e;return d.d(a,{a:a}),a},t=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,d.t=function(e,r){if(1&r&&(e=this(e)),8&r)return e;if("object"==typeof e&&e){if(4&r&&e.__esModule)return e;if(16&r&&"function"==typeof e.then)return e}var o=Object.create(null);d.r(o);var c={};a=a||[null,t({}),t([]),t(t)];for(var n=2&r&&e;("object"==typeof n||"function"==typeof n)&&!~a.indexOf(n);n=t(n))Object.getOwnPropertyNames(n).forEach(a=>c[a]=()=>e[a]);return c.default=()=>e,d.d(o,c),o},d.d=(e,a)=>{for(var t in a)d.o(a,t)&&!d.o(e,t)&&Object.defineProperty(e,t,{enumerable:!0,get:a[t]})},d.f={},d.e=e=>Promise.all(Object.keys(d.f).reduce((a,t)=>(d.f[t](e,a),a),[])),d.u=e=>"assets/js/"+({98:"af920ffe",571:"0ba6a408",1567:"22dd74f7",2076:"common",2272:"749371cc",2668:"eb5b356a",3207:"27b4a875",5490:"71478a5d",5742:"aba21aa0",5750:"d0314b07",6919:"ca2c3c0c",7098:"a7bd4aaa",8401:"17896441",9026:"c8078f0a",9048:"a94703ab",9172:"e633a5ea",9532:"33362219",9647:"5e95c892"}[e]||e)+"."+{98:"140c3203",165:"c26d6a3e",291:"cd97fb9c",571:"dd2959ac",617:"1447cf1d",1e3:"3d4d9f77",1203:"6c86c874",1567:"b9173093",1741:"070da722",1746:"4b809a87",2076:"0dd27f1f",2130:"0c95b4e7",2237:"b77c091f",2272:"6ea54965",2279:"0f9c36da",2291:"8a38f6d3",2325:"d0a48f1d",2334:"dbc94d93",2668:"5256f349",2821:"5850139d",3207:"26de3408",3488:"7023792e",3490:"618f86cf",3815:"503d6709",4250:"12e4bf74",4379:"c2ae56a8",4616:"28af5598",4802:"bbffcf8d",4981:"1178b3ff",5480:"82213497",5490:"3a49b919",5742:"35622335",5750:"7b0b4caa",5901:"a84db486",5955:"6630df13",5996:"aa2ae341",6241:"70145387",6319:"c05e2240",6366:"03bf2589",6567:"44bf886a",6919:"e8524bce",6992:"ce79b8a2",7098:"bc099609",7592:"35906688",7873:"ad98bc5d",7928:"25b35ee3",8142:"538be8cd",8249:"7b519ea1",8401:"11b57c0a",8565:"cea3e8a9",8756:"a32f496b",9026:"f1c0e5b8",9032:"8d15afa4",9048:"bfa519e3",9172:"6a095ec9",9412:"74eee71d",9510:"f78dc8f8",9532:"356477a0",9647:"251a99dd"}[e]+".js",d.miniCssF=e=>{},d.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),d.o=(e,a)=>Object.prototype.hasOwnProperty.call(e,a),r={},o="openrag-docs:",d.l=(e,a,t,c)=>{if(r[e])r[e].push(a);else{var n,f;if(void 0!==t)for(var i=document.getElementsByTagName("script"),b=0;b{n.onerror=n.onload=null,clearTimeout(s);var o=r[e];if(delete r[e],n.parentNode&&n.parentNode.removeChild(n),o&&o.forEach(e=>e(t)),a)return a(t)},s=setTimeout(l.bind(null,void 0,{type:"timeout",target:n}),12e4);n.onerror=l.bind(null,n.onerror),n.onload=l.bind(null,n.onload),f&&document.head.appendChild(n)}},d.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},d.p="/",d.gca=function(e){return e={17896441:"8401",33362219:"9532",af920ffe:"98","0ba6a408":"571","22dd74f7":"1567",common:"2076","749371cc":"2272",eb5b356a:"2668","27b4a875":"3207","71478a5d":"5490",aba21aa0:"5742",d0314b07:"5750",ca2c3c0c:"6919",a7bd4aaa:"7098",c8078f0a:"9026",a94703ab:"9048",e633a5ea:"9172","5e95c892":"9647"}[e]||e,d.p+d.u(e)},(()=>{var e={5354:0,1869:0};d.f.j=(a,t)=>{var r=d.o(e,a)?e[a]:void 0;if(0!==r)if(r)t.push(r[2]);else if(/^(1869|5354)$/.test(a))e[a]=0;else{var o=new Promise((t,o)=>r=e[a]=[t,o]);t.push(r[2]=o);var c=d.p+d.u(a),n=new Error;d.l(c,t=>{if(d.o(e,a)&&(0!==(r=e[a])&&(e[a]=void 0),r)){var o=t&&("load"===t.type?"missing":t.type),c=t&&t.target&&t.target.src;n.message="Loading chunk "+a+" failed.\n("+o+": "+c+")",n.name="ChunkLoadError",n.type=o,n.request=c,r[1](n)}},"chunk-"+a,a)}},d.O.j=a=>0===e[a];var a=(a,t)=>{var r,o,c=t[0],n=t[1],f=t[2],i=0;if(c.some(a=>0!==e[a])){for(r in n)d.o(n,r)&&(d.m[r]=n[r]);if(f)var b=f(d)}for(a&&a(t);i Chat in OpenRAG | OpenRAG - + diff --git a/docker/index.html b/docker/index.html index 0ff4700d..34e3c364 100644 --- a/docker/index.html +++ b/docker/index.html @@ -4,7 +4,7 @@ Install OpenRAG containers | OpenRAG - + diff --git a/index.html b/index.html index 8fb7d627..cc02125d 100644 --- a/index.html +++ b/index.html @@ -4,7 +4,7 @@ What is OpenRAG? | OpenRAG - + diff --git a/ingestion/index.html b/ingestion/index.html index c4da25a5..24a269b8 100644 --- a/ingestion/index.html +++ b/ingestion/index.html @@ -4,7 +4,7 @@ Ingest knowledge | OpenRAG - + diff --git a/install/index.html b/install/index.html index 2dcac678..563cb9f8 100644 --- a/install/index.html +++ b/install/index.html @@ -4,7 +4,7 @@ Install OpenRAG with TUI | OpenRAG - + @@ -323,40 +323,59 @@ For more information, see Manage Op If you installed OpenRAG with uvx, run uvx openrag.

Manage OpenRAG containers with the TUI​

After installation, the TUI can deploy, manage, and upgrade your OpenRAG containers.

-

Start all services​

-

Click Start All Services to start the OpenRAG containers. -The TUI 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. -The TUI then pulls the images and deploys the containers with the following command.

-
docker compose up -d
-

If images are missing, the TUI runs docker compose pull, then runs docker compose up -d.

+

Diagnostics​

+

The Diagnostics menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security.

Status​

The Status menu displays information on your container deployment. Here you can check container health, find your service ports, view logs, and upgrade your containers.

-

To view streaming logs, select the container you want to view, and press l. -To copy your logs, click Copy to Clipboard.

-

To upgrade your containers, click Upgrade. -Upgrade runs docker compose pull and then docker compose up -d --force-recreate. -For more information, see Upgrade OpenRAG containers with the TUI.

-

To reset your containers, click Reset. -Reset gives you a completely fresh start. -Reset deletes all of your data, including OpenSearch data, uploaded documents, and authentication. -Reset runs two commands. -It first stops and removes all containers, volumes, and local images.

-
docker compose down --volumes --remove-orphans --rmi local
-

When the first command is complete, OpenRAG removes any additional Docker objects with prune.

-
docker system prune -f
-

Native services status​

-

A native service in OpenRAG refers to a service run locally on your machine, and not within a container. -The docling serve process is a native service in OpenRAG, because it's a document processing service that is run on your local machine, and controlled separately from the containers.

-

To start or stop docling serve or any other native services, in the TUI Status menu, click Stop or Restart.

-

To view the status, port, or PID of a native service, in the TUI main menu, click Status.

+
    +
  • +

    Logs: To view streaming logs, select the container you want to view, and press l. +To copy the logs, click Copy to Clipboard.

    +
    • +
  • +

    Upgrade: Check for updates. For more information, see upgrade OpenRAG.

    +
    • +
  • +

    Reset: This is a destructive action that resets your containers.

    +
    • +
  • +

    Native services: From the Status menu, you can view the status, port, and process ID (PID) of the OpenRAG native services. +You can also click Stop or Restart to stop and start OpenRAG 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.

    +
    • +
+

Reset containers​

+
warning

This is a destructive action that destroys and recreates all of your OpenRAG containers.

+

To destroy and recreate your OpenRAG containers, go to the TUI Status menu, and then click Reset.

+

The Reset function runs two commands. First, it stops and removes all containers, volumes, and local images:

+
docker compose down --volumes --remove-orphans --rmi local
+

Then, it removes any additional Docker objects with docker system prune -f.

+

If you reset your containers as part of reinstalling OpenRAG, continue the reinstallation process after resetting the containers.

+

Start all services​

+

On the TUI main page, click Start All Services to start the OpenRAG containers and launch OpenRAG itself.

+

When you start all services, the following processes happen:

+
    +
  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.

    +
    2. +
  2. +

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

    +
    3. +
  3. +

    OpenRAG deploys the containers with docker compose up -d.

    +
    4. +

Upgrade OpenRAG​

-

To upgrade OpenRAG, upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers using the OpenRAG TUI.

-

Upgrading the OpenRAG Python package updates the TUI and Python code, but container versions are controlled separately by environment variables in your .env file.

-

Upgrade OpenRAG python package​

-

Use the following steps to upgrade the OpenRAG Python package to the latest version from PyPI. -After upgrading the Python package, you should also upgrade your OpenRAG containers.

-

If you installed OpenRAG using the automatic installer or uvx, follow these steps to upgrade:

    +

    To upgrade OpenRAG, upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers.

    +

    This is a two part process because upgrading the OpenRAG Python package updates the TUI and Python code, but the container versions are controlled by environment variables in your .env file.

    +
      +
    1. +

      Stop your OpenRAG containers: In the OpenRAG TUI, go to the Status menu, and then click Stop Services.

      +
      2. +
    2. +

      Upgrade the OpenRAG Python package to the latest version from PyPI.

      +

      Use these steps to upgrade the Python package if you installed OpenRAG using the automatic installer or uvx:

      1. Navigate to your OpenRAG workspace directory:

        cd openrag-workspace
        @@ -367,10 +386,7 @@ After upgrading the Python package, you should also 
        uvx --from openrag==0.1.33 openrag
      3. -
    3. -

      After upgrading the Python package, upgrade your containers.

      -
      4. -
-
  • -

    After upgrading the Python package, upgrade your containers.

    -
    • -
    -
  • -

    After upgrading the Python package, upgrade your containers.

    -
    • -

    Upgrade OpenRAG containers with the TUI​

    -

    After upgrading the OpenRAG Python package, upgrade your containers to ensure they match the latest version. -Upgrade runs docker compose pull, which pulls container images based on versions specified in your .env file. -OPENRAG_VERSION is set to latest by default, so it pulls the latest available container images.

    -
      -
    1. In the OpenRAG TUI, click Status, and then click Upgrade.
      2. -
    2. When the upgrade completes, close the Status window and continue using OpenRAG.
      3. + +
    3. +

      Start the upgraded OpenRAG containers: In the OpenRAG TUI, click Start All Services, and then wait while the containers start.

      +

      After upgrading the Python package, OpenRAG runs docker compose pull to get the appropriate container images matching the version specified in your OpenRAG .env file. Then, it recreates the containers with the new images using docker compose up -d --force-recreate.

      +

      In the .env file, the OPENRAG_VERSION environment variable is set to latest by default, which it pulls the latest available container images. +To pin a specific container image version, you can set OPENRAG_VERSION to the desired container image version, such as OPENRAG_VERSION=0.1.33.

      +

      However, when you upgrade the Python package, OpenRAG automatically attempts to keep the OPENRAG_VERSION synchronized with the Python package version. +You might need to edit the .env file after upgrading the Python package to enforce a different container version. +The TUI warns you if it detects a version mismatch.

      +

      If you get an error that langflow container already exists error during upgrade, see Langflow container already exists during upgrade.

      +
      4. +
    4. +

      When the upgrade process is complete, you can close the Status window and continue using OpenRAG.

      +
    -

    If you encounter a langflow container already exists error during upgrade, see Langflow container already exists during upgrade in the troubleshooting guide.

    -

    To pin container versions to a specific release other than latest, set the OPENRAG_VERSION in your .env file:

    -
    OPENRAG_VERSION=0.1.33
    -

    For more information, see System settings environment variables.

    -

    Diagnostics​

    -

    The Diagnostics menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security.

    Reinstall OpenRAG​

    To reinstall OpenRAG with a completely fresh setup:

    1. -

      Reset your containers using the Reset button in the TUI status menu. -This removes all containers, volumes, and data.

      +

      In the TUI Status menu, reset your containers to destroy the existing OpenRAG containers and their data.

    2. -

      Optional: Delete your project's .env file. -The Reset operation doesn't remove your project's .env file, so your passwords, API keys, and OAuth settings can be preserved. -If you delete the .env file, run the Set up OpenRAG with the TUI process again to create a new configuration.

      +

      Optional: Delete your project's .env file.

      +

      The Reset operation doesn't remove your project's .env file, so your passwords, API keys, and OAuth settings can be preserved. +If you delete the .env file, you must run the Set up OpenRAG with the TUI process again to create a new configuration file.

    3. -

      In the TUI Setup menu, follow these steps from Basic Setup:

      +

      Optional: Delete your OpenSearch knowledge base by deleting the contents of the ./opensearch-data folder in your OpenRAG installation directory.

      +
      4. +
    4. +

      In the TUI Setup menu, repeat the Basic Setup process:

      1. Click Start All Services to pull container images and start them.
      2. Under Native Services, click Start to start the Docling service.
        3. @@ -441,7 +454,8 @@ If you delete the .env file, run the Set
      3. Continue with application onboarding.
      5. -