SearXNG

​

Overview

​

Architecture

• SearXNG server — A standard (stateless) workload serving the UI and the API on port 8080. replicas instances run behind the platform load balancer with no session affinity, because there is no server-side session to pin: preferences live in a cookie in the user’s own browser.
• Redis and Sentinel (optional, on by default) — The redis template as a subchart, pinned to one master and one sentinel. It holds the rate limiter’s counters and the shared state a multi-replica install needs. It is not a result cache — search results are never stored there.
• Settings — The rendered settings.yml is mounted read-only at /etc/searxng/settings.yml from a template-created secret.
• Signing key — Supplied by you as a prerequisite secret and injected as an environment variable, so it is never written into the rendered configuration and never enters the Helm release.
• No volume set, no database, and no login. Everything durable is either your prerequisite secret or a cookie in a user’s browser.

​

What Gets Created

• Standard SearXNG Workload — {release}-searxng, serving the UI and API on port 8080 with replicas replicas and configurable CPU and memory.
• Stateful Redis and Sentinel Workloads — {release}-redis on 6379 and {release}-sentinel on 26379, created only when redis.enabled is true. Both are in-memory; neither mounts a volume.
• Settings Secret — An opaque secret ({release}-searxng-settings) holding the rendered settings.yml.
• Start-Script Secret — An opaque secret ({release}-searxng-startup) holding the container’s start-up script, created only when the bundled datastore is enabled.
• Identity & Policy — An identity bound to the SearXNG workload and a policy granting it reveal on exactly the secrets it reads: the settings secret, your prerequisite signing key, the start-up script, and the datastore password when redis.redis.auth.password.enabled is true. The Redis subchart brings its own identity, policy, and config secret.

​

Prerequisites

printf '%s' "$(openssl rand -hex 32)" | \
  cpln secret create-opaque --name my-searxng-secret-key --encoding plain -f -

cpln workload get-deployments {release}-searxng --gvc {gvc} -o yaml

​

Installation

​

Choosing an Access Shape

​

Reaching the UI

cpln port-forward {release}-searxng 8080:8080 --gvc {gvc}

cpln workload get {release}-searxng --gvc {gvc} -o yaml

​

Configuration

# ─── SearXNG ──────────────────────────────────────────────────────
image: searxng/searxng:2026.8.22-9fea41204
replicas: 1                    # 1 = proven single shape; >=2 = load-balanced tier (limiter state is shared via redis)
resources:
  minCpu: 250m
  maxCpu: 1000m
  minMemory: 256Mi
  maxMemory: 512Mi

# ─── Search behaviour ─────────────────────────────────────────────
instanceName: SearXNG          # shown in the UI and returned by /config
formats:                       # allowed: html, json, csv, rss (upstream default is html only)
  - html
  - json                       # the JSON API AI agents call: /search?q=...&format=json
imageProxy: true               # proxy result images through this instance instead of hotlinking third parties
baseUrl: ""                    # set only behind a custom domain, e.g. https://search.example.com (empty = derive from request)
limiter:
  enabled: false               # bot-detection rate limiter; requires redis.enabled. NOTE: it 429s non-browser clients, including the JSON API
extraSettings: {}              # merged into settings.yml verbatim, e.g. {general: {enable_metrics: false}}

# ─── Signing key (USER-CREATED PREREQUISITE — MUST EXIST BEFORE INSTALL) ─
# Opaque secret, encoding: plain, whose payload is the session/CSRF signing key.
# Create it FIRST — a missing secret WEDGES the deployment silently (logs
# return zero lines; the reason appears only in status.versions[].message).
# The exact create command is in the README Prerequisites section.
# Never rotate it casually: it invalidates every saved preference cookie.
secretKey:
  secretName: my-searxng-secret-key

# ─── Access ───────────────────────────────────────────────────────
# SearXNG has NO login of any kind. Default is private — see the README
# "Reaching the UI" section for the port-forward command.
# Before setting publicAccess.enabled: true, turn limiter.enabled on.
publicAccess:
  enabled: false               # true = UI + API on the canonical *.cpln.app endpoint, unauthenticated
internalAccess:
  type: same-gvc               # options: none, same-gvc, same-org, workload-list
  workloads: []                # used only with workload-list
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

# ─── Redis (subchart: redis) — limiter counters / shared state ────
# Pinned single-instance ON PURPOSE: SearXNG's valkey client is not
# Sentinel-aware, so it must talk to the master directly. redis.replicas
# must stay 1 (validated). One sentinel is required by the redis chart's
# boot-time master discovery; it cannot be scaled to zero.
redis:
  enabled: true                # false = no datastore; limiter must then stay off
  redis:
    image: redis:8
    replicas: 1                # MUST be 1 (validated) — SearXNG must reach the master directly
    auth:
      password:
        enabled: false         # true = require AUTH; password is wired into the connection URL
        value: change-me-searxng-redis
    resources:
      minCpu: 80m
      maxCpu: 200m
      minMemory: 128Mi
      maxMemory: 256Mi
  sentinel:
    image: redis:8
    replicas: 1
    resources:
      minCpu: 80m
      maxCpu: 200m
      minMemory: 128Mi
      maxMemory: 256Mi

​

Image and resources

