Skip to content
Klutch.sh Docs

Deploying a SearXNG App

Introduction

SearXNG is a privacy-respecting meta-search engine that federates queries across many providers. Deploying SearXNG with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and optional persistent storage—all configured from klutch.sh/app. This guide covers installation, Dockerfile setup, environment variables, storage, Nixpacks overrides, and sample checks.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your SearXNG Dockerfile (GitHub is the only supported git source)
  • Optional: API keys for specific search engines you want to enable

For onboarding, see the Quick Start.

Architecture and ports

  • SearXNG serves HTTP on internal port 8080 by default. Choose HTTP traffic and set the internal port to 8080.
  • Persistent storage is optional (e.g., for custom settings or rate-limit state).

Repository layout

searxng/
├── Dockerfile              # Must be at repo root for auto-detection
├── settings.yml            # Custom SearXNG configuration
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Build and run locally:

Terminal window
docker build -t searxng-local .
docker run -p 8080:8080 \
  -e SEARXNG_BASE_URL=http://localhost:8080 \
  searxng-local

Dockerfile for SearXNG (production-ready)

Place this at the repo root; Klutch.sh auto-detects Dockerfiles.

FROM searxng/searxng:latest


ENV SEARXNG_BASE_URL=http://localhost:8080


COPY settings.yml /etc/searxng/settings.yml


EXPOSE 8080
CMD ["uwsgi", "--ini", "/etc/searxng/uwsgi.ini"]

Notes:

  • Pin to a specific tag (e.g., searxng/searxng:2023.9.30) for stability.
  • If you rely on defaults, remove the COPY settings.yml line.

Environment variables (Klutch.sh)

Set these before deploying:

  • SEARXNG_BASE_URL=https://example-app.klutch.sh
  • PORT=8080
  • Optional: provider API keys (e.g., SEARXNG_GOOGLE_API_KEY, SEARXNG_GOOGLE_CX, SEARXNG_BING_API_KEY) as supported by your settings.yml

If deploying without the Dockerfile and relying on Nixpacks:

  • NIXPACKS_START_CMD=uwsgi --ini /etc/searxng/uwsgi.ini

Attach persistent volumes

If you keep custom configs or state, add storage in Klutch.sh (path and size only):

  • /etc/searxng — custom settings (if you want to override at runtime).
  • /var/lib/searxng — optional state, rate limiting, or plugins.

Ensure paths are writable inside the container if you modify them.

Deploy SearXNG on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add the environment variables above (base URL and any provider API keys).
  5. Attach volumes at /etc/searxng and/or /var/lib/searxng if you manage configs/state at runtime.
  6. Deploy. Your instance will be reachable at https://example-app.klutch.sh.

Sample checks

Landing page:

Terminal window
curl -I https://example-app.klutch.sh

Search query:

Terminal window
curl "https://example-app.klutch.sh/search?q=klutch.sh"

Health checks and production tips

  • Add an HTTP readiness probe to / or /health if you expose one.
  • Keep provider API keys in Klutch.sh secrets; rotate regularly.
  • Pin image versions and test config changes in staging before production.
  • If using local volumes, monitor usage and resize proactively.

SearXNG on Klutch.sh delivers reproducible Docker builds, managed secrets, and optional config storage—without extra YAML or CI steps. Configure ports, env vars, and any provider keys, then launch your privacy-first meta-search engine.