DEV Community

konsongong
konsongong

Posted on Originally published at vpsfolio.pages.dev

SearXNG Docker: Self-Host a Private Metasearch Engine

This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.

What SearXNG does and what it needs

SearXNG is a metasearch engine that aggregates results from multiple search services without tracking or profiling users. It queries upstream engines on your behalf, strips identifying headers, and returns a unified result page. You can run it as a private instance for yourself, a team, or a small community.

The stack is lightweight: a Python web application (the searxng/searxng image) and Redis for caching and rate limiting. No external database is required. The project does not publish a minimum RAM figure; memory use scales with concurrent queries and the number of enabled engines. An idle instance is modest, while heavy use with many engines and large result pages will consume more.

SearXNG listens on port 8080 inside the container. You will expose it on the host via a reverse proxy for HTTPS.

Prerequisites, ports, and volume constraints

  • A Linux VPS or local machine with Docker Engine 20.10+ and Docker Compose v2.
  • A domain name pointing to your server (for HTTPS). For local testing, you can use localhost.
  • Port 8080 will be bound to 127.0.0.1 on the host. Your reverse proxy will listen on 80/443.
  • A persistent volume for SearXNG configuration and cache. The official image expects /etc/searxng to contain settings.yml and a secret key. We'll mount a named volume there and generate the config on first run.
  • Redis data is ephemeral; a named volume is optional but useful for persistence across restarts.

No host directories need to be mounted; everything lives in Docker volumes.

Production Docker Compose setup

Create a project directory and generate a .env file with strong secrets:

mkdir -p ~/searxng && cd ~/searxng
cat <<'EOF' > .env
# Generate with: openssl rand -hex 32
SEARXNG_SECRET=
# Optional: set to your domain for correct links
SEARXNG_BASE_URL=https://search.example.com/
# Timezone
TZ=UTC
EOF
# Fill in the secret
sed -i "s/^SEARXNG_SECRET=.*/SEARXNG_SECRET=$(openssl rand -hex 32)/" .env
Enter fullscreen mode Exit fullscreen mode

Now write the compose.yml:

services:
  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - searxng-config:/etc/searxng
    environment:
      - SEARXNG_SECRET=${SEARXNG_SECRET}
      - SEARXNG_BASE_URL=${SEARXNG_BASE_URL:-http://localhost:8080/}
      - TZ=${TZ:-UTC}
    depends_on:
      - redis
    networks:
      - searxng-net

  redis:
    image: redis:7-alpine
    container_name: searxng-redis
    restart: unless-stopped
    command: redis-server --save 60 1 --loglevel warning
    volumes:
      - redis-data:/data
    networks:
      - searxng-net

volumes:
  searxng-config:
  redis-data:

networks:
  searxng-net:
    driver: bridge
Enter fullscreen mode Exit fullscreen mode

Start the stack:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

On first start, the container will generate a default settings.yml in the searxng-config volume. You can edit it later by exec'ing into the container or using a bind mount if you prefer. For production, you should customize settings.yml to enable/disable engines, set a proper server.secret_key, and configure server.limiter and server.public_instance as needed.

Reverse proxy, HTTPS, and first-run hardening

SearXNG should not be exposed directly to the internet without HTTPS. Use Caddy or Nginx as a reverse proxy on the same host. Below is a Caddyfile example (Caddy handles TLS automatically):

search.example.com {
    reverse_proxy 127.0.0.1:8080
}
Enter fullscreen mode Exit fullscreen mode

For Nginx, ensure you pass the correct headers:

server {
    listen 443 ssl http2;
    server_name search.example.com;

    ssl_certificate /etc/letsencrypt/live/search.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/search.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
Enter fullscreen mode Exit fullscreen mode

SearXNG does not require WebSocket support. However, if you enable the limiter or use features that rely on client IP, ensure X-Forwarded-For and X-Forwarded-Proto are set correctly so SearXNG sees the real client IP and protocol. Set SEARXNG_BASE_URL to your public HTTPS URL to generate correct links.

First-run hardening:

  • The default settings.yml may allow public access. To restrict to your own use, set server.public_instance: false and configure server.limiter: true with a Redis URL (e.g., redis://redis:6379/0).
  • Change the default secret key in settings.yml (the SEARXNG_SECRET env var overrides it if set).
  • Consider enabling server.image_proxy: true to proxy images and avoid leaking your users' IPs to third-party sites.

Updating, backups, and common pitfalls

Update the stack regularly to get new features and security fixes:

cd ~/searxng
docker compose pull
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Backup the configuration volume (contains settings.yml and any customizations):

docker run --rm -v searxng-config:/data -v $(pwd):/backup alpine tar czf /backup/searxng-config-$(date +%F).tar.gz -C /data .
Enter fullscreen mode Exit fullscreen mode

Redis data is cache and can be lost; back it up only if you rely on persistent rate-limit counters:

docker run --rm -v redis-data:/data -v $(pwd):/backup alpine tar czf /backup/redis-data-$(date +%F).tar.gz -C /data .
Enter fullscreen mode Exit fullscreen mode

Common pitfalls:

  1. Limiter and Redis: If you enable the limiter without configuring Redis, SearXNG may fail to start or block all requests. Ensure redis service is running and server.redis.url points to redis://redis:6379/0.
  2. Base URL mismatch: If SEARXNG_BASE_URL is not set to your public URL, generated links (e.g., in results or preferences) may point to localhost, breaking the experience. Always set it to your HTTPS domain.
  3. Engine blocking: Some upstream search engines may block requests from your server's IP. Use the settings.yml to disable problematic engines or configure proxies if needed.

Measured in our sandbox run: total memory 138.6 MB (sum of per-container peaks over a 30s idle window after startup) across 2 containers; largest container 130.3 MB; published port(s) 8080; HTTP probe returned 200. The run took 52.2s including the image download. Required secret(s) SEARXNG_SECRET were generated for the test run, as the tutorial instructs. Container breakdown: searxng 130.3 MB, redis 8.3 MB.


Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.


Originally published with full interactive benchmark metrics and server sizing notes at https://vpsfolio.pages.dev/searxng-docker-self-hosting/.

Top comments (0)