OpenQuery/docs/installation.md

Installation Guide

This guide covers how to build, install, and configure OpenQuery on your system.

📋 Table of Contents

1. Prerequisites
2. Quick Install
3. Manual Build
4. Platform-Specific Instructions
5. Post-Installation
6. Verification
7. Uninstallation

Prerequisites

Required Software

• .NET SDK 10.0 or later
  • Download from dotnet.microsoft.com
  • Verify: dotnet --version should show 10.x or higher

External Services (Setup Required)

1. SearxNG Instance - Metasearch engine

   • Docker (Recommended):

     docker run -d \
       --name searxng \
       -p 8002:8080 \
       -v searxng-data:/etc/searxng \
       searxng/searxng:latest
     

   • Access at http://localhost:8002

   • Alternative: Use a public SearxNG instance from searx.space

2. OpenRouter API Key - AI model provider

   • Sign up at openrouter.ai
   • Get your API key from dashboard
   • Free tier available with rate limits

Quick Install

The easiest way to get OpenQuery up and running:

# 1. Clone the repository
git clone <your-repo-url>
cd OpenQuery

# 2. Make install script executable and run
chmod +x install.sh
./install.sh

# 3. Configure your API key
openquery configure -i

# 4. Test it
openquery "Hello world"

What the install script does:

• Builds the project in Release mode
• Publishes as self-contained AOT binary
• Copies to ~/.local/bin/OpenQuery (Linux/macOS)
• Creates config directory ~/.config/openquery/

Manual Build

If you prefer to build manually or need a specific platform:

Step 1: Restore Dependencies

dotnet restore

Step 2: Build

dotnet build -c Release

Step 3: Publish

For Current Platform (Self-Contained AOT)

dotnet publish -c Release \
  --self-contained true \
  /p:PublishAot=true

The binary will be at:

bin/Release/net10.0/<rid>/publish/OpenQuery

For Specific Platform (Cross-Compilation)

Runtime Identifiers (RIDs):

Platform	RID
Linux x64	linux-x64
Linux ARM64	linux-arm64
macOS x64	osx-x64
macOS ARM64	osx-arm64
Windows x64	win-x64
Windows ARM64	win-arm64

Example for Linux x64:

dotnet publish -c Release \
  -r linux-x64 \
  --self-contained true \
  /p:PublishAot=true

Step 4: Deploy

Copy the binary to a directory in your PATH:

# Linux/macOS
sudo cp bin/Release/net10.0/linux-x64/publish/OpenQuery /usr/local/bin/
chmod +x /usr/local/bin/OpenQuery

# Windows (PowerShell as Admin)
Copy-Item bin\Release\net10.0\win-x64\publish\OpenQuery.exe C:\Program Files\OpenQuery\

Or use a local bin directory:

mkdir -p ~/.local/bin
cp bin/Release/net10.0/linux-x64/publish/OpenQuery ~/.local/bin/
# Add to PATH if not already: export PATH="$HOME/.local/bin:$PATH"

Platform-Specific Instructions

Linux

Ubuntu/Debian

# Install .NET SDK 10.0
wget https://dot.net/v10/dotnet-install.sh -O dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --channel 10.0

# Add to PATH
export PATH="$HOME/.dotnet:$PATH"

# Build and install (as shown above)

With Systemd Service (Optional)

If you run SearxNG locally, you might want it as a service:

# Create systemd service for SearxNG (if using Docker)
sudo nano /etc/systemd/system/searxng.service

[Unit]
Description=SearxNG Search Engine
Requires=docker.service
After=docker.service

[Service]
Restart=always
ExecStart=/usr/bin/docker start -a searxng
ExecStop=/usr/bin/docker stop -t 2 searxng

[Install]
WantedBy=multi-user.target

sudo systemctl enable searxng
sudo systemctl start searxng

macOS

Homebrew Install (if .NET available)

brew install dotnet-sdk

M1/M2 (ARM64) Notes

• Use RID: osx-arm64
• Ensure you have the ARM64 version of .NET SDK

Windows

Using Winget (Windows 10/11)

winget install Microsoft.DotNet.SDK.10

Manual Install

1. Download installer from dotnet.microsoft.com
2. Run installer
3. Verify in PowerShell:

   dotnet --version
   

Building

dotnet publish -c Release -r win-x64 --self-contained true /p:PublishAot=true

Post-Installation

1. Verify SearxNG is Running

curl "http://localhost:8002/search?q=test&format=json"

Expected: JSON response with results array.

2. Configure OpenQuery

# Interactive setup
openquery configure -i

# Or via environment variables
setx OPENROUTER_API_KEY "sk-or-..."  # Windows
export OPENROUTER_API_KEY="sk-or-..." # Linux/macOS

3. Optional: Set Defaults

openquery configure --queries 5 --chunks 4 --results 10

Verification

Test Installation

# Check binary exists and is executable
which openquery  # Linux/macOS
where openquery  # Windows

# If installed as OpenQuery (capital O)
which OpenQuery

Test Configuration

# Should show your config or defaults
cat ~/.config/openquery/config

Test the System

# Simple query (should work with any API key)
openquery "What is 2+2?"

# More complex query
openquery -v "What are the benefits of exercise?"

Expected output:

• Spinner animation with status updates
• Streaming answer from the AI
• Citations like [Source 1](url) in the answer

Uninstallation

Using Uninstall Script

chmod +x uninstall.sh
./uninstall.sh

The script will:

• Remove binary from ~/.local/bin/
• Ask if you want to delete config directory

Manual Removal

# Remove binary
rm ~/.local/bin/OpenQuery

# Remove config (optional)
rm -r ~/.config/openquery

Remove SearxNG (if no longer needed)

docker rm -f searxng
docker volume rm searxng-data

Advanced Build Options

Reduce Binary Size

Edit OpenQuery.csproj:

<PropertyGroup>
  <PublishAot>true</PublishAot>
  <InvariantGlobalization>true</InvariantGlobalization>  <!-- Already set -->
  <StripSymbols>true</StripSymbols>
</PropertyGroup>

Debug Build

dotnet build -c Debug
dotnet run -- "your question"

With Symbols (for debugging)

dotnet publish -c Release -r linux-x64 \
  --self-contained true \
  /p:PublishAot=true \
  /p:DebugType=portable

Troubleshooting Installation

"dotnet: command not found"

• Add .dotnet to PATH: export PATH="$HOME/.dotnet:$PATH"
• Restart terminal or source shell config

"The SDK 'Microsoft.NET.Sdk' was not found"

• .NET SDK not installed correctly
• Re-run installer or use dotnet-install.sh

AOT Build Fails

• Some platforms may not support AOT yet
• Remove /p:PublishAot=true to use JIT
• Check .NET AOT support

Docker Pull Fails (SearxNG)

# Pull image separately first
docker pull searxng/searxng:latest
# Then run container
docker run -d --name searxng -p 8002:8080 searxng/searxng

Port 8002 Already in Use

Change port in docker command:

docker run -d --name searxng -p 8080:8080 searxng/searxng
# Then set SEARXNG_URL=http://localhost:8080

Next Steps

After successful installation:

1. Configure OpenQuery
2. Learn how to use it
3. Read the Architecture to understand how it works

---

Need help? See Troubleshooting or open an issue.