Vibecode Algolia
track this build5 phases, 10 steps, beginner friendly0%KINDA · weekend project
Typo-tolerant instant search over your own data is a solved open-source problem: Meilisearch or Typesense on a small box gives you the core in an afternoon. What Algolia adds is the managed global edge, the merchandising and AI ranking layer, and not operating anything.
the project pack5 files · written for this build, step by step
You are building a lean indie version of Algolia. Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt. ===== README.md ===== # Algolia · indie build Instant, typo-tolerant search over your own content without writing a search engine: Meilisearch on a small box behind Caddy, an idempotent indexing script, a search-only key for the browser, and a search box under 5 KB that works without JavaScript too. Estimated effort: **weekend**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts. ## Stack | Part | Choice | Why | | --- | --- | --- | | Engine | Meilisearch | rule zero: do not write a search engine | | Indexer | A Node script | your content to documents, idempotently | | Hosting | A VPS with a few GB of RAM behind Caddy | the index lives in memory | ## Before you start Have every one of these ready. The plan assumes them from step one. - [ ] **Node.js 22 or newer** · free - Why: Everything in this build runs on it: the server, the scripts, the tests. - Get it: Download the LTS installer from nodejs.org, or install with your package manager (brew install node, or nvm install 22). Restart the terminal afterwards. - Verify: node --version prints v22 or higher - [ ] **A terminal and a code editor** · free - Why: Every step below is a command you type or a file you edit. - Get it: VS Code (code.visualstudio.com), Cursor or Zed. Open a folder for the project and use the editor's built-in terminal. - Verify: You can open a folder and run a command in its terminal - [ ] **Git** · free - Why: History for your code, and the way most hosts deploy. - Get it: Install from git-scm.com or with your package manager, then run git init in the project folder once it exists. - Verify: git --version prints a version - [ ] **A VPS with 4 GB of RAM** · about $6 to $12 a month - Why: Meilisearch holds the index in memory. - Get it: Hetzner CX22 or similar, Ubuntu 24.04. - [ ] **Meilisearch** · free - Why: The engine. - Get it: curl -L https://install.meilisearch.com | sh, or the Docker image getmeili/meilisearch. - Verify: meilisearch --version prints - [ ] **Your content as files, JSON or a database** · free - Why: The indexer reads it. - Get it: Markdown files, a JSON export, or a database connection string. - [ ] **A domain or subdomain** (optional) · roughly $10 a year, or free on an existing domain - Why: search.yourdomain.com for the API. - Get it: Register at Cloudflare Registrar, Porkbun or Namecheap, or use a subdomain of one you already own. You add one DNS record in the deploy phase. - [ ] **Caddy on the server** (optional) · free - Why: Automatic HTTPS in front of the Node process. Without TLS the browser features this relies on (and your visitors' trust) do not work. - Get it: On the VPS: follow the install steps at caddyserver.com/docs/install for Ubuntu. One Caddyfile with your domain and a reverse_proxy line is the whole config. - Verify: caddy version prints a version on the server ## Quick start ```sh meilisearch --master-key $MEILI_MASTER_KEY --http-addr 127.0.0.1:7700 ``` Then copy `.env.example` to `.env` and fill in the values it documents. ## Honest limits This build deliberately does not replace: - Merchandising rules, AI ranking, the global edge: commerce money. - the global distributed search network - merchandising, rules and A/B testing - AI ranking and personalization - zero operations If one of those is essential to you, that is the reason to keep paying for Algolia, and the README should say so rather than pretend. ===== BRIEF.md ===== # Build brief · Algolia The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me site search like Algolia for my own content. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. ### Rule zero Do not write a search engine. Ranking, typo tolerance and prefix matching are years of work that Meilisearch already did. Deploy it and build the thin layer around it. ### Stack (fixed, do not substitute) - Meilisearch on a small VPS behind Caddy, or its Docker image. A Node indexing script. A vanilla-JS search box, no framework. ### Phase 1 · Run it Build: Meilisearch with a master key in .env, bound to localhost, Caddy in front with TLS. Done when: the health endpoint answers over HTTPS and the master key is required for admin calls. Do not build yet: indexing, UI. ### Phase 2 · Index Build: an indexing script that reads your content (Markdown, JSON or a database) into documents with id, title, url, body and tags, sets searchable and displayed attributes, and runs idempotently. Done when: re-running adds nothing, a changed document updates in place, and a deleted one disappears. ### Phase 3 · Keys Build: a search-only API key scoped to the index for the browser; the master key never leaves the server. Done when: the browser key can search and cannot add documents. ### Phase 4 · The box Build: a search input with results as you type, highlighting, keyboard navigation, and a debounce. Under 5 kB of JavaScript. Works as a normal form submit when JS is off. Done when: a typo still finds the right result and the box is fully keyboard operable. ### Phase 5 · Operate Build: a systemd unit, snapshot backups, index rebuild on deploy, and the README. Done when: a restore from snapshot searches correctly. ### Out of scope (and why) - Merchandising rules, AI ranking, the global edge. That is commerce money. ### README must contain - The key model in two sentences. - How to reindex. ===== AGENTS.md ===== # Agent instructions · Algolia indie build - Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Meilisearch, A Node script, A VPS with a few GB of RAM behind Caddy. Do not substitute. - Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes. - Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name. - Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced. - Do not invent cryptography, security guarantees, APIs or compliance claims. - Add a focused test for every destructive, security-sensitive or data-loss path the plan names. - Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs". ===== BUILD_PLAN.md ===== # Build plan · Algolia Instant, typo-tolerant search over your own content without writing a search engine: Meilisearch on a small box behind Caddy, an idempotent indexing script, a search-only key for the browser, and a search box under 5 KB that works without JavaScript too. Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note. ## Phase 1 · Run it Meilisearch bound to localhost with a master key, Caddy in front. ### Steps 1. Install and run with MEILI_MASTER_KEY, bound to 127.0.0.1:7700 ```sh meilisearch --master-key $MEILI_MASTER_KEY --http-addr 127.0.0.1:7700 ``` 2. Caddyfile with reverse_proxy and TLS Files: `Caddyfile` ### Done when - [ ] The health endpoint answers over HTTPS - [ ] The master key is required for admin calls ## Phase 2 · Index Documents with id, title, url, body and tags; idempotent. ### Steps 1. Write index.mjs reading CONTENT_DIR into documents and setting searchable and displayed attributes ```sh mkdir search-index && cd search-index && git init && npm init -y && npm pkg set type=module && npm install meilisearch@0.4 mkdir -p content && cp .env.example .env ``` 2. Make it idempotent on a content hash; delete removed documents ### Done when - [ ] Re-running adds nothing - [ ] A changed document updates - [ ] A deleted one disappears ## Phase 3 · Keys A search-only key for the browser; the master key never leaves the server. ### Steps 1. Create a search-only API key scoped to the index 2. Put it in the page; verify it cannot write ### Done when - [ ] The browser key can search - [ ] It cannot add documents ## Phase 4 · The box Results as you type, highlighted, keyboard-driven, under 5 KB, degrades to a form. ### Steps 1. Vanilla-JS search box with debounce and highlighting 2. A server-rendered /search?q= fallback for JavaScript off ### Done when - [ ] A typo still finds the right result - [ ] Fully keyboard operable - [ ] Under 5 KB of JavaScript ## Phase 5 · Operate Service, snapshots, reindex on deploy. ### Steps 1. systemd unit, nightly snapshot, reindex step in your deploy 2. README: the key model in two sentences and how to reindex Files: `README.md` ### Done when - [ ] A restore from snapshot searches correctly ## Not in this build - Merchandising rules, AI ranking, the global edge: commerce money. ## After v1, if you want it - Faceted filters - Multi-index federated search ===== .env.example ===== # Copy to .env and fill in. Never commit .env; this file documents it. # Required · secret. openssl rand -base64 32; admin key, server-side only. MEILI_MASTER_KEY=long-random # Required. Public API address behind Caddy. MEILI_URL=https://search.yourdomain.com # Optional. Generated in Phase 3; safe for the browser. MEILI_SEARCH_KEY=... # Required. Where the indexer reads from. CONTENT_DIR=./content
You are building a lean indie version of Algolia. Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt. ===== README.md ===== # Algolia · indie build Instant, typo-tolerant search over your own content without writing a search engine: Meilisearch on a small box behind Caddy, an idempotent indexing script, a search-only key for the browser, and a search box under 5 KB that works without JavaScript too. Estimated effort: **weekend**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts. ## Stack | Part | Choice | Why | | --- | --- | --- | | Engine | Meilisearch | rule zero: do not write a search engine | | Indexer | A Node script | your content to documents, idempotently | | Hosting | A VPS with a few GB of RAM behind Caddy | the index lives in memory | ## Before you start Have every one of these ready. The plan assumes them from step one. - [ ] **Node.js 22 or newer** · free - Why: Everything in this build runs on it: the server, the scripts, the tests. - Get it: Download the LTS installer from nodejs.org, or install with your package manager (brew install node, or nvm install 22). Restart the terminal afterwards. - Verify: node --version prints v22 or higher - [ ] **A terminal and a code editor** · free - Why: Every step below is a command you type or a file you edit. - Get it: VS Code (code.visualstudio.com), Cursor or Zed. Open a folder for the project and use the editor's built-in terminal. - Verify: You can open a folder and run a command in its terminal - [ ] **Git** · free - Why: History for your code, and the way most hosts deploy. - Get it: Install from git-scm.com or with your package manager, then run git init in the project folder once it exists. - Verify: git --version prints a version - [ ] **A VPS with 4 GB of RAM** · about $6 to $12 a month - Why: Meilisearch holds the index in memory. - Get it: Hetzner CX22 or similar, Ubuntu 24.04. - [ ] **Meilisearch** · free - Why: The engine. - Get it: curl -L https://install.meilisearch.com | sh, or the Docker image getmeili/meilisearch. - Verify: meilisearch --version prints - [ ] **Your content as files, JSON or a database** · free - Why: The indexer reads it. - Get it: Markdown files, a JSON export, or a database connection string. - [ ] **A domain or subdomain** (optional) · roughly $10 a year, or free on an existing domain - Why: search.yourdomain.com for the API. - Get it: Register at Cloudflare Registrar, Porkbun or Namecheap, or use a subdomain of one you already own. You add one DNS record in the deploy phase. - [ ] **Caddy on the server** (optional) · free - Why: Automatic HTTPS in front of the Node process. Without TLS the browser features this relies on (and your visitors' trust) do not work. - Get it: On the VPS: follow the install steps at caddyserver.com/docs/install for Ubuntu. One Caddyfile with your domain and a reverse_proxy line is the whole config. - Verify: caddy version prints a version on the server ## Quick start ```sh meilisearch --master-key $MEILI_MASTER_KEY --http-addr 127.0.0.1:7700 ``` Then copy `.env.example` to `.env` and fill in the values it documents. ## Honest limits This build deliberately does not replace: - Merchandising rules, AI ranking, the global edge: commerce money. - the global distributed search network - merchandising, rules and A/B testing - AI ranking and personalization - zero operations If one of those is essential to you, that is the reason to keep paying for Algolia, and the README should say so rather than pretend. ===== BRIEF.md ===== # Build brief · Algolia The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me site search like Algolia for my own content. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. ### Rule zero Do not write a search engine. Ranking, typo tolerance and prefix matching are years of work that Meilisearch already did. Deploy it and build the thin layer around it. ### Stack (fixed, do not substitute) - Meilisearch on a small VPS behind Caddy, or its Docker image. A Node indexing script. A vanilla-JS search box, no framework. ### Phase 1 · Run it Build: Meilisearch with a master key in .env, bound to localhost, Caddy in front with TLS. Done when: the health endpoint answers over HTTPS and the master key is required for admin calls. Do not build yet: indexing, UI. ### Phase 2 · Index Build: an indexing script that reads your content (Markdown, JSON or a database) into documents with id, title, url, body and tags, sets searchable and displayed attributes, and runs idempotently. Done when: re-running adds nothing, a changed document updates in place, and a deleted one disappears. ### Phase 3 · Keys Build: a search-only API key scoped to the index for the browser; the master key never leaves the server. Done when: the browser key can search and cannot add documents. ### Phase 4 · The box Build: a search input with results as you type, highlighting, keyboard navigation, and a debounce. Under 5 kB of JavaScript. Works as a normal form submit when JS is off. Done when: a typo still finds the right result and the box is fully keyboard operable. ### Phase 5 · Operate Build: a systemd unit, snapshot backups, index rebuild on deploy, and the README. Done when: a restore from snapshot searches correctly. ### Out of scope (and why) - Merchandising rules, AI ranking, the global edge. That is commerce money. ### README must contain - The key model in two sentences. - How to reindex. ===== AGENTS.md ===== # Agent instructions · Algolia indie build - Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Meilisearch, A Node script, A VPS with a few GB of RAM behind Caddy. Do not substitute. - Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes. - Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name. - Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced. - Do not invent cryptography, security guarantees, APIs or compliance claims. - Add a focused test for every destructive, security-sensitive or data-loss path the plan names. - Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs". ===== BUILD_PLAN.md ===== # Build plan · Algolia Instant, typo-tolerant search over your own content without writing a search engine: Meilisearch on a small box behind Caddy, an idempotent indexing script, a search-only key for the browser, and a search box under 5 KB that works without JavaScript too. Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note. ## Phase 1 · Run it Meilisearch bound to localhost with a master key, Caddy in front. ### Steps 1. Install and run with MEILI_MASTER_KEY, bound to 127.0.0.1:7700 ```sh meilisearch --master-key $MEILI_MASTER_KEY --http-addr 127.0.0.1:7700 ``` 2. Caddyfile with reverse_proxy and TLS Files: `Caddyfile` ### Done when - [ ] The health endpoint answers over HTTPS - [ ] The master key is required for admin calls ## Phase 2 · Index Documents with id, title, url, body and tags; idempotent. ### Steps 1. Write index.mjs reading CONTENT_DIR into documents and setting searchable and displayed attributes ```sh mkdir search-index && cd search-index && git init && npm init -y && npm pkg set type=module && npm install meilisearch@0.4 mkdir -p content && cp .env.example .env ``` 2. Make it idempotent on a content hash; delete removed documents ### Done when - [ ] Re-running adds nothing - [ ] A changed document updates - [ ] A deleted one disappears ## Phase 3 · Keys A search-only key for the browser; the master key never leaves the server. ### Steps 1. Create a search-only API key scoped to the index 2. Put it in the page; verify it cannot write ### Done when - [ ] The browser key can search - [ ] It cannot add documents ## Phase 4 · The box Results as you type, highlighted, keyboard-driven, under 5 KB, degrades to a form. ### Steps 1. Vanilla-JS search box with debounce and highlighting 2. A server-rendered /search?q= fallback for JavaScript off ### Done when - [ ] A typo still finds the right result - [ ] Fully keyboard operable - [ ] Under 5 KB of JavaScript ## Phase 5 · Operate Service, snapshots, reindex on deploy. ### Steps 1. systemd unit, nightly snapshot, reindex step in your deploy 2. README: the key model in two sentences and how to reindex Files: `README.md` ### Done when - [ ] A restore from snapshot searches correctly ## Not in this build - Merchandising rules, AI ranking, the global edge: commerce money. ## After v1, if you want it - Faceted filters - Multi-index federated search ===== .env.example ===== # Copy to .env and fill in. Never commit .env; this file documents it. # Required · secret. openssl rand -base64 32; admin key, server-side only. MEILI_MASTER_KEY=long-random # Required. Public API address behind Caddy. MEILI_URL=https://search.yourdomain.com # Optional. Generated in Phase 3; safe for the browser. MEILI_SEARCH_KEY=... # Required. Where the indexer reads from. CONTENT_DIR=./content
You are building a production product version of Algolia. Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt. ===== PRODUCT.md ===== # Algolia · product brief ## Problem Typo-tolerant instant search over your own data is a solved open-source problem: Meilisearch or Typesense on a small box gives you the core in an afternoon. What Algolia adds is the managed global edge, the merchandising and AI ranking layer, and not operating anything. ## Product outcome Search you operate with a relevance loop, at a fraction of the hosted price, with the edge stated as the thing you gave up. ## Target user A builder who needs a maintainable product foundation, not a one-off demo. ## Required capabilities - a VPS with a few GB of RAM - your data as JSON ## Explicit non-goals for v1 - Merchandising rules, AI ranking, the global edge: commerce money. - the global distributed search network - merchandising, rules and A/B testing - AI ranking and personalization - zero operations ## Success criteria - Search-only key verified read-only - Reindex idempotence verified - Snapshot restore verified ===== BRIEF.md ===== # Build brief · Algolia The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me site search like Algolia for my own content. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. ### Rule zero Do not write a search engine. Ranking, typo tolerance and prefix matching are years of work that Meilisearch already did. Deploy it and build the thin layer around it. ### Stack (fixed, do not substitute) - Meilisearch on a small VPS behind Caddy, or its Docker image. A Node indexing script. A vanilla-JS search box, no framework. ### Phase 1 · Run it Build: Meilisearch with a master key in .env, bound to localhost, Caddy in front with TLS. Done when: the health endpoint answers over HTTPS and the master key is required for admin calls. Do not build yet: indexing, UI. ### Phase 2 · Index Build: an indexing script that reads your content (Markdown, JSON or a database) into documents with id, title, url, body and tags, sets searchable and displayed attributes, and runs idempotently. Done when: re-running adds nothing, a changed document updates in place, and a deleted one disappears. ### Phase 3 · Keys Build: a search-only API key scoped to the index for the browser; the master key never leaves the server. Done when: the browser key can search and cannot add documents. ### Phase 4 · The box Build: a search input with results as you type, highlighting, keyboard navigation, and a debounce. Under 5 kB of JavaScript. Works as a normal form submit when JS is off. Done when: a typo still finds the right result and the box is fully keyboard operable. ### Phase 5 · Operate Build: a systemd unit, snapshot backups, index rebuild on deploy, and the README. Done when: a restore from snapshot searches correctly. ### Out of scope (and why) - Merchandising rules, AI ranking, the global edge. That is commerce money. ### README must contain - The key model in two sentences. - How to reindex. ===== ARCHITECTURE.md ===== # Architecture · Algolia ## Stack | Part | Choice | Why | | --- | --- | --- | | Engine | Meilisearch | rule zero: do not write a search engine | | Indexer | A Node script | your content to documents, idempotently | | Hosting | A VPS with a few GB of RAM behind Caddy | the index lives in memory | ## Modules Each module has one owner concern and a documented way to replace it. | Module | Owns | How to replace it | | --- | --- | --- | | Engine | Meilisearch | Typesense with the same document shape | | Indexer | content to documents | Any source | | Keys | master vs search-only | Tenant tokens later | | Box | the UI | Any client | ## Configuration Every runtime setting is an environment variable documented in `.env.example`, validated at startup, with a safe local default wherever one exists. - `MEILI_MASTER_KEY` · required, secret · openssl rand -base64 32; admin key, server-side only. - `MEILI_URL` · required · Public API address behind Caddy. - `MEILI_SEARCH_KEY` · optional · Generated in Phase 3; safe for the browser. - `CONTENT_DIR` · required · Where the indexer reads from. ## Production baseline - Security: least privilege, input validation at every boundary, secret redaction in logs, rate limits on abuse-prone paths, no invented security primitives. - Data: explicit schema and migrations, transactional writes where integrity matters, backup and restore procedures that have been exercised. - Integrations: adapters around third-party providers, idempotent webhook or job processing, bounded retries, timeouts. - Observability: structured logs with request or operation ids, an error-tracking hook, and health and readiness checks where a server exists. - Quality: unit tests for domain rules, integration tests at module boundaries, one end-to-end test of the critical path. ## Decision records For each dependency in the stack table, keep a short note: why it was chosen, its failure mode, and how it is replaced. Do not add infrastructure until a requirement in `PRODUCT.md` justifies it. ===== AGENTS.md ===== # Agent instructions · Algolia product build - Read `PRODUCT.md` and `ARCHITECTURE.md` before changing code. The stack is fixed: Meilisearch, A Node script, A VPS with a few GB of RAM behind Caddy. - Implement milestone by milestone from `MILESTONES.md`; keep each change reviewable and leave the application runnable at every commit. - Treat authentication, payments, encryption, imports, webhooks and destructive actions as high-risk boundaries when present. - Never invent cryptography or silently weaken a requirement to make a check pass. - Put every external service behind an interface with a deterministic fake for tests. - Add migrations and rollback or recovery notes for every persistent data change. - Log useful operational context without credentials, tokens, passwords or personal data. - Update documentation and run every check before completing a milestone. ===== MILESTONES.md ===== # Delivery milestones · Algolia Estimated effort: **weekend** for the indie phases; the production-only milestones add the trust and operability layer. ## M1 · Run it Meilisearch bound to localhost with a master key, Caddy in front. ### Steps 1. Install and run with MEILI_MASTER_KEY, bound to 127.0.0.1:7700 ```sh meilisearch --master-key $MEILI_MASTER_KEY --http-addr 127.0.0.1:7700 ``` 2. Caddyfile with reverse_proxy and TLS Files: `Caddyfile` ### Done when - [ ] The health endpoint answers over HTTPS - [ ] The master key is required for admin calls ## M2 · Index Documents with id, title, url, body and tags; idempotent. ### Steps 1. Write index.mjs reading CONTENT_DIR into documents and setting searchable and displayed attributes ```sh mkdir search-index && cd search-index && git init && npm init -y && npm pkg set type=module && npm install meilisearch@0.4 mkdir -p content && cp .env.example .env ``` 2. Make it idempotent on a content hash; delete removed documents ### Done when - [ ] Re-running adds nothing - [ ] A changed document updates - [ ] A deleted one disappears ## M3 · Keys A search-only key for the browser; the master key never leaves the server. ### Steps 1. Create a search-only API key scoped to the index 2. Put it in the page; verify it cannot write ### Done when - [ ] The browser key can search - [ ] It cannot add documents ## M4 · The box Results as you type, highlighted, keyboard-driven, under 5 KB, degrades to a form. ### Steps 1. Vanilla-JS search box with debounce and highlighting 2. A server-rendered /search?q= fallback for JavaScript off ### Done when - [ ] A typo still finds the right result - [ ] Fully keyboard operable - [ ] Under 5 KB of JavaScript ## M5 · Operate Service, snapshots, reindex on deploy. ### Steps 1. systemd unit, nightly snapshot, reindex step in your deploy 2. README: the key model in two sentences and how to reindex Files: `README.md` ### Done when - [ ] A restore from snapshot searches correctly ## M6 · Relevance tuning (production only) Synonyms, ranking rules, and a way to measure. ### Steps 1. Configure synonyms and ranking rules for your domain 2. Log queries with zero results and review them weekly ### Done when - [ ] Top zero-result queries are visible - [ ] A synonym fixes one of them ===== OPERATIONS.md ===== # Operations · Algolia ## Backup Nightly snapshots; the index is rebuildable from content. ## Restore Load the snapshot or reindex. Do a restore drill before the first real user, and write the date here when it passes. ## Monitoring Uptime on health; zero-result rate. ## Incident checklist A leaked master key: rotate and regenerate search keys. 1. Contain the issue without destroying evidence or user data. 2. Record the timeline and affected scope. 3. Rotate exposed secrets and revoke compromised sessions or credentials. 4. Restore from a verified backup when needed. 5. Document the root cause, the remediation and the regression test. ## Release gate - [ ] Search-only key verified read-only - [ ] Reindex idempotence verified - [ ] Snapshot restore verified ## Launch constraint Do not market omitted Algolia capabilities as implemented. The non-goals in `PRODUCT.md` remain user-visible limitations until they are deliberately delivered. ===== .env.example ===== # Copy to .env and fill in. Never commit .env; this file documents it. # Required · secret. openssl rand -base64 32; admin key, server-side only. MEILI_MASTER_KEY=long-random # Required. Public API address behind Caddy. MEILI_URL=https://search.yourdomain.com # Optional. Generated in Phase 3; safe for the browser. MEILI_SEARCH_KEY=... # Required. Where the indexer reads from. CONTENT_DIR=./content
README.md
# Algolia · indie build Instant, typo-tolerant search over your own content without writing a search engine: Meilisearch on a small box behind Caddy, an idempotent indexing script, a search-only key for the browser, and a search box under 5 KB that works without JavaScript too. Estimated effort: **weekend**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts. ## Stack | Part | Choice | Why | | --- | --- | --- | | Engine | Meilisearch | rule zero: do not write a search engine | | Indexer | A Node script | your content to documents, idempotently | | Hosting | A VPS with a few GB of RAM behind Caddy | the index lives in memory | ## Before you start Have every one of these ready. The plan assumes them from step one. - [ ] **Node.js 22 or newer** · free - Why: Everything in this build runs on it: the server, the scripts, the tests. - Get it: Download the LTS installer from nodejs.org, or install with your package manager (brew install node, or nvm install 22). Restart the terminal afterwards. - Verify: node --version prints v22 or higher - [ ] **A terminal and a code editor** · free - Why: Every step below is a command you type or a file you edit. - Get it: VS Code (code.visualstudio.com), Cursor or Zed. Open a folder for the project and use the editor's built-in terminal. - Verify: You can open a folder and run a command in its terminal - [ ] **Git** · free - Why: History for your code, and the way most hosts deploy. - Get it: Install from git-scm.com or with your package manager, then run git init in the project folder once it exists. - Verify: git --version prints a version - [ ] **A VPS with 4 GB of RAM** · about $6 to $12 a month - Why: Meilisearch holds the index in memory. - Get it: Hetzner CX22 or similar, Ubuntu 24.04. - [ ] **Meilisearch** · free - Why: The engine. - Get it: curl -L https://install.meilisearch.com | sh, or the Docker image getmeili/meilisearch. - Verify: meilisearch --version prints - [ ] **Your content as files, JSON or a database** · free - Why: The indexer reads it. - Get it: Markdown files, a JSON export, or a database connection string. - [ ] **A domain or subdomain** (optional) · roughly $10 a year, or free on an existing domain - Why: search.yourdomain.com for the API. - Get it: Register at Cloudflare Registrar, Porkbun or Namecheap, or use a subdomain of one you already own. You add one DNS record in the deploy phase. - [ ] **Caddy on the server** (optional) · free - Why: Automatic HTTPS in front of the Node process. Without TLS the browser features this relies on (and your visitors' trust) do not work. - Get it: On the VPS: follow the install steps at caddyserver.com/docs/install for Ubuntu. One Caddyfile with your domain and a reverse_proxy line is the whole config. - Verify: caddy version prints a version on the server ## Quick start ```sh meilisearch --master-key $MEILI_MASTER_KEY --http-addr 127.0.0.1:7700 ``` Then copy `.env.example` to `.env` and fill in the values it documents. ## Honest limits This build deliberately does not replace: - Merchandising rules, AI ranking, the global edge: commerce money. - the global distributed search network - merchandising, rules and A/B testing - AI ranking and personalization - zero operations If one of those is essential to you, that is the reason to keep paying for Algolia, and the README should say so rather than pretend.
BRIEF.md
# Build brief · Algolia The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me site search like Algolia for my own content. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. ### Rule zero Do not write a search engine. Ranking, typo tolerance and prefix matching are years of work that Meilisearch already did. Deploy it and build the thin layer around it. ### Stack (fixed, do not substitute) - Meilisearch on a small VPS behind Caddy, or its Docker image. A Node indexing script. A vanilla-JS search box, no framework. ### Phase 1 · Run it Build: Meilisearch with a master key in .env, bound to localhost, Caddy in front with TLS. Done when: the health endpoint answers over HTTPS and the master key is required for admin calls. Do not build yet: indexing, UI. ### Phase 2 · Index Build: an indexing script that reads your content (Markdown, JSON or a database) into documents with id, title, url, body and tags, sets searchable and displayed attributes, and runs idempotently. Done when: re-running adds nothing, a changed document updates in place, and a deleted one disappears. ### Phase 3 · Keys Build: a search-only API key scoped to the index for the browser; the master key never leaves the server. Done when: the browser key can search and cannot add documents. ### Phase 4 · The box Build: a search input with results as you type, highlighting, keyboard navigation, and a debounce. Under 5 kB of JavaScript. Works as a normal form submit when JS is off. Done when: a typo still finds the right result and the box is fully keyboard operable. ### Phase 5 · Operate Build: a systemd unit, snapshot backups, index rebuild on deploy, and the README. Done when: a restore from snapshot searches correctly. ### Out of scope (and why) - Merchandising rules, AI ranking, the global edge. That is commerce money. ### README must contain - The key model in two sentences. - How to reindex.
AGENTS.md
# Agent instructions · Algolia indie build - Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Meilisearch, A Node script, A VPS with a few GB of RAM behind Caddy. Do not substitute. - Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes. - Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name. - Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced. - Do not invent cryptography, security guarantees, APIs or compliance claims. - Add a focused test for every destructive, security-sensitive or data-loss path the plan names. - Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs".
BUILD_PLAN.md
# Build plan · Algolia Instant, typo-tolerant search over your own content without writing a search engine: Meilisearch on a small box behind Caddy, an idempotent indexing script, a search-only key for the browser, and a search box under 5 KB that works without JavaScript too. Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note. ## Phase 1 · Run it Meilisearch bound to localhost with a master key, Caddy in front. ### Steps 1. Install and run with MEILI_MASTER_KEY, bound to 127.0.0.1:7700 ```sh meilisearch --master-key $MEILI_MASTER_KEY --http-addr 127.0.0.1:7700 ``` 2. Caddyfile with reverse_proxy and TLS Files: `Caddyfile` ### Done when - [ ] The health endpoint answers over HTTPS - [ ] The master key is required for admin calls ## Phase 2 · Index Documents with id, title, url, body and tags; idempotent. ### Steps 1. Write index.mjs reading CONTENT_DIR into documents and setting searchable and displayed attributes ```sh mkdir search-index && cd search-index && git init && npm init -y && npm pkg set type=module && npm install meilisearch@0.4 mkdir -p content && cp .env.example .env ``` 2. Make it idempotent on a content hash; delete removed documents ### Done when - [ ] Re-running adds nothing - [ ] A changed document updates - [ ] A deleted one disappears ## Phase 3 · Keys A search-only key for the browser; the master key never leaves the server. ### Steps 1. Create a search-only API key scoped to the index 2. Put it in the page; verify it cannot write ### Done when - [ ] The browser key can search - [ ] It cannot add documents ## Phase 4 · The box Results as you type, highlighted, keyboard-driven, under 5 KB, degrades to a form. ### Steps 1. Vanilla-JS search box with debounce and highlighting 2. A server-rendered /search?q= fallback for JavaScript off ### Done when - [ ] A typo still finds the right result - [ ] Fully keyboard operable - [ ] Under 5 KB of JavaScript ## Phase 5 · Operate Service, snapshots, reindex on deploy. ### Steps 1. systemd unit, nightly snapshot, reindex step in your deploy 2. README: the key model in two sentences and how to reindex Files: `README.md` ### Done when - [ ] A restore from snapshot searches correctly ## Not in this build - Merchandising rules, AI ranking, the global edge: commerce money. ## After v1, if you want it - Faceted filters - Multi-index federated search
.env.example
# Copy to .env and fill in. Never commit .env; this file documents it. # Required · secret. openssl rand -base64 32; admin key, server-side only. MEILI_MASTER_KEY=long-random # Required. Public API address behind Caddy. MEILI_URL=https://search.yourdomain.com # Optional. Generated in Phase 3; safe for the browser. MEILI_SEARCH_KEY=... # Required. Where the indexer reads from. CONTENT_DIR=./content
PRODUCT.md
# Algolia · product brief ## Problem Typo-tolerant instant search over your own data is a solved open-source problem: Meilisearch or Typesense on a small box gives you the core in an afternoon. What Algolia adds is the managed global edge, the merchandising and AI ranking layer, and not operating anything. ## Product outcome Search you operate with a relevance loop, at a fraction of the hosted price, with the edge stated as the thing you gave up. ## Target user A builder who needs a maintainable product foundation, not a one-off demo. ## Required capabilities - a VPS with a few GB of RAM - your data as JSON ## Explicit non-goals for v1 - Merchandising rules, AI ranking, the global edge: commerce money. - the global distributed search network - merchandising, rules and A/B testing - AI ranking and personalization - zero operations ## Success criteria - Search-only key verified read-only - Reindex idempotence verified - Snapshot restore verified
BRIEF.md
# Build brief · Algolia The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins. Build me site search like Algolia for my own content. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. ### Rule zero Do not write a search engine. Ranking, typo tolerance and prefix matching are years of work that Meilisearch already did. Deploy it and build the thin layer around it. ### Stack (fixed, do not substitute) - Meilisearch on a small VPS behind Caddy, or its Docker image. A Node indexing script. A vanilla-JS search box, no framework. ### Phase 1 · Run it Build: Meilisearch with a master key in .env, bound to localhost, Caddy in front with TLS. Done when: the health endpoint answers over HTTPS and the master key is required for admin calls. Do not build yet: indexing, UI. ### Phase 2 · Index Build: an indexing script that reads your content (Markdown, JSON or a database) into documents with id, title, url, body and tags, sets searchable and displayed attributes, and runs idempotently. Done when: re-running adds nothing, a changed document updates in place, and a deleted one disappears. ### Phase 3 · Keys Build: a search-only API key scoped to the index for the browser; the master key never leaves the server. Done when: the browser key can search and cannot add documents. ### Phase 4 · The box Build: a search input with results as you type, highlighting, keyboard navigation, and a debounce. Under 5 kB of JavaScript. Works as a normal form submit when JS is off. Done when: a typo still finds the right result and the box is fully keyboard operable. ### Phase 5 · Operate Build: a systemd unit, snapshot backups, index rebuild on deploy, and the README. Done when: a restore from snapshot searches correctly. ### Out of scope (and why) - Merchandising rules, AI ranking, the global edge. That is commerce money. ### README must contain - The key model in two sentences. - How to reindex.
ARCHITECTURE.md
# Architecture · Algolia ## Stack | Part | Choice | Why | | --- | --- | --- | | Engine | Meilisearch | rule zero: do not write a search engine | | Indexer | A Node script | your content to documents, idempotently | | Hosting | A VPS with a few GB of RAM behind Caddy | the index lives in memory | ## Modules Each module has one owner concern and a documented way to replace it. | Module | Owns | How to replace it | | --- | --- | --- | | Engine | Meilisearch | Typesense with the same document shape | | Indexer | content to documents | Any source | | Keys | master vs search-only | Tenant tokens later | | Box | the UI | Any client | ## Configuration Every runtime setting is an environment variable documented in `.env.example`, validated at startup, with a safe local default wherever one exists. - `MEILI_MASTER_KEY` · required, secret · openssl rand -base64 32; admin key, server-side only. - `MEILI_URL` · required · Public API address behind Caddy. - `MEILI_SEARCH_KEY` · optional · Generated in Phase 3; safe for the browser. - `CONTENT_DIR` · required · Where the indexer reads from. ## Production baseline - Security: least privilege, input validation at every boundary, secret redaction in logs, rate limits on abuse-prone paths, no invented security primitives. - Data: explicit schema and migrations, transactional writes where integrity matters, backup and restore procedures that have been exercised. - Integrations: adapters around third-party providers, idempotent webhook or job processing, bounded retries, timeouts. - Observability: structured logs with request or operation ids, an error-tracking hook, and health and readiness checks where a server exists. - Quality: unit tests for domain rules, integration tests at module boundaries, one end-to-end test of the critical path. ## Decision records For each dependency in the stack table, keep a short note: why it was chosen, its failure mode, and how it is replaced. Do not add infrastructure until a requirement in `PRODUCT.md` justifies it.
AGENTS.md
# Agent instructions · Algolia product build - Read `PRODUCT.md` and `ARCHITECTURE.md` before changing code. The stack is fixed: Meilisearch, A Node script, A VPS with a few GB of RAM behind Caddy. - Implement milestone by milestone from `MILESTONES.md`; keep each change reviewable and leave the application runnable at every commit. - Treat authentication, payments, encryption, imports, webhooks and destructive actions as high-risk boundaries when present. - Never invent cryptography or silently weaken a requirement to make a check pass. - Put every external service behind an interface with a deterministic fake for tests. - Add migrations and rollback or recovery notes for every persistent data change. - Log useful operational context without credentials, tokens, passwords or personal data. - Update documentation and run every check before completing a milestone.
MILESTONES.md
# Delivery milestones · Algolia Estimated effort: **weekend** for the indie phases; the production-only milestones add the trust and operability layer. ## M1 · Run it Meilisearch bound to localhost with a master key, Caddy in front. ### Steps 1. Install and run with MEILI_MASTER_KEY, bound to 127.0.0.1:7700 ```sh meilisearch --master-key $MEILI_MASTER_KEY --http-addr 127.0.0.1:7700 ``` 2. Caddyfile with reverse_proxy and TLS Files: `Caddyfile` ### Done when - [ ] The health endpoint answers over HTTPS - [ ] The master key is required for admin calls ## M2 · Index Documents with id, title, url, body and tags; idempotent. ### Steps 1. Write index.mjs reading CONTENT_DIR into documents and setting searchable and displayed attributes ```sh mkdir search-index && cd search-index && git init && npm init -y && npm pkg set type=module && npm install meilisearch@0.4 mkdir -p content && cp .env.example .env ``` 2. Make it idempotent on a content hash; delete removed documents ### Done when - [ ] Re-running adds nothing - [ ] A changed document updates - [ ] A deleted one disappears ## M3 · Keys A search-only key for the browser; the master key never leaves the server. ### Steps 1. Create a search-only API key scoped to the index 2. Put it in the page; verify it cannot write ### Done when - [ ] The browser key can search - [ ] It cannot add documents ## M4 · The box Results as you type, highlighted, keyboard-driven, under 5 KB, degrades to a form. ### Steps 1. Vanilla-JS search box with debounce and highlighting 2. A server-rendered /search?q= fallback for JavaScript off ### Done when - [ ] A typo still finds the right result - [ ] Fully keyboard operable - [ ] Under 5 KB of JavaScript ## M5 · Operate Service, snapshots, reindex on deploy. ### Steps 1. systemd unit, nightly snapshot, reindex step in your deploy 2. README: the key model in two sentences and how to reindex Files: `README.md` ### Done when - [ ] A restore from snapshot searches correctly ## M6 · Relevance tuning (production only) Synonyms, ranking rules, and a way to measure. ### Steps 1. Configure synonyms and ranking rules for your domain 2. Log queries with zero results and review them weekly ### Done when - [ ] Top zero-result queries are visible - [ ] A synonym fixes one of them
OPERATIONS.md
# Operations · Algolia ## Backup Nightly snapshots; the index is rebuildable from content. ## Restore Load the snapshot or reindex. Do a restore drill before the first real user, and write the date here when it passes. ## Monitoring Uptime on health; zero-result rate. ## Incident checklist A leaked master key: rotate and regenerate search keys. 1. Contain the issue without destroying evidence or user data. 2. Record the timeline and affected scope. 3. Rotate exposed secrets and revoke compromised sessions or credentials. 4. Restore from a verified backup when needed. 5. Document the root cause, the remediation and the regression test. ## Release gate - [ ] Search-only key verified read-only - [ ] Reindex idempotence verified - [ ] Snapshot restore verified ## Launch constraint Do not market omitted Algolia capabilities as implemented. The non-goals in `PRODUCT.md` remain user-visible limitations until they are deliberately delivered.
.env.example
# Copy to .env and fill in. Never commit .env; this file documents it. # Required · secret. openssl rand -base64 32; admin key, server-side only. MEILI_MASTER_KEY=long-random # Required. Public API address behind Caddy. MEILI_URL=https://search.yourdomain.com # Optional. Generated in Phase 3; safe for the browser. MEILI_SEARCH_KEY=... # Required. Where the indexer reads from. CONTENT_DIR=./content
$ choose a build depth, inspect the files, then open the complete pack in your agent
Commerce teams pay for milliseconds everywhere and for tuning relevance without engineers. A blog search does not need either.
xthe global distributed search network
xmerchandising, rules and A/B testing
xAI ranking and personalization
xzero operations
share on X ↗"I just replaced Algolia with one prompt"
Vibecode Algolia
Kinda. The core of Algolia is buildable in a weekend with the prompt on this page, but there are real gaps: the global distributed search network, merchandising, rules and A/B testing. Read the honest list above before committing.
How much does Algolia cost?
Algolia's pricing is usage-based or varies by plan · Free: 10K search requests and 50K records a month. Grow: 10K requests included then $0.50 per additional 1K, 100K records then $0.40 per 1K. Grow Plus $1.75 per 1K requests with AI ranking. Elevate custom, annual..
What do I lose by replacing Algolia?
Honestly: the global distributed search network; merchandising, rules and A/B testing; AI ranking and personalization; zero operations. If any of those are load-bearing for you, keep paying.
Is there an open-source alternative to Algolia?
Yes: Meilisearch (open-source instant search engine), Typesense (open-source typo-tolerant search). Using prior art is also vibecoding; the prompt is for when you want it exactly your way.