docs: add comprehensive documentation with README and detailed guides

- Add user-friendly README.md with quick start guide - Create docs/ folder with structured technical documentation: - installation.md: Build and setup instructions - configuration.md: Complete config reference - usage.md: CLI usage guide with examples - architecture.md: System design and patterns - components/: Deep dive into each component (OpenQueryApp, SearchTool, Services, Models) - api/: CLI reference, environment variables, programmatic API - troubleshooting.md: Common issues and solutions - performance.md: Latency, throughput, and optimization - All documentation fully cross-referenced with internal links - Covers project overview, architecture, components, APIs, and support See individual files for complete documentation.
2026-03-19 10:01:58 +01:00
parent b28d8998f7
commit 65ca2401ae
16 changed files with 7073 additions and 0 deletions
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -0,0 +1,358 @@
+# 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.