searchmirror README

The project's README from github.com/databluedev/searchmirror. As one markdown file: README.md.

SearchMirror

CI Licence: AGPL v3

SearchMirror is an open-source, self-hosted rank tracker built around the DataBlue SERP API. It tracks Google positions by keyword, region, language, and device while keeping provider credentials under the control of the instance owner or each account.

Status: pre-1.0. The local Docker stack and supported product paths are functional, but the project still carries a legacy Django 3.2 and MongoDB 4.4 runtime. Treat the included Compose stack as a development environment, not a production deployment template.

Supported scope

The current public surface is intentionally narrow:

Keyword research, search volume, Content Gap, page audit, billing and the old commercial vendor integrations are not part of this application and their code has been removed. Google Search Console and Analytics code is retained but parked until a proper server-side OAuth flow is provided; it is not advertised as ready.

Bring your own keys

Live rank checks require DataBlue. Each account can save its own DataBlue key under Settings -> API Keys. Keys are encrypted at rest with SERP_KEY_SECRET and are not returned in clear text.

An operator may set DATABLUE_API_KEY and explicitly enable ALLOW_INSTANCE_FALLBACK=true for a single-operator install. Fallback is off by default so one account cannot silently spend the instance owner's credits.

Geo Citations and Content Planner optionally use OpenAI, Anthropic, Perplexity, or Gemini. Accounts configure a provider key and model in Settings; both features share the same provider router. No Hugging Face or DataForSEO account is required.

Quick start

Requirements: Docker with the Compose plugin.

git clone https://github.com/databluedev/searchmirror.git
cd searchmirror
cp .env.example .env
docker compose up -d --build

The backend automatically applies migrations and runs the idempotent local seed. Sign in at http://127.0.0.1:3001 with:

Field Local value
Email [email protected]
Password LocalDev12345

These credentials are for the local seed only. Replace the placeholder Django, engine, encryption, and scheduler secrets before exposing an instance.

Service Address Purpose
tracker-app http://127.0.0.1:3001 React application
tracker-backend http://127.0.0.1:8000 Django API
tracker-engine http://127.0.0.1:8001 internal ranking engine
tracker-scheduler - queues the daily 01:00 rank runs
tracker-mongo 127.0.0.1:27017 MongoDB

Every port is published on 127.0.0.1 only -- the stack is not reachable from the local network, and there is no IPv6 listener to half-answer a localhost connection. localhost and 127.0.0.1 both work; the docs use the explicit IPv4 form because that is what the tests and CORS_ALLOWED_ORIGINS are written against.

The tracker-* container names are retained for volume and deployment compatibility; the public product name is SearchMirror.

Run real rankings

Saving a DataBlue key only configures the account. The following command performs live provider requests and spends DataBlue credits:

docker compose exec engine python rank_local.py

The command prints the estimated request count before starting. It is never run automatically by the test suite.

Production-bundle smoke build

The main app can also be compiled and served by nginx on port 4001:

docker compose --profile prod up -d --build app-prod

This validates the frontend bundle; it does not turn the development Django servers or MongoDB image into a hardened production deployment.

Marketing site

landing/ is an independent Vite application:

cd landing
pnpm install
pnpm dev      # http://localhost:5180
pnpm build    # production bundle in landing/dist

Its outbound links live in landing/src/lib/site.ts. REPO_URL there is still a placeholder and has to be set to the real repository before the page is published — the licence, docs, and issues links are all derived from it.

Configuration

Copy .env.example to .env. The example documents every supported setting and contains only local placeholders.

The important security settings are:

AI provider environment variables are optional instance fallbacks. A hosted or multi-user deployment should leave them blank and use per-account keys.

Tests and builds

With the local stack running:

python -m pytest tests -q
docker compose exec -T backend python manage.py check
docker compose exec -T engine python manage.py check
docker compose exec -T app npm run build
cd landing && pnpm build

The tests cover authentication, provider routing, production configuration, supported routes, and Docker-backed integration behavior. Browser verification should avoid clicking Rank, Refresh, or Generate unless spending configured provider credits is intentional.

Project layout

Path Purpose
app/ React 18 + Vite product UI
landing/ React 18 + Vite marketing site
backend/ Django API, accounts, projects, reports, and orchestration
engine/ Django ranking engine and DataBlue integration
shared/ code shared by both Django services
brand/ the mark: source of truth for every favicon, logo, and wordmark
docker/ service Dockerfiles and nginx configuration
tests/ regression and Docker-backed integration tests

