Workload · Running a private search engine

SearXNG Self Hosted: Your Own Private Metasearch, Set Up Properly

Running SearXNG yourself takes one small Linux server with Docker, the project's two-container Compose file, and three decisions: keep the secret key the container generates, publish the port only to the server itself, and turn the limiter and Valkey on only if other people will use it. SearXNG sends your query to many search engines and merges what comes back, so the engines see your server's address rather than your own.

The short version
  1. Official install: two containers, SearXNG and Valkey, from the project's own Compose file
  2. The container writes a random secret key on its first start; SearXNG refuses to run with the placeholder
  3. Bind it to 127.0.0.1 and put HTTPS and a password, or a VPN, in front
  4. Limiter and Valkey matter once you share the instance, not for a household behind a password

What a SearXNG instance needs from a server

A SearXNG instance needs a Linux machine that can run Docker or Podman and reach the internet, and very little else. It keeps no index of the web: every search is relayed to the engines you enable, and the answers are merged into one page. The project's documentation publishes no hardware minimum, so the honest way to size it is to watch what your own use costs.

PieceWhat it doesWhat makes it grow
searxng-coreThe web app: takes your query, asks the engines, renders resultsHow many searches arrive at once; the image proxy, which the docs say uses memory
searxng-valkeySmall key-value store the limiter keeps its counters inOnly matters once the limiter is on and many visitors arrive
Reverse proxyHTTPS and a password in front of the appBarely noticeable for one household

Start small and run docker stats during a normal day of searching. If memory is tight, move up a size; the containers and their volumes come with you.

Why your own server rather than a public instance

The project's own advice is to use an instance run by people you trust, and the one operator you can fully vouch for is you. On a public instance you cannot tell whether queries are logged, and the docs warn that busy, unprotected instances attract abuse that ends in CAPTCHAs, bans and thinner results. Your own instance keeps the settings, the logging choices and the list of engines in your hands, and you can make your preferences the instance's defaults, so clearing browser cookies does not wipe them.

A Cloud VPS fits this job well. It has its own IPv4 address and an IPv6 /96, root access, and a browser console for the day SSH will not answer. It is built on its own once the first payment clears, usually within a couple of minutes, and you can choose the Docker app when you order, which gives you Docker and Docker Compose ready to use over SSH. Traffic the machine receives, which is most of what the engines send back, is free; only what it sends counts toward the size's monthly allowance, and a search engine for a few people sends little.

Up and running in one sitting

1. Get the machine. Order a Cloud VPS with the Docker app, or install Docker yourself from Docker's own instructions, and log in as root over SSH.

2. Fetch the official files. This downloads the project's Compose file and environment template into a new searxng folder. The commands are chained, so nothing runs if a step before it fails:

mkdir -p ./searxng/core-config/ && cd ./searxng/ && \
curl -fsSL \
    -O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
    -O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example && \
cp -i .env.example .env

3. Keep the port on the server. Edit .env so the published port listens only on 127.0.0.1. Without a host address, Compose publishes 8080 on every address the machine has, and Docker's documentation notes that published ports skip a ufw firewall entirely.

# searxng/.env
SEARXNG_HOST=127.0.0.1
SEARXNG_PORT=8080
SEARXNG_BASE_URL=https://search.example.com/

4. Start it. Run docker compose up -d, then docker compose ps: you should see searxng-core on 127.0.0.1:8080 and searxng-valkey beside it. If the app keeps restarting, docker compose logs -f core shows why.

5. Put HTTPS and a password in front. Run a reverse proxy such as nginx or Caddy on the host, serving HTTPS for your name and forwarding to 127.0.0.1:8080, and protect it with a password before you share the address. Pass the X-Forwarded-For and X-Real-IP headers, as the project's nginx example does.

6. Search. Open your address, try a query, and set your preferences.

If you add a ufw firewall, allow SSH before you enable it, and make sure its rules cover IPv6 as well as IPv4, since the machine has addresses in both. Rather not expose a web page at all? Keep the proxy off the public interface and reach the instance over a private VPN such as self-hosted NetBird.

The settings that actually matter

