SearXNG Proxy

A simple proxy server for SearXNG meta-search engine with authentication, designed to provide secure access to privacy-respecting search.

📋 Table of Contents

✨ Features
🚀 Quick Start
🔌 API Usage
☁️ Cloudflare Tunnel Setup
⚙️ Configuration
🧪 Running Tests
📂 Project Structure
🔒 Security Notes
🔧 Troubleshooting
📄 License
🤝 Contributing

✨ Features

API Key Authentication: Secure access control via Bearer tokens
Cloudflare Tunnel Integration: Built-in support for secure external access
Docker Support: Complete containerized setup with Docker Compose
Health Check Endpoints: Monitor proxy status (authenticated + unauthenticated)
Multi-Engine Search: Aggregates results from Google, Bing, DuckDuckGo, Qwant, Yahoo, Brave
Flexible Configuration: Environment-based configuration
Comprehensive Tests: Unit and integration tests with Jest
Unlimited Searches: No rate limits (self-hosted)
JSON & HTML Output: Support for both JSON API and HTML responses

🚀 Quick Start

📋 Prerequisites

Docker and Docker Compose
Node.js 18+ (for local development)
Cloudflare account (optional, for tunnel)

🐳 Docker Deployment (Recommended)

Clone the repository:

git clone https://github.com/loonylabs-dev/searxng-proxy.git
cd searxng-proxy

Set up environment:

cp .env.example .env
# Edit .env with your API key

Generate API Key:

# Generate a secure API key
openssl rand -base64 32

# Add to .env:
# API_KEY=your_generated_key_here

Start services:
```
docker-compose up -d
```

Verify:

# Check services
docker-compose ps

# Test local endpoint (requires port mapping, see Configuration)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:3000/search?q=test&format=json"

💻 Local Development

Install dependencies:
```
npm install
```

Set up environment:

cp .env.example .env
# Edit .env with your configuration (use SEARXNG_URL=http://localhost:8080)

Start SearXNG (Docker):

docker run -d -p 8080:8080 -v ./searxng:/etc/searxng searxng/searxng:latest

Start the proxy:

npm run dev          # Development mode
# or
npm run build && npm start  # Production mode

🔌 API Usage

The proxy provides secure access to SearXNG with API key authentication.

🔐 Authentication

All requests (except /healthz) require a Bearer token:

Authorization: Bearer YOUR_API_KEY

📍 Endpoints

`GET /search`

Search with SearXNG.

Parameters:

q (required) - Search query
format (optional) - Response format: json (default) or html
engines (optional) - Specific engines to use
Additional SearXNG parameters (language, time_range, etc.)

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://search.loonylabs.dev/search?q=typescript+best+practices&format=json"

Response (JSON):

{
  "query": "typescript best practices",
  "number_of_results": 42,
  "results": [
    {
      "title": "TypeScript Best Practices",
      "url": "https://example.com/typescript-best-practices",
      "content": "Learn the best practices for TypeScript...",
      "engine": "google"
    }
  ]
}

`GET /health`

Health check (requires authentication).

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://search.loonylabs.dev/health"

Response:

{
  "status": "ok",
  "service": "searxng-proxy"
}

`GET /healthz`

Health check (no authentication required - for Cloudflare monitoring).

curl "https://search.loonylabs.dev/healthz"

Response:

{
  "status": "ok",
  "service": "searxng-proxy"
}

🎯 Integration Example

// searxng-client.ts
import fetch from 'node-fetch';

const SEARXNG_URL = 'https://search.loonylabs.dev';
const SEARXNG_API_KEY = process.env.SEARXNG_API_KEY;

export async function search(query: string, maxResults = 10) {
  const response = await fetch(
    `${SEARXNG_URL}/search?q=${encodeURIComponent(query)}&format=json`,
    {
      headers: {
        'Authorization': `Bearer ${SEARXNG_API_KEY}`,
      },
    }
  );

  if (!response.ok) {
    throw new Error(`Search failed: ${response.statusText}`);
  }

  const data = await response.json();
  return data.results.slice(0, maxResults);
}

Usage:

const results = await search('machine learning tutorials', 10);
console.log(results);

☁️ Cloudflare Tunnel Setup

For secure external access:

Set up Cloudflare Tunnel:

# Install cloudflared and create a tunnel
cloudflared tunnel create searxng-proxy

