GitHub - gridlhq/flapjack

Self-hosted search engine with an Algolia-compatible API. Single binary, no dependencies.

Drop-in replacement for Algolia — works with InstantSearch.js and the algoliasearch client. Typo-tolerant full-text search with faceting, geo search, and custom ranking. Single static binary, runs anywhere, data stays on disk.

Live Demo · Geo Demo · API Docs

Quickstart

curl -fsSL https://install.flapjack.foo | sh    #install

flapjack                                        #run the server

open http://127.0.0.1:7700/dashboard            #load the dashboard


# Add documents
curl -X POST http://localhost:7700/indexes/movies/documents \
  -d '[
    {"objectID":"1","title":"The Matrix","year":1999},
    {"objectID":"2","title":"Inception","year":2010}
  ]'

# Search
curl "http://localhost:7700/indexes/movies/search?q=matrxi"

flapjack uninstall

# Install specific version
curl -fsSL https://install.flapjack.foo | sh -s -- v0.2.0

# Custom install directory
FLAPJACK_INSTALL=/opt/flapjack curl -fsSL https://install.flapjack.foo | sh

# Skip PATH modification
NO_MODIFY_PATH=1 curl -fsSL https://install.flapjack.foo | sh

Migrate from Algolia

flapjack

curl -X POST http://localhost:7700/migrate \
  -d '{"appId":"YOUR_ALGOLIA_APP_ID","apiKey":"YOUR_ALGOLIA_ADMIN_KEY","sourceIndex":"products"}'

Search:

curl "http://localhost:7700/indexes/products/search?q=widget"

Then point your frontend at Flapjack instead of Algolia:

import algoliasearch from 'algoliasearch';

// app-id can be any string, api-key is your FLAPJACK_ADMIN_KEY or a search key
const client = algoliasearch('my-app', 'your-flapjack-api-key');
client.transporter.hosts = [{ url: 'localhost:7700', protocol: 'http' }];

// Everything else stays the same

InstantSearch.js widgets work as-is — SearchBox, Hits, RefinementList, Pagination, GeoSearch, etc.

Features

Algolia-compatible REST API under /1/ — works with InstantSearch.js v5, the algoliasearch client, and Laravel Scout.

Comparison

Deployment

cargo build --release
./target/release/flapjack

Requires Rust 1.70+. Pre-built binaries for Linux x86_64 (static musl), Linux ARM64, macOS Intel, and macOS Apple Silicon on the releases page.

# docker-compose.yml
services:
  flapjack:
    image: flapjack/flapjack:latest
    ports:
      - "7700:7700"
    volumes:
      - ./data:/data
    environment:
      FLAPJACK_DATA_DIR: /data
      FLAPJACK_ADMIN_KEY: ${ADMIN_KEY}
    restart: unless-stopped

# /etc/systemd/system/flapjack.service
[Unit]
Description=Flapjack Search Server
After=network.target

[Service]
Type=simple
User=flapjack
WorkingDirectory=/var/lib/flapjack
Environment=FLAPJACK_DATA_DIR=/var/lib/flapjack/data
Environment=FLAPJACK_ADMIN_KEY=your-key
ExecStart=/usr/local/bin/flapjack
Restart=always

[Install]
WantedBy=multi-user.target

Configuration

Data stored in FLAPJACK_DATA_DIR. Mount as a volume in Docker.

API Documentation

• Online API docs
• Swagger UI (local)

Use as a Library

Flapjack's core can be embedded directly:

[dependencies]
flapjack = { version = "0.1", default-features = false }

See LIB.md for the embedding guide.

Architecture

Built on Tantivy (forked for edge-ngram prefix search). Axum + Tokio HTTP server. Supports 600+ indexes per 4GB node.

flapjack/              # Core library (search, indexing, query execution)
flapjack-http/         # HTTP server (Axum handlers, routing)
flapjack-replication/  # Cluster coordination
flapjack-ssl/          # TLS (Let's Encrypt, ACME)
flapjack/       # Binary entrypoint

Development

cargo install cargo-nextest
cargo nextest run

Roadmap

Security

• Hash API keys at rest (salted SHA-256)
• Admin key on first boot only
• Key type prefixes (fj_admin_, fj_search_)

Infrastructure

• High availability — multi-node replication
• Managed cloud (SaaS)

Search

• Vector / hybrid search
• AI search (RAG)
• A/B testing
• Multi-language support

Platform

• Webhooks
• Role-based access control

Dashboard Screenshots

Flapjack includes a built-in dashboard UI served at http://localhost:7700 when the server is running.

License

MIT