Richmack Search v0.5.1

Richmack Search is a private, multi-user research metasearch and local RAG environment. It combines SearXNG discovery, per-user PDF libraries, local Ollama generation, EmbeddingGemma retrieval, source-aware answers, confidence scores, notes, and admin-visible search history.

What's new in v0.5.1

• GitHub Container Registry publishing workflow (.github/workflows/ghcr.yml)
• Multi-architecture container image: ghcr.io/iamrichmack111/richmack-search:latest
• Docker Compose can either build locally or deploy the prebuilt GHCR image
• Installer automatically attempts to pull both required Ollama models
• richmack-search models pulls gemma3:4b and embeddinggemma:300m-qat-q4_0
• richmack-search pull downloads the latest container images
• richmack-search deploy pulls and launches the prebuilt GHCR image without rebuilding

v0.5 features

• Default embeddings switched to embeddinggemma:300m-qat-q4_0
• Real indexing jobs run in the background instead of blocking the browser request
• Live indexing progress bar with real page/chunk counts
• Progress stages: download, PDF read, text extraction, embedding, SQLite save, complete/error
• Existing PDFs are retained when upgrading from Nomic embeddings
• Existing Nomic vectors are cleared and documents are marked needs_reindex when the upgrader switches embedding models
• Cross-platform installer detects macOS vs Ubuntu/Debian-family Linux
• macOS Application bundle in ~/Applications/Richmack Search.app
• Ubuntu/freedesktop application launcher and optional Desktop shortcut
• CLI command: richmack-search
• man page: man richmack-search
• Uninstaller removes launchers/CLI integration but intentionally keeps the research database and PDFs

Research/RAG features

Each account has a private library. Original PDFs are stored under:

data/documents/<user_id>/

Indexing extracts text page by page, chunks it, generates EmbeddingGemma vectors through Ollama, and stores the chunks and vectors in SQLite. RAG answers include inline [S1] citations, source title, page number, similarity score, source URL/local PDF link, retrieval confidence, and answer confidence.

The confidence percentages are heuristic evidence scores, not calibrated probabilities that an answer is true. Retrieval confidence is derived from vector similarity; answer confidence also considers supporting-source diversity. Ollama is instructed not to invent those percentages.

Requirements

• Docker Desktop on macOS, or Docker Engine + Compose plugin on Ubuntu/Linux
• Ollama reachable from the Docker container
• Generation model, default: gemma3:4b
• Embedding model, default: embeddinggemma:300m-qat-q4_0

Default .env values:

RICHMACK_SEARCH_PORT=8090
OLLAMA_URL=http://richmack.local:11434
OLLAMA_MODEL=gemma3:4b
OLLAMA_EMBED_MODEL=embeddinggemma:300m-qat-q4_0

Install both required Ollama models on the machine that actually runs Ollama:

ollama pull gemma3:4b
ollama pull embeddinggemma:300m-qat-q4_0

Or after installing Richmack Search:

richmack-search models

The model helper can also use the Ollama HTTP API when OLLAMA_URL points at a reachable remote Ollama host.

New install — automatic OS detection

Unzip the release and run:

cd ~/Downloads
unzip -o richmack-search-v0.5.1.zip
cd richmack-search-v0.5.1
./install.sh

install.sh detects the host OS. On macOS it creates a Richmack Search .app bundle. On Ubuntu/Debian-family Linux it installs a .desktop launcher and icon. In both cases it installs the CLI wrapper under ~/.local/bin/richmack-search and a user man page.

Upgrade an existing Richmack Search

You can use either:

cd ~/Downloads/richmack-search-v0.5.1
./upgrade-existing.sh ~/richmack-search

or simply:

./install.sh

when ~/richmack-search already exists; the installer detects it and performs an in-place upgrade.

The upgrader backs up data/richmack-library.sqlite3, preserves your .env, SearXNG settings, users, saved research, notes, RAG history, and original PDFs. If it finds OLLAMA_EMBED_MODEL=nomic-embed-text, it changes the model to EmbeddingGemma and invalidates only the old vectors. PDFs remain intact and affected library items show needs_reindex.

Indexing progress

Open:

http://localhost:8090/library

Choose Index PDF. The browser now receives a background job ID and polls the local status endpoint. The progress panel reports actual work, for example:

Embedding                                   68%
Embedding 137 / 201 chunks with EmbeddingGemma
Pages: 121 / 121   Chunks: 137 / 201

The progress bar is not a fake timer; page and chunk counters are updated by the indexing worker.

RAG workflow

1. Search and Save to Richmack, or upload a local PDF.
2. Go to Library.
3. Index the PDF and watch the live progress bar.
4. Go to RAG / Ask My Library.
5. Ask a question.
6. Review the answer, source pages, similarity percentages, retrieval confidence, and answer confidence.
7. Save useful answers as notes and export Markdown or TXT.

Scanned/image-only PDFs still require OCR outside the app; v0.5 does not automatically OCR them.

User profiles and admin history

Normal users see only their own saved research, PDF index, RAG history, notes, and search history. The first profile is the administrator. Admins can open /admin/history to review searches from all profiles and recent RAG questions/confidence scores.

Desktop launchers

macOS

The installer creates:

~/Applications/Richmack Search.app

Opening it starts the Docker stack if necessary and opens Richmack Search in the default browser.

Ubuntu / Linux

The installer creates:

~/.local/share/applications/richmack-search.desktop

and, when ~/Desktop exists:

~/Desktop/Richmack Search.desktop

CLI

richmack-search open
richmack-search start
richmack-search pull
richmack-search deploy
richmack-search models
richmack-search stop
richmack-search restart
richmack-search status
richmack-search logs
richmack-search library
richmack-search rag

Man page

man richmack-search

If your system does not automatically search user-local man pages, use:

man -l ~/richmack-search/man/richmack-search.1

Uninstall desktop integration

~/richmack-search/uninstall.sh

This deliberately does not delete ~/richmack-search because that directory can contain user accounts, PDFs, saved notes, embeddings, and history.

Data safety

Deleting a saved library item from the application deletes that item's retained local PDF and associated chunks for that user. Uninstalling the desktop launcher does not delete research data. Back up data/ before manually removing the application directory.

Pull the prebuilt container from GitHub Container Registry

After the GitHub Actions workflow publishes the image, the web container is available as:

docker pull ghcr.io/iamrichmack111/richmack-search:latest

A normal deployment from the repository is:

git clone https://github.com/iamrichmack111/richmack-search.git
cd richmack-search
cp .env.example .env
./scripts/pull-ollama-models.sh
docker compose pull
docker compose up -d --no-build

For development, continue to build the local source instead:

docker compose up -d --build

docker-compose.yml contains both image: and build: for the web service. --build uses your local code; pull + --no-build uses the published GHCR image.

GitHub Container Registry publishing

The included workflow publishes Linux AMD64 and ARM64 images when main is pushed, when a v* tag is pushed, or when the workflow is manually dispatched. The repository must have GitHub Actions enabled and package write permission available to GITHUB_TOKEN.