openrag_install

When the user asks to install OpenRAG, follow this workflow in order.

Initial assessment phase

Before starting installation, check for an existing OpenRAG installation:

Check if ~/.openrag/tui/.env exists
If it exists:
- Read the configuration to understand what's already set up
- Check if services are currently running with docker compose ps for the generated OpenRAG compose file, or by filtering on the compose project/labels instead of docker ps --filter "name=openrag"
- Inform the user about the existing installation
- Ask if they want to:
  - Start existing services (if stopped)
  - Reconfigure existing installation
  - Verify existing installation
  - Proceed with fresh installation (will use existing config)
If no existing installation found, proceed with fresh installation workflow

Primary goals

Produce a grounded installation spec in requirements.md
Break the work into executable tasks in todo.md
Implement all tasks that can be completed in the current environment
Pause for user action when a task requires credentials, configuration choices, or other interactive input
Verify the installation locally until http://localhost:3000 launches without startup errors and http://localhost:5001/docs is reachable
Treat browser onboarding after the app launches as user-owned and outside installation completion

Requirements authoring phase

First, create or update requirements.md using the official OpenRAG installation documentation:

Use https://docs.openr.ag/install-options as the source of truth
Do not hallucinate implementation details that are not supported by the documentation or the local environment
Prioritize the minimal installation path and the fewest necessary steps
Organize requirements into logical categories
Use numbered identifiers in the format REQ-001, REQ-002, and so on
Include acceptance criteria for every requirement
Include requirements covering:
- System prerequisites and resource requirements
- Configuration and security
- Platform compatibility
- Edge cases and troubleshooting considerations

Include the following specific requirement in the spec:

Non-containerized service: docling-serve on port 5001
It is a required bundled Python service
It is bundled with OpenRAG and managed by uvx or uv
It should be automatically started and stopped via uvx openrag
It should be available at http://localhost:5001/docs
Verification should include either lsof -i :5001 or curl http://localhost:5001/docs
Do not immediately flag failure if http://localhost:5001/docs is not ready right after startup; wait and re-check because docling-serve may come up after the main OpenRAG services

Requirements review phase

After drafting requirements.md:

Review it for gaps, ambiguities, contradictions, and missing edge cases
Tighten vague language
Add missing acceptance criteria where needed
Update the file before moving to implementation planning

Task planning and execution phase

After requirements.md is stable:

Read requirements.md
Create todo.md that breaks the work into concrete tasks
Implement each task that is relevant to the current environment
For user-interactive tasks, do not guess or fabricate values; instruct the user to complete the step and confirm when done
Mark tasks complete in todo.md only after they pass validation
If troubleshooting partially started OpenRAG services, stop all services before attempting to start them again

CRITICAL: Interactive Terminal Limitation

Most agent shell tools cannot drive interactive terminal applications that require user input. This includes any command that renders a TUI, prompts for passwords, or expects arrow-key navigation.

When the installation reaches the point where uvx openrag needs to be run:

What NOT to do:

Do NOT attempt to run uvx openrag through the agent's shell tool expecting to interact with it
Do NOT try to use background processes for interactive commands
Do NOT assume you can send input to an already-running interactive terminal

What TO do:

Explicitly instruct the user to open a NEW terminal window/tab outside the agent's shell
Provide the exact command to run: uvx --python 3.13 openrag
Give step-by-step instructions for what they will see and how to respond:
- First run: Select "Reconfigure" (option 2)
- Set OpenSearch Admin password (MUST be strong)
- Set Langflow Admin password (can autogenerate or manual)
- Accept defaults for other prompts (press 'N' or skip)
- Return to menu and select "Start services" (option 1)
- Wait for "Services are running" message
Wait for user confirmation that they completed the steps
After confirmation, verify the installation using non-interactive commands:
- Check container status: docker ps --filter "name=openrag"
- Verify ports: lsof -i :3000 and lsof -i :5001
- Test endpoints: curl http://localhost:3000 and curl http://localhost:5001/docs

Example user instruction format:

The next step requires running an interactive command that I cannot control directly.

Please open a NEW terminal window (separate from this agent session) and run:

    uvx --python 3.13 openrag

You will see a menu. Follow these steps:
1. Type '2' and press Enter (Reconfigure)
2. Enter a STRONG OpenSearch Admin password (write it down!)
3. Enter Langflow Admin password (or autogenerate)
4. Press 'N' or skip for other prompts
5. Type '1' and press Enter (Start services)
6. Wait for "Services are running" message

Once complete, come back here and confirm: "Configuration and services started successfully"

User-interactive guidance

When a task requires user input, secret values, or interactive terminal control:

Tell the user exactly what action they need to take
Explain how you will verify completion
Wait for confirmation before proceeding
Explicitly instruct the user that the OpenSearch password must be strong, defaults can be used for all other values to get started quickly
ALWAYS instruct users to run uvx openrag in a separate terminal outside the agent's shell
Provide explicit step-by-step guidance for what they will see and how to respond
After user confirms completion, verify using non-interactive commands

Safety and accuracy rules

Prefer official documentation and observed local state over assumptions
Do not invent ports, services, commands, configuration keys, or file locations unless verified
Keep installation steps as simple and minimal as possible
Use secure defaults and align with OWASP-style handling of secrets and credentials
Call out platform-specific limitations when they affect installation or verification
Be explicit that the agent's shell cannot drive interactive TUI applications
Never attempt to run uvx openrag interactively through the agent's shell
Do not treat delayed startup alone as a failure condition when output is still progressing normally

Verification and completion

Before considering the installation complete:

Verify all completed tasks against the acceptance criteria in requirements.md
Confirm required services are running
Verify http://localhost:3000 first
Wait briefly, then verify docling-serve is reachable at http://localhost:5001/docs
If OpenRAG services were restarted during troubleshooting, verify they are all healthy after the clean restart
Only escalate to troubleshooting if repeated checks fail after a reasonable delay or the terminal shows explicit errors
Consider the installation complete once the app launches without startup errors on http://localhost:3000 and http://localhost:5001/docs is reachable
Do not treat provider selection or browser onboarding completion as part of installation completion

Collaboration style

Be explicit about what is known, what is inferred, and what still needs verification
Surface ambiguities early and resolve them before implementation
Keep outputs structured and easy to audit
Iterate on requirements.md and todo.md as new validated information is discovered
Clearly communicate when user action is required in a separate terminal