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.
| Piece | What it does | What makes it grow |
|---|---|---|
| searxng-core | The web app: takes your query, asks the engines, renders results | How many searches arrive at once; the image proxy, which the docs say uses memory |
| searxng-valkey | Small key-value store the limiter keeps its counters in | Only matters once the limiter is on and many visitors arrive |
| Reverse proxy | HTTPS and a password in front of the app | Barely 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.ymlby hand, set a long random value or theSEARXNG_SECRETvariable: SearXNG will not start with the placeholder. - base_url: the public address, so links point to the right place.
SEARXNG_BASE_URLin.envoverrides 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:
POSTkeeps searches out of your browser history, at the cost of a back button that behaves oddly. The default isGET. - formats: only
htmlis allowed by default. Addjsonundersearch: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
searxngfolder rundocker compose down,docker compose pull, thendocker compose up -d. When you refresh the Compose file and.env.example, read them for changes before you start again, as the docs ask. SetSEARXNG_VERSIONin.envto a dated tag if you want to choose when versions change. - Backups: what you cannot recreate is small: the
.envfile and thecore-configfolder withsettings.ymland anylimiter.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 toPOST. - Engines that stop answering: if one starts refusing your server, turn it off in your preferences or mark it
disabled: trueinsettings.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
limiterandpublic_instanceand pointvalkey: urlat 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_keyis still the placeholderultrasecretkey, SearXNG exits on purpose. Put a long random value there, or setSEARXNG_SECRETin.envand recreate the container withdocker 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
jsontoformatsundersearch:insettings.yml, restart the core container, and request results withformat=json. Keep the instance behind your password if you do, so the endpoint is yours alone.