Configure tunnel:

cp cloudflare/config.example.yml cloudflare/config.yml
# Edit config.yml with your tunnel ID and domain

Add tunnel credentials: Place your tunnel credentials JSON file in cloudflare/

Configure DNS:

cloudflared tunnel route dns searxng-proxy search.loonylabs.dev

The tunnel will automatically start with Docker Compose

See cloudflare/README.md for detailed setup instructions.

⚙️ Configuration

🔧 Environment Variables

Create .env from .env.example:

Variable	Default	Description
`API_KEY`	Required	Authentication key for API access
`SEARXNG_URL`	`http://searxng:8080` (Docker) `http://localhost:8080` (local)	SearXNG server URL
`PORT`	`3000`	Proxy server port (local dev only)
`PROXY_URL`	-	Proxy URL for integration tests (optional)

Example .env:

API_KEY=your_secret_api_key_here
SEARXNG_URL=http://searxng:8080

# For integration tests (optional)
PROXY_URL=https://search.loonylabs.dev

📋 SearXNG Settings

Edit searxng/settings.yml to customize:

Search engines
UI theme
Rate limiting
Result formatting
Language preferences

See SearXNG Documentation for all options.

🐳 Docker Configuration

The Docker setup includes:

SearXNG container: Meta-search engine (internal only)
Proxy container: Express server with API key authentication
Cloudflared container: Cloudflare Tunnel client (optional)

Architecture:

Internet (HTTPS)
    ↓
Cloudflare Tunnel
    ↓
Proxy (Express + API Key Auth)
    ↓
SearXNG (Meta-Search Engine)

Port Exposure: By default, no ports are exposed to the host for security. Access is via Cloudflare Tunnel.

To expose port 3000 for local testing, add to docker-compose.yml:

proxy:
  ports:
    - "3000:3000"  # Add this line

🧪 Running Tests

The project includes comprehensive unit and integration tests.

Quick Test Commands

# Run all tests
npm test

# Run only unit tests (no Docker required)
npm run test:unit

# Run only integration tests (Docker required)
npm run test:integration

# Run tests in watch mode
npm run test:unit:watch

# Run tests with coverage
npm run test:unit:coverage

Test Structure

/tests
├── /unit              # Unit tests (no Docker required)
│   └── /api           # API endpoint tests
│       ├── health.test.ts      # Health endpoint tests (9 tests)
│       └── search.test.ts      # Search logic tests (21 tests)
├── /integration       # Integration tests (Docker required)
│   └── searxng-integration.test.ts  # End-to-end search tests (17 tests)
└── README.md          # Detailed testing documentation

Running Integration Tests

Integration tests require running Docker containers:

# 1. Start services
docker-compose up -d

# 2. Configure PROXY_URL in .env
# Option A: Use Cloudflare Tunnel URL (recommended)
PROXY_URL=https://search.loonylabs.dev

# Option B: Use localhost (requires port mapping)
# Add "ports: - 3000:3000" to proxy service in docker-compose.yml
PROXY_URL=http://localhost:3000

# 3. Run integration tests
npm run test:integration

Test Coverage:

✅ 47+ tests across unit and integration suites
✅ Health check endpoints (/health, /healthz)
✅ Search functionality (JSON/HTML formats)
✅ Authentication & authorization
✅ Error handling (missing params, invalid API keys)
✅ Response validation
✅ Special characters & unicode support

For detailed testing documentation, see tests/README.md.

📂 Project Structure

searxng-proxy/
├── src/
│   └── index.ts              # Express proxy server with API key auth
├── tests/                    # Test suite
│   ├── unit/                 # Unit tests
│   │   └── api/              # API endpoint unit tests
│   │       ├── health.test.ts
│   │       └── search.test.ts
│   ├── integration/          # Integration tests
│   │   └── searxng-integration.test.ts
│   └── README.md             # Testing documentation
├── searxng/
│   └── settings.yml          # SearXNG configuration
├── cloudflare/
│   ├── config.example.yml    # Cloudflare tunnel template
│   └── README.md             # Cloudflare setup guide
├── docker-compose.yml        # Complete stack (searxng + proxy + cloudflared)
├── Dockerfile                # Proxy service image
├── .env.example              # Environment variables template
├── jest.config.js            # Jest test configuration
├── jest.setup.js             # Jest setup file
├── package.json              # Node.js dependencies
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This file