On its first start the container copies a template to core-config/settings.yml, replaces the placeholder ultrasecretkey with a random value, and turns the image proxy on. Everything else comes from the project defaults, because the file begins with use_default_settings: true. Change only what you need:

  • secret_key: used for cryptography. Leave the generated one alone. If you ever write settings.yml by hand, set a long random value or the SEARXNG_SECRET variable: SearXNG will not start with the placeholder.
  • base_url: the public address, so links point to the right place. SEARXNG_BASE_URL in .env overrides it.
  • image_proxy: thumbnails are fetched by your server instead of your browser. The docs note it costs memory, and every image it relays is traffic your server sends.
  • method: POST keeps searches out of your browser history, at the cost of a back button that behaves oddly. The default is GET.
  • formats: only html is allowed by default. Add json under search: if a script or another tool of yours will query the instance.

The limiter and Valkey go together. The limiter is SearXNG's bot protection and per-address rate limit, and it needs a Valkey database to keep its counts. Its job is to stop bot-like traffic before the engines start answering your server with CAPTCHAs or refusals. For a household behind a password, leave it off. The moment you share the instance more widely, turn it on along with the public-instance features:

# core-config/settings.yml: add the two server lines to the server block
# that is already there, and leave its secret_key exactly as it is
server:
  limiter: true
  public_instance: true

valkey:
  url: valkey://valkey:6379/0

The host name valkey is the Compose service name, as the migration notes in the docs say. Apply the change with docker compose restart core. Behind a proxy, the limiter reads the visitor's real address from the forwarded headers only when the request arrives from an address in trusted_proxies, set in core-config/limiter.toml. Find the address your proxy reaches the container from and list it there, or every visitor looks like the same one. If you want to run Valkey for other jobs too, our Valkey server guide covers it on its own.

Keeping it healthy

  • Updates: from the searxng folder run docker compose down, docker compose pull, then docker compose up -d. When you refresh the Compose file and .env.example, read them for changes before you start again, as the docs ask. Set SEARXNG_VERSION in .env to a dated tag if you want to choose when versions change.
  • Backups: what you cannot recreate is small: the .env file and the core-config folder with settings.yml and any limiter.toml. The cache volume holds things like the favicon cache, which rebuilds itself.
  • Logs: with GET, every query sits in the address your proxy logs. If you want no trail, turn the proxy's access log off for this site, as the project's nginx notes show, or switch to POST.
  • Engines that stop answering: if one starts refusing your server, turn it off in your preferences or mark it disabled: true in settings.yml, and lean on the others.

For the proxy and certificate part in more depth, see Docker Compose behind HTTPS.

Where this setup stops being the right one

A private instance hides your home connection and your browser from the engines. It does not make you anonymous: every search leaves from one server address that only you use, and the docs mention a proxy or Tor for routing outgoing requests if that matters to you.

A Cloud VPS shares its physical server with other customers, and processor time is shared. If you plan to open SearXNG to a community with heavy traffic, a whole dedicated server gives you every core and an unmetered port, so nobody counts what it sends. If it will be one container among many on bare metal, see running Kubernetes yourself.

Questions people ask

Will my searches be anonymous once I run my own instance?
Not fully. The engines see your server's address instead of yours, and they get no cookies from your browser. But all your searches come from one address used only by you, so the instance protects your home connection rather than your identity. The docs describe routing outgoing requests through a proxy or Tor for more.
How big a server does SearXNG need?
The project publishes no minimum. It indexes nothing itself, so the load comes from how many searches arrive at once and whether the image proxy is on. Start on a small Cloud VPS, watch docker stats, and move up a size if memory runs short: the machine restarts once and keeps its files and addresses. Sizes cannot shrink later.
Do I need the limiter on a personal instance?
Not if it sits behind a password or a VPN. The limiter exists to stop bots from making the engines block your server, and it needs Valkey to work. Once anyone outside your household can reach it, turn on limiter and public_instance and point valkey: url at the Valkey container.
Why does SearXNG refuse to start after I wrote my own settings file?
The most common reason is the secret key. If secret_key is still the placeholder ultrasecretkey, SearXNG exits on purpose. Put a long random value there, or set SEARXNG_SECRET in .env and recreate the container with docker compose up -d --force-recreate.
Can my scripts or other apps query it?
Yes, once you allow it. By default only the html format is served. Add json to formats under search: in settings.yml, restart the core container, and request results with format=json. Keep the instance behind your password if you do, so the endpoint is yours alone.

Get a server for your private search

Pick a Cloud VPS with the Docker app, and your SearXNG instance can be answering searches the same evening.

Choose your Cloud VPS

Read next