OpenQuery/docs/installation.md

# Installation Guide

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

## 📋 Table of Contents

1. [Prerequisites](#prerequisites)
2. [Quick Install](#quick-install)
3. [Manual Build](#manual-build)
4. [Platform-Specific Instructions](#platform-specific-instructions)
5. [Post-Installation](#post-installation)
6. [Verification](#verification)
7. [Uninstallation](#uninstallation)

## Prerequisites

### Required Software
- **.NET SDK 10.0** or later
  - Download from [dotnet.microsoft.com](https://dotnet.microsoft.com/download)
  - Verify: `dotnet --version` should show 10.x or higher

### External Services (Setup Required)
1. **SearxNG Instance** - Metasearch engine
   - **Docker (Recommended)**:
     ```bash
     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](https://searx.space)
   
2. **OpenRouter API Key** - AI model provider
   - Sign up at [openrouter.ai](https://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:

```bash
# 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
```bash
dotnet restore
```

### Step 2: Build
```bash
dotnet build -c Release
```

### Step 3: Publish

#### For Current Platform (Self-Contained AOT)
```bash
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:
```bash
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:

```bash
# 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:
```bash
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
```bash
# 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:
```bash
# Create systemd service for SearxNG (if using Docker)
sudo nano /etc/systemd/system/searxng.service
```

```ini
[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
```

```bash
sudo systemctl enable searxng
sudo systemctl start searxng
```

### macOS

#### Homebrew Install (if .NET available)
```bash
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)
```powershell
winget install Microsoft.DotNet.SDK.10
```

#### Manual Install
1. Download installer from [dotnet.microsoft.com](https://dotnet.microsoft.com/download)
2. Run installer
3. Verify in PowerShell:
   ```powershell
   dotnet --version
   ```

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

## Post-Installation

### 1. Verify SearxNG is Running
```bash
curl "http://localhost:8002/search?q=test&format=json"
```

Expected: JSON response with results array.

### 2. Configure OpenQuery
```bash
# 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
```bash
openquery configure --queries 5 --chunks 4 --results 10
```

## Verification

### Test Installation
```bash
# Check binary exists and is executable
which openquery  # Linux/macOS
where openquery  # Windows

# If installed as OpenQuery (capital O)
which OpenQuery
```

### Test Configuration
```bash
# Should show your config or defaults
cat ~/.config/openquery/config
```

### Test the System
```bash
# 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
```bash
chmod +x uninstall.sh
./uninstall.sh
```

The script will:
- Remove binary from `~/.local/bin/`
- Ask if you want to delete config directory

### Manual Removal
```bash
# Remove binary
rm ~/.local/bin/OpenQuery

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

### Remove SearxNG (if no longer needed)
```bash
docker rm -f searxng
docker volume rm searxng-data
```

## Advanced Build Options

### Reduce Binary Size
Edit `OpenQuery.csproj`:
```xml
<PropertyGroup>
  <PublishAot>true</PublishAot>
  <InvariantGlobalization>true</InvariantGlobalization>  <!-- Already set -->
  <StripSymbols>true</StripSymbols>
</PropertyGroup>
```

### Debug Build
```bash
dotnet build -c Debug
dotnet run -- "your question"
```

### With Symbols (for debugging)
```bash
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](https://docs.microsoft.com/dotnet/core/deploying/native-aot/)

### Docker Pull Fails (SearxNG)
```bash
# 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:
```bash
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](configuration.md)
2. [Learn how to use it](usage.md)
3. Read the [Architecture](architecture.md) to understand how it works

---

**Need help?** See [Troubleshooting](troubleshooting.md) or open an issue.