Skip to content

OneSearch

Self-hosted, privacy-focused search for your homelab.

Search across all your files, documents, and notes from a single interface. No cloud dependencies, no telemetry, just fast local search powered by Meilisearch.

Features

Fast full-text search with typo tolerance and relevance ranking. OneSearch uses Meilisearch under the hood, so searches are typically sub-second even with millions of documents.

Multiple file types supported: text, code, config, Markdown, PDFs, Office docs, RTF, EPUB, subtitles, comics, images, RAW photos, audio/video metadata, and metadata-only entries for everything else.

Multiple sources: Index local directories, NAS shares, or external drives. Each source can have its own include/exclude patterns.

Incremental indexing: Only changed files get reindexed, so updates are fast. Full reindex available when you need it.

Scheduled indexing: Set per-source cron schedules (hourly, daily, weekly, or custom) so sources stay up to date automatically.

Authentication: JWT-based login with a setup wizard. Rate-limited to prevent brute force.

Three ways to use it: Web UI for browsing and searching, REST API for integrations, and CLI for automation.

Themeable: pick an accent color preset or dial in a custom hue from Admin -> Settings. Persists across reloads.

Privacy first: Everything runs locally. No outbound connections, no telemetry, no cloud services. Your data never leaves your network.

Quick Start

Get OneSearch running in a few minutes:

# Create project directory
mkdir onesearch && cd onesearch

# Download docker-compose.yml
curl -O https://raw.githubusercontent.com/demigodmode/OneSearch/main/docker-compose.yml

# Download and configure environment
curl -O https://raw.githubusercontent.com/demigodmode/OneSearch/main/.env.example
cp .env.example .env
# Edit .env and set MEILI_MASTER_KEY (generate with: openssl rand -base64 32)

# Start it up
docker-compose up -d

Open http://localhost:8000, create your admin account in the setup wizard, and you're ready to go.

For detailed setup instructions, see the Installation Guide.

What's New

The current Docker setup runs OneSearch and managed Meilisearch in a single container by default. Recent releases also added rich media indexing, authenticated previews, RAW/photo metadata, metadata-only indexing for unsupported files, and full reindex controls in the UI, CLI, and API.

Check the Changelog for release-by-release details.

How to Use It

Web Interface

The main search page gives you a Google-like search box with filters for source and file type. Click any result to see the full document with syntax highlighting. The admin section lets you manage sources and monitor indexing status.

Web UI Guide

Command Line

The CLI is great for automation and scripting. Add sources, trigger reindexing, and search from the command line. Supports JSON output for easy parsing.

CLI Documentation

REST API

Full API access for custom integrations. All the web UI functionality is available via API endpoints.

API Reference

Common Use Cases

Personal knowledge base: Search across notes, documents, and downloads from one place.

Homelab documentation: Index config files, logs, and technical docs scattered across your servers.

Research library: Full-text search across PDFs, academic papers, and research notes.

Media libraries: Search filenames and metadata across large photo, RAW, audio, and video collections.

Architecture

OneSearch is built on modern, proven technologies:

  • FastAPI (Python) for the backend API
  • Meilisearch for fast full-text search
  • SQLite for metadata and configuration
  • React + TypeScript for the web UI
  • Docker Compose for easy deployment

The backend handles indexing and search requests. Meilisearch stores the search index. SQLite tracks which files have been indexed and their metadata. The frontend is served by nginx and talks to the backend API.

See the Architecture Guide for details.

Support

Next Steps

New to OneSearch? Start with the Installation Guide.

Already installed? Check out the User Guide to learn about adding sources and searching.

Want to automate? See the CLI Documentation.

Building integrations? Explore the API Reference.