Deploy to Cloudflare
A Ferroseek deployment is an ordinary Worker: the compiled engine is bundled into the Worker script. With a static index, the index parts are uploaded as static assets and the Worker is read-only. With the indexing API, indices live in an R2 bucket, writes go through a writer Durable Object, and a second Worker script runs compactions; see Deploy with the indexing API. You deploy with Wrangler.
Before you deploy
Section titled “Before you deploy”You need a Cloudflare account that Wrangler is logged in to (npx wrangler login), and:
-
The engine built for WebAssembly:
npm run wasm:build -
An index in the Worker’s assets directory. For the standalone Worker that is
worker/assets/index/:npm run index:build:100k -
Secrets, if the Worker should require authentication (standalone Worker only; see Run a standalone search Worker).
Deploy the standalone Worker
Section titled “Deploy the standalone Worker”npx wrangler deploy --config worker/wrangler.jsoncworker/wrangler.jsonc declares the indexing API’s bindings as well (the bucket, the writer and the compactor), so Wrangler needs the bucket and the compactor script to exist; create them as described below even if you only serve the static index for now. The variable FERROSEEK_SOURCE: "assets" in that file keeps the Worker on the static index, read-only.
Wrangler uploads the Worker and the contents of worker/assets/. Because the configuration sets run_worker_first: true, the index files are reachable only through the ASSETS binding, not at a public URL. Observability is turned on in the same file, so request logs and CPU-time analytics appear in the Cloudflare dashboard.
Check it:
curl -s https://<your-worker>.workers.dev/Deploy an embedded Worker
Section titled “Deploy an embedded Worker”Deploy your own Worker the same way, from its directory or with --config pointing at its Wrangler file. Make sure the index is inside its assets directory at the path its assetsIndexSource reads, and that run_worker_first covers that path.
What to expect after a deploy
Section titled “What to expect after a deploy”- The first request in each new isolate loads the index. In the production measurement, loading took 226 to 313 ms and the first request 0.84 to 1.35 s in total.
- The first request after uploading new index files was slower still: 4.5 s in the one measurement.
- Memory after loading the 100k-product index was about 62 MB of the 128 MB isolate limit.
These are measurements of the proof of concept; see Performance for the conditions. If cold starts matter, send a request to new deployments before they take traffic.
Deploy with the indexing API
Section titled “Deploy with the indexing API”The indexing API is new. So far it has run only under wrangler dev with local R2 and Durable Objects; the steps below follow the configuration in the repository but have not yet been carried out against Cloudflare.
The pieces, as configured in worker/wrangler.jsonc (design 6.4):
{ "name": "ferroseek", "main": "src/index.ts", "rules": [{ "type": "CompiledWasm", "globs": ["**/*.wasm"], "fallthrough": false }], "r2_buckets": [{ "binding": "FERROSEEK_BUCKET", "bucket_name": "ferroseek-indices" }], "durable_objects": { "bindings": [ { "name": "FERROSEEK_WRITER", "class_name": "FerroseekWriter" }, { "name": "FERROSEEK_COMPACTOR", "class_name": "FerroseekCompactor", "script_name": "ferroseek-compactor" } ] }, "migrations": [{ "tag": "v1", "new_sqlite_classes": ["FerroseekWriter"] }], "vars": { "FERROSEEK_PREFIX": "ferroseek/", "FERROSEEK_FRESHNESS_MS": "1000", "FERROSEEK_MEMORY_BUDGET_BYTES": "77594624", "FERROSEEK_WRITER_ENGINE": "wasm" }}| Binding or variable | What it is |
|---|---|
FERROSEEK_BUCKET |
The R2 bucket holding every index: one manifest.json per index (the current generation) and immutable segment and tombstone objects |
FERROSEEK_WRITER |
The writer Durable Object class, one object per index, SQLite-backed; exported by this script |
FERROSEEK_COMPACTOR |
The compactor Durable Object, in the separate ferroseek-compactor script so a merge never shares memory with a search isolate |
FERROSEEK_FRESHNESS_MS |
The freshness window F: no search is answered from a manifest check older than this, and refresh=true answers after publish plus F |
FERROSEEK_MEMORY_BUDGET_BYTES |
Index data an isolate may hold across all indices (74 MiB); the writer bounds deltas against the same value |
FERROSEEK_REALTIME_GET |
Optional: reader serves real-time GETs from the searchable generation instead of the writer |
Steps:
-
Build both WebAssembly modules:
npm run wasm:build(search) andnpm run wasm:build:writer(the writer’s validator, delta builder and merger). -
Create the bucket and its lifecycle rule. Objects are written by the writer and the compactor only; compaction output is a multipart upload, so abort incomplete uploads after a day (R2’s default is seven):
npx wrangler r2 bucket create ferroseek-indicesnpx wrangler r2 bucket lifecycle add ferroseek-indices abort-multipart --abort-multipart-days 1 -
Deploy the compactor first, because the main Worker’s binding names its script:
npm run deploy:compactor(worker/compactor/wrangler.jsonc, with"limits": { "cpu_ms": 300000 }for merges of large indices). It merges up to 80 MiB of input (base plus deltas) inside the Worker; there is no fallback above that (see Compaction). -
Set the secrets.
FERROSEEK_USERNAME/FERROSEEK_PASSWORD(orFERROSEEK_API_KEY) for read-only clients, andFERROSEEK_WRITE_USERNAME/FERROSEEK_WRITE_PASSWORD(orFERROSEEK_WRITE_API_KEY) for clients that write:npx wrangler secret put FERROSEEK_WRITE_PASSWORD --config worker/wrangler.jsonc, and so on. -
Remove
FERROSEEK_SOURCEfrom the vars (or set it tor2) and deploy the main Worker. The first deployment applies thev1migration that creates the writer class. -
Bootstrap each index, either by adopting an offline build (
npm run adopt -- --url https://<worker> --index products --remote, withFERROSEEK_WRITE_USERNAME/FERROSEEK_WRITE_PASSWORDin the environment) or through the API (PUT /{index}, then_bulk). See Write through the API.
For an embedded engine, the application’s Worker gets the same bucket and Durable Object bindings, exports FerroseekWriter from @ferroseek/writer (after setWriterWasm(…) with the writer module), and passes them to createFerroseek:
import wasm from "@ferroseek/engine/wasm";import { createFerroseek, generationOptionsFromEnv } from "@ferroseek/engine";
const search = createFerroseek({ wasm, ...generationOptionsFromEnv(env) });// search.fetch(request, ctx) — pass the ExecutionContext so background manifest checks can finish.The example shop shows it with --env indexing in examples/shop-worker/wrangler.jsonc, and exposes the engine’s routes to its operators under /_search-admin/ with write credentials.
Run it locally
Section titled “Run it locally”npm run dev:indexing runs the Worker with --env local: Wrangler emulates the R2 bucket and the SQLite Durable Objects on disk, and the compactor is exported from the same script (FERROSEEK_COMPACTOR without script_name). npm run dev keeps serving the static index.
What to expect from writes
Section titled “What to expect from writes”Measured locally under wrangler dev (local R2 and Durable Objects, one machine; production numbers are not measured yet):
| Measure | Result |
|---|---|
Single-document write, refresh=false |
1.5 ms p50, 2.5 ms p95 |
1,000-item _bulk |
45 ms p50, 51 ms p95 (small documents); 104 ms p50 for 1,000 catalog updates |
refresh=true |
1,019 ms p50 (publish plus the 1 s freshness window) |
refresh=wait_for with refresh_interval: 1s |
2,027 ms p50 |
| A write without refresh visible in another isolate | 1.41 s p50, 1.42 s p95 |
Cold load of the 100k index (x-index-load-ms) |
from R2 91 to 327 ms, from static assets 97 to 209 ms, across runs on a loaded machine |
| Blocking base swap after compacting the 100k index | 284 to 299 ms, no request failed |
| Compaction of the 100k index with 4,800 changes | 0.85 to 0.90 s |
Limits to keep in mind
Section titled “Limits to keep in mind”| Limit | Value | Why it matters |
|---|---|---|
| Static asset file size | 25 MiB | Index parts are at most 20 MiB |
| Isolate memory | 128 MB | Index plus your application plus per-request working memory must fit |
| Startup time of the Worker’s global scope | about 1 s | The index is therefore loaded on the first request, not at module load |
| R2 writes to one key | 1 per second | Generations of one index are published at most once a second |
| Durable Object throughput | about 1,000 requests per second per object | One writer per index: use _bulk for loads, realtimeGet: "reader" for GET-heavy sites |
| Compaction input | 80 MiB of base plus deltas | Larger merges fail; the index stays within it under the default 74 MiB memory budget |
Check Cloudflare’s current Workers limits for your plan.