docs/quick-start.md

Quick Start

Prerequisites

• Docker Desktop or Docker Engine
• Node.js LTS (for local development only)
• Git
• Modern browser with WebGPU support (for optimal AI performance)

Installation & Running

Development (Recommended for Contributing)

# Clone the repository
git clone https://github.com/felladrin/MiniSearch.git
cd MiniSearch

# Start all services (SearXNG, Node.js app with HMR)
docker compose up

Access the application at http://localhost:7861 (HMR) or http://localhost:7860 (main)

The development server includes:

• Hot Module Replacement (HMR) on port 7861 for instant code changes
• Full dev tools and source maps
• Live code watching with volume mounts
• Integrated SearXNG search service
• Biome formatting and linting on save

Production

# Build and start production containers
docker compose -f docker-compose.production.yml up --build

Access at http://localhost:7860

Production mode:

• Pre-built optimized assets
• No dev tools or HMR
• Optimized Docker layer caching

First Configuration

No Configuration Required (Default)

MiniSearch works out of the box with browser-based AI inference. Search works immediately, and AI responses use on-device models via WebLLM (WebGPU).

Optional: Enable AI Response

1. Open the application
2. Click Settings (gear icon)
3. Toggle Enable AI Response
4. Choose inference type:
   • Browser (recommended): Uses WebLLM with WebGPU or Wllama for local processing
   • Internal API: Configure OpenAI-compatible endpoint
   • AI Horde: Pre-configured distributed computing
5. The app will download ~300MB-1GB model files on first use (browser mode)
6. Subsequent loads are instant (cached in IndexedDB)

Optional: Restrict Access

Add access keys to prevent unauthorized usage:

# Create .env file
echo 'ACCESS_KEYS="my-secret-key-1,my-secret-key-2"' > .env

# Restart containers
docker compose up --build

Users will be prompted to enter an access key before using the app.

Development Without Docker

# Install dependencies
npm install

# Start development server
npm run dev

# In another terminal, start SearXNG (or use standalone instance)
# See SearXNG documentation for setup

Access at http://localhost:7860

Note: Running without Docker requires manual SearXNG setup and environment configuration.

Verification

Test Search

1. Enter any query in the search box
2. Press Enter or click Search
3. Results should appear within 2-5 seconds

Test AI Response

1. Toggle "Enable AI Response" in Settings
2. Search for "What is quantum computing?"
3. After search results load, an AI-generated response should appear with citations

Test Chat

1. After getting an AI response
2. Type a follow-up question like "Tell me more"
3. The AI should respond using conversation context

Common Issues

Issue: Search returns no results

Solution: Verify SearXNG is running. Check container logs:

docker compose logs searxng

Issue: AI response never loads

Solution: Check browser console for errors. Common causes:

• WebGPU not supported (app will automatically fall back to Wllama)
• Model download blocked by firewall or CORS
• Insufficient disk space for model caching
• Browser extensions blocking WebAssembly
• Try switching inference types in Settings

Issue: Access key not working

Solution: Ensure ACCESS_KEYS is set in .env file and containers were rebuilt with --build flag.

Issue: Port already in use

Solution: Change ports in docker-compose.yml:

ports:
  - "7862:7860"  # Use 7862 instead of 7861

Next Steps

• Customize AI: See docs/ai-integration.md for model selection and inference options
• Configure: See docs/configuration.md for all environment variables and settings
• Architecture: See docs/overview.md for system design
• Contributing: See docs/pull-requests.md for development workflow