🔒 Security Notes

API Key: Use a strong, randomly generated key (32+ characters)
HTTPS Only: Cloudflare Tunnel provides automatic HTTPS
Credentials: Never commit .env, config.yml, or *.json files
Rate Limiting: Consider adding rate limiting in production
Monitoring: Monitor usage via Cloudflare Analytics
Port Exposure: By default, no ports are exposed to host (secure)

🔧 Troubleshooting

Services won't start

# Check Docker
docker --version
docker-compose --version

# Check logs
docker-compose logs

# Check specific service
docker-compose logs proxy
docker-compose logs searxng

401 Unauthorized

Verify API key in .env matches your request header
Check: Authorization: Bearer YOUR_API_KEY (space after "Bearer")
API key is case-sensitive
Ensure no extra spaces or newlines in API key

Cloudflare Tunnel not connecting

# Check cloudflared logs
docker-compose logs cloudflared

# Verify tunnel configuration
cat cloudflare/config.yml

# Test tunnel status (on Cloudflare dashboard)
# https://one.dash.cloudflare.com/

SearXNG not returning results

# Check SearXNG logs
docker-compose logs searxng

# Test SearXNG directly (inside Docker network)
docker-compose exec proxy wget -O- "http://searxng:8080/search?q=test&format=json"

# Check if SearXNG is running
docker-compose ps searxng

Integration tests fail with ECONNREFUSED

Cause: Proxy port not exposed to host (intentional for security)

Solutions:

Use Cloudflare Tunnel (recommended):

# In .env
PROXY_URL=https://search.yourdomain.com

Temporarily expose port for testing:
```
# In docker-compose.yml
proxy:
  ports:
    - "3000:3000"
```
Then restart: docker-compose down && docker-compose up -d

NPM package installation fails

# Clear npm cache
npm cache clean --force

# Remove node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Run tests: npm test
Submit a pull request

For questions or support, please open an issue on GitHub.

📚 Similar Projects

This project follows the same pattern as:

ollama-proxy - Ollama API with authentication and Cloudflare Tunnel

🔗 Links

SearXNG: https://github.com/searxng/searxng
SearXNG Docs: https://docs.searxng.org
Cloudflare Tunnels: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps

Made with ❤️ by loonylabs-dev

Privacy-Respecting Meta-Search API ✅

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

SearXNG Proxy

✨ Features

🚀 Quick Start

🐳 Docker Deployment (Recommended)

🔌 API Usage

🔐 Authentication

📍 Endpoints

`GET /search`

`GET /health`

`GET /healthz`

🎯 Integration Example

☁️ Cloudflare Tunnel Setup

⚙️ Configuration

🧪 Running Tests

Quick Test Commands

Test Structure

Running Integration Tests

📂 Project Structure

🔒 Security Notes

🔧 Troubleshooting

Services won't start

401 Unauthorized

Cloudflare Tunnel not connecting

SearXNG not returning results

Integration tests fail with ECONNREFUSED

NPM package installation fails

📄 License

🤝 Contributing

📚 Similar Projects

🔗 Links

About

Uh oh!

Releases

Packages

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
cloudflare		cloudflare
searxng		searxng
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
jest.config.js		jest.config.js
jest.setup.js		jest.setup.js
package.json		package.json
tsconfig.json		tsconfig.json

loonylabs-dev/searxng-proxy

Folders and files

Latest commit

History

Repository files navigation

SearXNG Proxy

✨ Features

🚀 Quick Start

🐳 Docker Deployment (Recommended)

🔌 API Usage

🔐 Authentication

📍 Endpoints

GET /search

GET /health

GET /healthz

🎯 Integration Example

☁️ Cloudflare Tunnel Setup

⚙️ Configuration

🧪 Running Tests

Quick Test Commands

Test Structure

Running Integration Tests

📂 Project Structure

🔒 Security Notes

🔧 Troubleshooting

Services won't start

401 Unauthorized

Cloudflare Tunnel not connecting

SearXNG not returning results

Integration tests fail with ECONNREFUSED

NPM package installation fails

📄 License

🤝 Contributing

📚 Similar Projects

🔗 Links

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`GET /search`

`GET /health`

`GET /healthz`

Packages