• image — The SearXNG server image. Pin a concrete tag.
• replicas — Number of instances. 1 is the proven single shape; 2 or more form a load-balanced tier that shares limiter state through the bundled datastore. At two replicas, a rolling restart served 300 of 300 requests and an abrupt replica loss served 75 of 75, with the replacement serving 11 seconds later.
• resources.minCpu / resources.maxCpu / resources.minMemory / resources.maxMemory — CPU reservation and limit, memory reservation and limit for the SearXNG container.

​

Search Behavior

• instanceName — The name shown in the UI and returned by /config.
• formats — Output formats the instance will serve. Allowed values are html, json, csv, and rss; upstream defaults to html only, and this template ships [html, json]. A format that is not listed is refused with 403, so removing json disables the API.
• imageProxy — When true (default), result images are relayed through this instance instead of being hotlinked from third parties, so a user’s browser never contacts the origin. On a public instance that also makes it an open image relay.
• baseUrl — Set only when the instance sits behind a custom domain (for example https://search.example.com). Empty derives the URL from the request, which is correct for the canonical *.cpln.app endpoint. It drives the opensearch.xml document browsers use to add the instance as a search provider.
• limiter.enabled — The bot-detection rate limiter. Off by default; requires redis.enabled. See Choosing an Access Shape before turning it on.
• extraSettings — Merged verbatim into settings.yml over the keys above, so anything in the upstream settings reference is reachable — engine selection, safe_search, outgoing timeouts. An override of a key this template also sets wins cleanly instead of producing a duplicate YAML key.

​

Signing Key

• secretKey.secretName — The name of your prerequisite opaque secret, whose whole payload is the signing key. Every replica reads the same one, which is what lets any replica verify any user’s preference cookie. The chart grants the workload reveal on exactly that secret.

​

Access

• publicAccess.enabled — When true, the UI and API are served over HTTPS on the automatically assigned *.cpln.app endpoint, unauthenticated. When false (default), external requests are refused at the edge with 403.
• internalAccess.type — Internal firewall scope of the workload:

• internalAccess.workloads — Workload links (//gvc/GVC_NAME/workload/WORKLOAD_NAME), used only with workload-list.

​

Redis

• redis.enabled — When false, no datastore is deployed and SearXNG runs standalone. limiter.enabled must then stay false; the chart refuses to render the combination, because without the datastore SearXNG would install no limiter at all while its configuration still claimed one.
• redis.redis.replicas — Must stay 1, and the chart rejects anything else. SearXNG’s client is not Sentinel-aware and has to reach the master directly, so extra replicas would serve read-only connections and silently break the limiter. One sentinel is required by the Redis chart’s boot-time master discovery and cannot be scaled to zero.
• redis.redis.auth.password.enabled / redis.redis.auth.password.value — When enabled, the datastore requires AUTH and the password is wired into the connection URL through a template-created secret. Change the placeholder value if you turn this on.
• redis.redis.image / redis.sentinel.image / redis.redis.resources / redis.sentinel.resources — Image and CPU and memory bounds for the two datastore workloads.

​

Using the JSON API

curl 'http://{release}-searxng.{gvc}.cpln.local:8080/search?q=control+plane&format=json'

​

Connecting

​

Important Notes

• There is no authentication of any kind. With publicAccess.enabled: true the UI, the API, /config, and /stats are all served to anyone who finds the endpoint. Turn limiter.enabled on before you publish.
• The limiter blocks the JSON API for non-browser clients. Plain curl and HTTP client libraries get 429 on /search while the limiter is on. Pick one of the two shapes in Choosing an Access Shape deliberately.
• /config and /stats are unauthenticated and go public with the UI. /config lists your engine and plugin configuration. Setting extraSettings: {general: {enable_metrics: false}} stops collecting the data behind /stats.
• /metrics is not open, and cannot be opened without a password. Upstream gates it on general.open_metrics, which is empty by default, so the route returns 404 as shipped. Setting it through extraSettings enables the route and requires that password over HTTP basic auth.
• Create the signing-key secret before installing, and treat it as write-once. A missing secret wedges the deployment with zero log output; rotating it invalidates every saved preference cookie.
• redis.redis.replicas must stay 1, and limiter.enabled requires redis.enabled. Both are enforced at render time, so a bad combination fails the install rather than shipping a silently unlimited instance.
• The datastore holds no durable data. If it restarts, limiter counters reset and nothing is lost, because search results were never stored there.
• Going public throttles your own results. Upstream engines answer heavy or bot-like traffic with CAPTCHAs and rate limits, which shows up as fewer results rather than an error. A limiter and a modest instance are what keep result quality up.
• The first helm upgrade after an install can re-apply resources that did not change, including the bundled datastore, which bounces those workloads once. Values were byte-identical across the re-apply in testing, and later upgrades of the same release report everything unchanged. At replicas: 1 budget a brief blip on that first upgrade.
• Firewall changes take effect after a delay — flipping publicAccess.enabled or internalAccess.type can take from twenty seconds to a couple of minutes to be enforced after the upgrade reports success.
• Install into a single-location GVC unless you mean otherwise. A workload runs in every location its GVC has, so extra locations multiply both the instance count and the outbound query volume upstream engines see from you.
• Uninstalling removes everything the template created — workloads, secrets, identity, and policy, with no volume sets left behind. Your own signing-key secret survives, so a reinstall against the same name keeps preference cookies valid.

​

External References