The backend and engine are separate Django applications sharing MongoDB. A future runtime upgrade should migrate Django/djongo and MongoDB together rather than changing one layer in isolation.

Documentation

Document What it is for
docs/USER-GUIDE.md Using a running instance: projects, keywords, reading the dashboard, and what costs money
docs/CONFIGURATION.md Every environment variable, what it does, and what breaks without it
SECURITY.md Reporting a vulnerability, and what is in scope
CONTRIBUTING.md Start here to work on the code: running the stack, where things live, conventions, how to submit a change
CODE_OF_CONDUCT.md What is expected of everyone taking part, and how to report a problem
CHANGELOG.md What changed in each release, and the known limitations of the current one
docs/TESTING.md The test suite — how it runs, the two kinds of test, what is covered and what is not
docs/DEPLOYMENT.md Running an instance for real: the production overlay, TLS, secrets, backups
docs/DESIGN.md The design contract. Governs every pixel; read before any UI change
docs/PRODUCT-DESIGN.md Navigation and information architecture
docs/ORCHESTRATION.md How daily ranking is scheduled across projects. Read before changing engine/project/machine/
docs/DATABLUE-INTEGRATION.md How the SERP provider is called and what it returns
docs/DATABLUE-FINDINGS-2026-09-05.md Measured provider behaviour, including fields that are always empty
docs/SHIPPED-SURFACE.md What ships, what is parked and why. Paired with tests/test_shipped_surface.py

Maintainer

Built and maintained by Sheik Mohammed Ali M (@sheik-md-ali) — [email protected].

Bug reports and feature requests belong in the issue tracker; questions are welcome by email. Security issues go through SECURITY.md, not a public issue. Contributions are welcome — start with CONTRIBUTING.md.

License

SearchMirror is licensed under the GNU Affero General Public License v3.0. If you modify it and provide the modified software as a network service, the AGPL requires that service's users be offered the corresponding source code.

Copyright (C) 2026 Sheik Mohammed Ali M and SearchMirror contributors.

searchmirror (databluedev/searchmirror)

Searching Database…

110 ·GitHub
Searchmirror
What is this?SearchMirror is an open-source, self-hosted rank tracker and AI-visibility monitor that checks Google search positions by keyword, region, language, and device through the DataBlue SERP API.
Is this a framework or a ready-to-run app?It is a ready-to-run self-hosted web app: a Django API plus an internal ranking engine on the backend, a React 18 + Vite dashboard on the frontend, and MongoDB for storage, all shipped as a Docker Compose stack.
How do I get it running?Copy .env.example to .env and start the Docker Compose stack; the backend applies migrations and runs an idempotent local seed automatically, with a default local admin login.
Do I need a DataBlue API key to see real rankings?Yes, live rank checks require your own DataBlue SERP API key saved per account under Settings -> API Keys; Geo Citations and Content Planner can optionally use an OpenAI, Anthropic, Perplexity, or Gemini key you supply.
Is this production-ready?No, the project is pre-1.0 and still runs on a legacy Django 3.2 and MongoDB 4.4 stack; the shipped Compose setup is meant as a development environment, not a hardened production deployment.
How are my saved provider keys protected?Saved DataBlue keys are encrypted at rest using the SERPKEYSECRET setting and are never returned in clear text to the account.
What does the AGPL license mean for me here?SearchMirror is AGPL-3.0, so if you modify it and run the modified version as a network service, you must offer that service's users the corresponding source code.
What AI providers power Geo Citations and Content Planner?Accounts configure their own key and model for OpenAI, Anthropic, Perplexity, or Gemini through a shared provider router used by both features.
What features used to exist but were removed?Keyword research, search volume, Content Gap, page audit, billing, and legacy commercial vendor integrations have been stripped out of the code entirely; Google Search Console/Analytics code remains but is parked until a proper OAuth flow ships.
How often do rankings get refreshed?The tracker-scheduler service queues a daily rank run at 01:00 across all projects.
Can every account share one DataBlue key instead of bringing their own?Not by default - an operator must explicitly set DATABLUE_API_KEY and enable ALLOW_INSTANCE_FALLBACK=true for a single-operator install, so one account can't silently spend the owner's credits.
What are similar projects?rankme.fast, canonry, jevbox, bisibility, clevis, quivr, youtube-automation-agent, open-seo-mcp-skills
Which topics is it in?ai-visibility, generative-engine-optimization, django, scheduler, seo, byok, mongodb, analytics, search, oauth, vite, authentication
Creator
databluedev
Size
2.7 MB
Stars
110
Updated
CommitOct 01
Age
1mo
Commits · 90 Days