How to Self-Host SearXNG in 2026: Search API, Rate Limits and TLS

Most SearXNG installation notes end at the first page load. That is too early: engines block the server IP or formats omit json for API clients. A useful production test is more demanding — submit both HTML and JSON searches, confirm several engines contribute results and trigger the configured limiter from a test client.

SearXNG's role is straightforward: privacy-focused metasearch engine and search API. Its operational boundary includes more than the web process, so the dependency, stored state and public route all have to be named explicitly before real data arrives.

Define success for SearXNG first

Do not let the SearXNG image choose production architecture by accident. The image supplies a process on 8080; storage, routing and external requirements still need deliberate lifecycles. The network contract for SearXNG is Redis or Valkey when limiter and bot-detection features are enabled. Keep private endpoints on internal DNS, permit only required outbound calls and give SearXNG a scoped service credential.

The deployment is ready for deeper testing when it can submit both HTML and JSON searches, confirm several engines contribute results and trigger the configured limiter from a test client. Follow the transaction in logs and watch upstream-engine latency, simultaneous queries, result parsing and bans applied to the server IP. Those observations reveal whether the current topology isolates the right component.

Separate replaceable containers from lasting data

Make a recovery manifest for SearXNG: settings.yml, limiter configuration and any local plugins. Mount /etc/searxng before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. Check ownership and free space now, because a mounted but unwritable path behaves like no persistence at all.

Back up to a failure domain separate from the running server. Recreate SearXNG from its pinned image and verify that custom engines, formats, limiter rules and proxy settings return and a known query produces multi-engine results. The persistent-volume guide helps translate that exercise into snapshot and retention policy.

Close temporary setup access

Bootstrap credentials are temporary; the trust model is permanent. With SearXNG, watch for shipping the example secret_key or disabling rate controls on a public endpoint, and keep a non-default secret key, enable abuse controls and expose JSON only when an agent or application requires it.

Treat SEARXNG_SECRET according to its SearXNG role: keep sensitive values out of Git, document rotation effects and never substitute a public example in production. Run the image without unnecessary Linux capabilities and expose only the public application route. Keep administrator activity visible without recording secret values.

Record a known-good SearXNG deployment

Convert the SearXNG smoke test into a repeatable release command or short runbook. Its output must demonstrate this outcome: submit both HTML and JSON searches, confirm several engines contribute results and trigger the configured limiter from a test client. Record the application version, container digest, route hostname and test-data identifier with the result.

Run the same check after a routine container swap and after restoring settings.yml, limiter configuration and any local plugins elsewhere. The restore has succeeded when custom engines, formats, limiter rules and proxy settings return and a known query produces multi-engine results. Compare timing and consumption related to upstream-engine latency, simultaneous queries, result parsing and bans applied to the server IP; a large change is worth investigation even when the final action still passes.

Then exercise a safe failure: temporarily deny the test identity access to Redis or Valkey when limiter and bot-detection features are enabled. Confirm that SearXNG surfaces the fault and returns to normal without destructive manual edits. Preserve only the necessary, redacted log excerpt. This four-part gate covers startup, persistence, recovery and failure handling.

Run the first production-shaped instance

Use the container as a replaceable runtime, not as the location of truth.

docker run -d \
  --name searxng \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v searxng-data:/etc/searxng \
  -e SEARXNG_SECRET=replace-with-a-long-random-value \
  searxng/searxng:latest

Add the reviewed connection settings for Redis or Valkey when limiter and bot-detection features are enabled; use private names for private services. Inspect the container user, writable paths and bound listener before exposing it. Run the complete action — submit both HTML and JSON searches, confirm several engines contribute results and trigger the configured limiter from a test client — and save the exact image reference that produced the result.

Prevent proxy success from masking application failure

Expose one HTTPS hostname for SearXNG; keep raw port 8080 private. Set server base_url and trusted proxy headers for HTTPS. This prevents browsers and API clients from learning two competing addresses.

From a clean client, run the known-good transaction and inspect the first failing request. Use the custom-domain guide when DNS or TLS is wrong. Treat “engines block the server IP or formats omit json for API clients” as a separate application diagnosis once the route is proven.

Logs that answer the next question

The first useful operational metric for SearXNG is whether it can submit both HTML and JSON searches, confirm several engines contribute results and trigger the configured limiter from a test client. Pair that with saturation signals for upstream-engine latency, simultaneous queries, result parsing and bans applied to the server IP. A process-only probe should not call expensive dependencies or restart the container because an upstream is briefly unavailable.

Treat upgrades as data changes because settings syntax, engine definitions and limiter behavior can shift, so deploy configuration and image changes as one review. Pin versions, rehearse on restored state and keep the previous image available until a rollback remains valid. When engines block the server IP or formats omit json for API clients, preserve logs from before the restart; they usually contain the causal message.

Attach SearXNG to Dockup's lifecycle

The platform layer for SearXNG consists of port 8080, ingress, TLS, runtime configuration, storage and dependency reachability. Dockup can reproduce those pieces for its own infrastructure or a server the customer connects.

Then the operator finishes the product layer: set server base_url and trusted proxy headers for HTTPS; enforce this access rule — keep a non-default secret key, enable abuse controls and expose JSON only when an agent or application requires it; and run “submit both HTML and JSON searches, confirm several engines contribute results and trigger the configured limiter from a test client”. Recording that test alongside the deployment avoids confusing automated provisioning with application readiness.

Frequently asked questions

What does SearXNG need for a production deployment?

Route the SearXNG container on port 8080 through one HTTPS origin. The supporting network requirement is Redis or Valkey when limiter and bot-detection features are enabled. Do not call SearXNG ready until you can submit both HTML and JSON searches, confirm several engines contribute results and trigger the configured limiter from a test client.

Which SearXNG data belongs in a backup?

Persist /etc/searxng and include settings.yml, limiter configuration and any local plugins in the same recovery manifest. A clean SearXNG restore passes only when custom engines, formats, limiter rules and proxy settings return and a known query produces multi-engine results.

Does SearXNG require HTTPS behind a reverse proxy?

Use HTTPS for the public SearXNG origin and keep port 8080 on the internal route. Apply the SearXNG setting correctly: set server base_url and trusted proxy headers for HTTPS. For SearXNG, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a SearXNG upgrade be tested?

Restore current SearXNG state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because settings syntax, engine definitions and limiter behavior can shift, so deploy configuration and image changes as one review. Keep the previous SearXNG image until its data-migration and rollback boundary are understood.