Developer Tools guide
SearXNG Docker Compose Setup: Private Search Without a Public Abuse Magnet
Use the current official SearXNG Compose template, persist configuration, enable appropriate limiting, and choose public exposure deliberately.
Published and reviewed by OpenAlt · September 25, 2026
TL;DR
The safest SearXNG Docker Compose setup is private by default. Fetch the current official Compose template, keep its configuration in a persistent core-config directory, configure .env and settings.yml, and place the service behind a reverse proxy only when needed. Valkey supports limiter and bot-protection features. A public instance is possible, but it becomes an operational responsibility rather than a simple web service.
TOC
- Private or public?
- Prerequisites
- Fetch and configure the official template
- Start and verify
- Reverse proxy, TLS, and secret key
- Limiter and Valkey
- Persistence, backup, and updates
- Migration from old
searxng-docker - Troubleshooting
- FAQ
Private or public?
Keep SearXNG private unless you have a clear reason, monitoring, and abuse controls. Private access works well for one person, a household, or a trusted team. Public access means handling rate limits, abusive traffic, privacy disclosures, upstream blocking, and availability.
| Choice | Best for | Main responsibility |
|---|---|---|
| Private | Personal or household search | Authentication or network access control |
| Trusted team | Small internal group | User access, quotas, and monitoring |
| Public | A maintained community service | Abuse response, limiter tuning, privacy policy, and uptime |
SearXNG aggregates results from other search engines. It does not eliminate upstream restrictions. A public endpoint can attract automated traffic, cause upstream engines to block requests, and create complaints that a private deployment never encounters.
Prerequisites
Use a Linux host, Docker Engine, and the Docker Compose plugin. You also need permission to bind the chosen local port and enough storage for images, logs, and configuration backups.
If you have no special installation preference, the official installation documentation recommends either a container deployment or the installation script. This guide uses the current official Compose method.
Fetch and configure the official template
Start in a dedicated directory and download both files from the current SearXNG repository. Do not copy an old tutorial’s Compose file.
mkdir -p ~/searxng
cd ~/searxng
curl -fsSL https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
-o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example \
-o .env.example
cp .env.example .env
mkdir -p core-config
The official container documentation specifically uses container/docker-compose.yml and .env.example, and documents migration away from the older searxng-docker directory. Read the current Docker installation guide whenever the template changes.
Edit .env before starting. Set the hostname or base URL required by the template, choose a local bind address and port, and review image and worker settings. For a private deployment, bind Docker to loopback or expose it only through a trusted network. Do not bind it broadly just because the service is reachable from inside the container network.
Generate a strong secret key:
openssl rand -hex 32
Place the result in the secret variable named by the current .env.example, commonly SEARXNG_SECRET. Keep .env readable only by administrators. Changing the secret later can invalidate sessions or other state, so treat it as a long-lived credential.
After the first start, review core-config/settings.yml. Use the SearXNG settings reference for documented options. Keep the configuration narrow: enable only the engines and formats you need, choose an appropriate user interface policy, and configure the limiter before considering public access.
Start and verify
Validate the rendered Compose configuration, then start the service:
docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=100 searxng valkey
A healthy deployment should show running containers and no repeating configuration, permission, DNS, or connection errors. Open the configured base URL from an allowed network and run a few searches. Verify that the result page loads, at least several engines respond, and the service remains reachable after restarting the containers.
If the generated configuration is not yet present, allow the container to initialize, then inspect core-config. Make changes there rather than editing files inside a running container. Container layers are disposable; the mounted configuration directory is the durable part.
Reverse proxy, TLS, and secret key
For a LAN-only deployment, direct access through a private address may be enough. For a hostname or remote access, place SearXNG behind a reverse proxy such as Caddy, Nginx, or Traefik.
Keep SearXNG bound to localhost or an internal Docker network, terminate HTTPS at the proxy, and forward the original host and client information. Set the SearXNG base URL to the public HTTPS address so generated links and redirects are correct. Do not expose the backend port directly when the proxy is intended to enforce TLS, access control, or authentication.
A reverse proxy does not replace application security. Protect administrative access, avoid leaking .env or core-config, and rotate credentials deliberately rather than during routine troubleshooting.
Limiter and Valkey
Valkey is included because SearXNG limiter and bot-protection features need a shared data store. Keep the Valkey service in the Compose project unless you have deliberately redesigned those features.
For a private instance, limiter settings still help prevent accidental overload and compromised clients. For a public instance, they are essential. Configure thresholds conservatively, test normal searches, and monitor rejected requests. Rate limiting cannot prevent every upstream block, but it reduces burst traffic and makes abuse easier to control.
Persistence, backup, and updates
Back up core-config, .env, and any locally modified Compose files. The core-config directory contains the persistent SearXNG configuration, including settings.yml and related runtime configuration. Protect the backup because it may contain the secret key and access-sensitive settings.
Before upgrading:
cp -a core-config core-config.backup
cp .env .env.backup
docker compose config
docker compose pull
docker compose up -d
docker compose logs --tail=100 searxng
The exact backup destination can be an encrypted disk or an administrator-controlled backup system. Do not rely on container layers as backups.
Update both official templates cautiously. Re-download the current docker-compose.yml and .env.example into a review location, compare changes with your local files, and merge new variables manually. Never overwrite .env blindly. Then pull updated images and recreate containers during a maintenance window. Check startup logs and perform searches after every upgrade.
Migration from old searxng-docker
Old searxng-docker instructions are mixed into many obsolete guides. The current official documentation includes a migration path because directory layout, variables, and service definitions can change.
Stop the old stack, make a complete copy of its configuration and .env, fetch the current official template, and map the existing SearXNG configuration into the new core-config mount. Compare every environment variable and volume path. Do not delete the old directory until the new stack has passed search, restart, proxy, and backup checks.
Troubleshooting
Blocked engines and timeouts are usually upstream, networking, or rate-limit problems rather than proof that Compose is broken. Start with:
docker compose logs -f searxng
docker compose exec searxng getent hosts valkey
Check DNS, outbound HTTPS, system time, proxy headers, and the engine status shown by SearXNG. Upstream providers may impose quotas, CAPTCHAs, throttling, or temporary blocks. Disable consistently unreliable engines or adjust documented timeout and limiter settings instead of increasing every timeout blindly.
If Valkey errors appear, confirm that both services share the Compose network and that the configured service name matches the current template. If settings disappear after recreation, verify that core-config is mounted and writable; editing files inside the container will not persist.
A sensible next step
Once the private/public decision is clear, browse OpenAlt’s self-hosting directory, explore related AI and LLM tools, or continue with the self-hosting beginner guide.
FAQ
Is SearXNG a search engine or an aggregator?
SearXNG is a metasearch aggregator. It queries configured upstream engines and presents combined results through one interface. Its privacy benefits come from controlling the frontend and reducing direct tracking by upstream services, but upstream availability and policies still apply.
Should the instance be public?
Usually no. Keep it private for personal, household, or trusted-team use. Make it public only when you are prepared to operate abuse controls, rate limiting, monitoring, privacy documentation, and upstream-engine management.
What must persist?
Persist the core-config directory, .env, and any customized Compose files. The configuration directory holds SearXNG settings; .env holds deployment values and the secret. Container filesystems and images can be recreated.
Why is Valkey included?
Valkey provides the shared storage needed by limiter and bot-protection features in the official Compose design. Removing it without changing those features can produce errors or leave a public service insufficiently protected.
How do you update an old searxng-docker install?
Back up the old directory and .env, fetch the current official Compose template, compare variables and volume mappings, move the retained configuration into the new core-config layout, and test before deleting anything. Follow the official Docker migration documentation.