Minor updates for Zee. Removed Molodetz specifics.

Closes: https://github.com/searxng/searxng/issues/4272
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

.coveragerc

@@ -1,15 +1,6 @@
 [run]
 branch = True
-source =
-  searx/engines
-  searx/__init__.py
-  searx/autocomplete.py
-  searx/https_rewrite.py
-  searx/languages.py
-  searx/search.py
-  searx/testing.py
-  searx/utils.py
-  searx/webapp.py
+source = searx
 
 [report]
 show_missing = True

.devcontainer/Dockerfile

@@ -0,0 +1,4 @@
+FROM mcr.microsoft.com/devcontainers/base:debian
+
+RUN apt-get update && \
+    apt-get -y install python3 python3-venv redis firefox-esr graphviz imagemagick librsvg2-bin fonts-dejavu shellcheck

.devcontainer/devcontainer.json

@@ -0,0 +1,31 @@
+{
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/github-cli": {}
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-azuretools.vscode-docker"
+      ],
+      "remote.otherPortsAttributes": {
+        "protocol": "https"
+      },
+      "settings": {
+        "files.autoSave": "off",
+        "python.defaultInterpreterPath": "/workspaces/searxng/local/py3/bin/python3",
+        "python.formatting.blackPath": "/workspaces/searxng/local/py3/bin/black",
+        "python.linting.pylintPath": "/workspaces/searxng/local/py3/bin/pylint"
+      }
+    }
+  },
+  "forwardPorts": [8000, 8888],
+  "portsAttributes": {
+    "8000": {"label": "Sphinx documentation"},
+    "8888": {"label": "SearXNG"}
+  },
+  "postCreateCommand": "git pull && make install"
+}

.dir-locals-template.el

@@ -0,0 +1,163 @@
+;;; .dir-locals.el
+;;
+;; Per-Directory Local Variables:
+;;   https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html
+;;
+;; For full fledge developer tools install emacs packages:
+;;
+;;    M-x package-install ...
+;;
+;;     magit gitconfig
+;;     nvm lsp-mode lsp-pyright lsp-eslint
+;;     pyvenv pylint pip-requirements
+;;     jinja2-mode
+;;     json-mode
+;;     company company-jedi company-quickhelp company-shell
+;;     realgud
+;;     sphinx-doc markdown-mode graphviz-dot-mode
+;;     apache-mode nginx-mode
+;;
+;; To setup a developer environment, build target::
+;;
+;;     $ make node.env.dev pyenv.install
+;;
+;; Some buffer locals are referencing the project environment:
+;;
+;; - prj-root                                --> <repo>/
+;; - nvm-dir                                 --> <repo>/.nvm
+;; - python-environment-directory            --> <repo>/local
+;; - python-environment-default-root-name    --> py3
+;; - python-shell-virtualenv-root            --> <repo>/local/py3
+;;       When this variable is set with the path of the virtualenv to use,
+;;      `process-environment' and `exec-path' get proper values in order to run
+;;      shells inside the specified virtualenv, example::
+;;         (setq python-shell-virtualenv-root "/path/to/env/")
+;; - python-shell-interpreter                --> <repo>/local/py3/bin/python
+;;
+;; Python development:
+;;
+;; Jedi, flycheck & other python stuff should use the 'python-shell-interpreter'
+;; from the local py3 environment.
+;;
+
+((nil
+  . ((fill-column . 80)
+     (indent-tabs-mode . nil)
+     (eval . (progn
+
+               (add-to-list 'auto-mode-alist '("\\.html\\'" . jinja2-mode))
+
+               ;; project root folder is where the `.dir-locals.el' is located
+               (setq-local prj-root
+                           (locate-dominating-file  default-directory ".dir-locals.el"))
+
+               (setq-local python-environment-directory
+                           (expand-file-name "./local" prj-root))
+
+               ;; to get in use of NVM environment, install https://github.com/rejeep/nvm.el
+               (setq-local nvm-dir (expand-file-name "./.nvm" prj-root))
+
+               ;; use nodejs from the (local) NVM environment (see nvm-dir)
+               (nvm-use-for-buffer)
+               (ignore-errors (require 'lsp))
+               (setq-local lsp-server-install-dir (car (cdr nvm-current-version)))
+               (setq-local lsp-enable-file-watchers nil)
+
+               ;; use 'py3' environment as default
+               (setq-local python-environment-default-root-name
+                           "py3")
+
+               (setq-local python-shell-virtualenv-root
+                           (expand-file-name
+                            python-environment-default-root-name python-environment-directory))
+
+               (setq-local python-shell-interpreter
+                           (expand-file-name
+                            "bin/python" python-shell-virtualenv-root))))))
+ (makefile-gmake-mode
+  . ((indent-tabs-mode . t)))
+
+ (yaml-mode
+  . ((eval . (progn
+
+               ;; flycheck should use the local py3 environment
+               (setq-local flycheck-yaml-yamllint-executable
+                           (expand-file-name "bin/yamllint" python-shell-virtualenv-root))
+
+               (setq-local flycheck-yamllintrc
+                           (expand-file-name  ".yamllint.yml" prj-root))
+
+               (flycheck-checker . yaml-yamllint)))))
+
+ (json-mode
+  . ((eval . (progn
+               (setq-local js-indent-level 4)
+               (flycheck-checker . json-python-json)))))
+
+ (js-mode
+  . ((eval . (progn
+               (ignore-errors (require 'lsp-eslint))
+               (setq-local js-indent-level 2)
+               ;; flycheck should use the eslint checker from developer tools
+               (setq-local flycheck-javascript-eslint-executable
+                           (expand-file-name "node_modules/.bin/eslint" prj-root))
+               ;; (flycheck-mode)
+
+               (if (featurep 'lsp-eslint)
+                   (lsp))
+               ))))
+
+ (python-mode
+  . ((eval . (progn
+               (ignore-errors (require 'jedi-core))
+               (ignore-errors (require 'lsp-pyright))
+               (ignore-errors (sphinx-doc-mode))
+               (setq-local python-environment-virtualenv
+                           (list (expand-file-name "bin/virtualenv" python-shell-virtualenv-root)
+                                 ;;"--system-site-packages"
+                                 "--quiet"))
+
+               (setq-local pylint-command
+                           (expand-file-name "bin/pylint" python-shell-virtualenv-root))
+
+               (if (featurep 'lsp-pyright)
+                   (lsp))
+
+               ;; pylint will find the '.pylintrc' file next to the CWD
+               ;;   https://pylint.readthedocs.io/en/latest/user_guide/run.html#command-line-options
+               (setq-local flycheck-pylintrc
+                           ".pylintrc")
+
+               ;; flycheck & other python stuff should use the local py3 environment
+               (setq-local flycheck-python-pylint-executable
+                           python-shell-interpreter)
+
+               ;; use 'M-x jedi:show-setup-info' and 'M-x epc:controller' to inspect jedi server
+               ;; https://tkf.github.io/emacs-jedi/latest/#jedi:environment-root -- You
+               ;; can specify a full path instead of a name (relative path). In that case,
+               ;; python-environment-directory is ignored and Python virtual environment
+               ;; is created at the specified path.
+               (setq-local jedi:environment-root
+                           python-shell-virtualenv-root)
+
+               ;; https://tkf.github.io/emacs-jedi/latest/#jedi:server-command
+               (setq-local jedi:server-command
+                           (list python-shell-interpreter
+                                 jedi:server-script))
+
+               ;; jedi:environment-virtualenv --> see above 'python-environment-virtualenv'
+               ;; is set buffer local!  No need to setup jedi:environment-virtualenv:
+               ;;
+               ;;    Virtualenv command to use.  A list of string.  If it is nil,
+               ;;    python-environment-virtualenv is used instead.  You must set non-nil
+               ;;    value to jedi:environment-root in order to make this setting work.
+               ;;
+               ;;    https://tkf.github.io/emacs-jedi/latest/#jedi:environment-virtualenv
+               ;;
+               ;; (setq-local jedi:environment-virtualenv
+               ;;             (list (expand-file-name "bin/virtualenv" python-shell-virtualenv-root)
+               ;;                   "--python"
+               ;;                   "/usr/bin/python3.4"
+               ;;                   ))
+               ))))
+ )

.dockerignore

@@ -0,0 +1,44 @@
+*~
+*/*~
+*/*/*~
+*/*/*/*~
+*/*/*/*/*~
+
+# Git
+.git
+.gitignore
+
+# CI
+.codeclimate.yml
+.travis.yml
+.taskcluster.yml
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*/__pycache__/
+*/*/__pycache__/
+*/*/*/__pycache__/
+*.py[cod]
+*/*.py[cod]
+*/*/*.py[cod]
+*/*/*/*.py[cod]
+
+# node_modules
+node_modules/
+*/node_modules/
+*/*/node_modules/
+*/*/*/node_modules/
+*/*/*/*/node_modules/
+
+.tx/
+
+# to sync with .gitignore
+geckodriver.log
+.coverage
+coverage/
+cache/
+build/
+dist/
+local/
+gh-pages/
+*.egg-info/

.editorconfig

@@ -0,0 +1,43 @@
+# https://editorconfig.org/
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+end_of_line = lf
+charset = utf-8
+
+[*.py]
+max_line_length = 119
+
+[*.html]
+indent_size = 4
+
+[*.js]
+indent_size = 2
+
+[*.json]
+indent_size = 4
+insert_final_newline = ignore
+
+# Minified JavaScript files shouldn't be changed
+[**.min.js]
+indent_style = ignore
+insert_final_newline = ignore
+
+# Makefiles always use tabs for indentation
+[Makefile]
+indent_style = tab
+
+# Batch files use tabs for indentation
+[*.bat]
+indent_style = tab
+
+[docs/**.rst]
+max_line_length = 79
+
+[*.yml]
+indent_size = 2

.gitattributes

@@ -0,0 +1,12 @@
+*.gif -diff
+*.png -diff
+*.min.css -diff
+*.min.js -diff
+*.css.map -diff
+*.js.map -diff
+*.eot -diff
+*.svg -diff
+*.ttf -diff
+*.woff -diff
+*.woff2 -diff
+messages.mo -diff

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,39 @@
+---
+name: Bug report
+about: Report a bug in SearXNG
+title: ''
+labels: bug
+assignees: ''
+
+---
+<!-- PLEASE FILL THESE FIELDS, IT REALLY HELPS THE MAINTAINERS OF SearXNG -->
+
+**Version of SearXNG, commit number if you are using on master branch and stipulate if you forked SearXNG**
+<!-- If you are running on master branch using git execute this command
+in order to fetch the latest commit ID:
+```
+git log -1
+``` 
+If you are using searxng-docker then look at the bottom of the SearXNG page
+and check for the version after "Powered by SearXNG"
+
+Please also stipulate if you are using a forked version of SearXNG and
+include a link to the fork source code.
+-->
+**How did you install SearXNG?**
+<!-- Did you install SearXNG using the official wiki or using searxng-docker
+or manually by executing the searx/webapp.py file? -->
+**What happened?**
+<!-- A clear and concise description of what the bug is. -->
+
+**How To Reproduce**
+<!-- How can we reproduce this issue? (as minimally and as precisely as possible) -->
+
+**Expected behavior**
+<!-- A clear and concise description of what you expected to happen. -->
+
+**Screenshots & Logs**
+<!-- If applicable, add screenshots, logs to help explain your problem. -->
+
+**Additional context**
+<!-- Add any other context about the problem here. -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Questions & Answers (Q&A)
+    url: https://github.com/searxng/searxng/discussions/categories/q-a
+    about: Ask questions and find answers

.github/ISSUE_TEMPLATE/engine-request.md

@@ -0,0 +1,31 @@
+---
+name: Engine request
+about: Request a new engine in SearXNG
+title: ''
+labels: enhancement, engine request
+assignees: ''
+
+---
+<!-- PLEASE FILL THESE FIELDS, IT REALLY HELPS THE MAINTAINERS OF SearXNG -->
+
+**Working URL to the engine**
+<!-- Please check if the engine is responding correctly before submitting it. -->
+
+**Why do you want to add this engine?**
+<!-- What's special about this engine? Is it open source or libre? -->
+
+**Features of this engine**
+<!-- Features of this engine: Doesn't track its users, fast, easy to integrate, ... -->
+
+**How can SearXNG fetch the information from this engine?**
+<!-- List API URL, example code (using the correct markdown) and more
+that could be useful for the developers in order to implement this engine.
+If you don't know what to write, let this part blank. -->
+
+**Applicable category of this engine**
+<!-- Where should this new engine fit in SearXNG? Current categories in SearXNG:
+general, files, images, it, map, music, news, science, social media and videos.
+You can add multiple categories at the same time. -->
+
+**Additional context**
+<!-- Add any other context about this engine here. -->

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Request a new feature in SearXNG
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+<!-- PLEASE FILL THESE FIELDS, IT REALLY HELPS THE MAINTAINERS OF SearXNG -->
+
+**Is your feature request related to a problem? Please describe.**
+<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->
+
+**Describe the solution you'd like**
+<!-- A clear and concise description of what you want to happen. -->
+
+**Describe alternatives you've considered**
+<!-- A clear and concise description of any alternative solutions or features you've considered. -->
+
+**Additional context**
+<!-- Add any other context or screenshots about the feature request here. -->

.github/dependabot.yml

@@ -0,0 +1,22 @@
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "friday"
+    open-pull-requests-limit: 5
+    target-branch: "master"
+    commit-message:
+      prefix: "[upd] pypi:"
+
+  - package-ecosystem: "npm"
+    directory: "/searx/static/themes/simple"
+    schedule:
+      interval: "weekly"
+      day: "friday"
+    open-pull-requests-limit: 5
+    target-branch: "master"
+    commit-message:
+      prefix: "[upd] npm:"

.github/workflows/checker.yml

@@ -0,0 +1,31 @@
+name: "Checker"
+on:  # yamllint disable-line rule:truthy
+  schedule:
+    - cron: "0 4 * * 5"
+  workflow_dispatch:
+
+jobs:
+  checker:
+    name: Checker
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Ubuntu packages
+        run: |
+          sudo ./utils/searxng.sh install packages
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+          architecture: 'x64'
+
+      - name: Install Python dependencies
+        run: |
+          make V=1 install
+
+      - name: Checker
+        run: |
+          make search.checker

.github/workflows/data-update.yml

@@ -0,0 +1,67 @@
+name: "Update searx.data"
+on:  # yamllint disable-line rule:truthy
+  schedule:
+    - cron: "59 23 28 * *"
+  workflow_dispatch:
+
+jobs:
+  updateData:
+    name: Update data - ${{ matrix.fetch }}
+    runs-on: ubuntu-24.04
+    if: ${{ github.repository_owner == 'searxng'}}
+    strategy:
+      fail-fast: false
+      matrix:
+        fetch:
+          - update_ahmia_blacklist.py
+          - update_currencies.py
+          - update_external_bangs.py
+          - update_firefox_version.py
+          - update_engine_traits.py
+          - update_wikidata_units.py
+          - update_engine_descriptions.py
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Ubuntu packages
+        run: |
+          sudo ./utils/searxng.sh install packages
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          architecture: 'x64'
+
+      - name: Install Python dependencies
+        run: |
+          make V=1 install
+
+      - name: Fetch data
+        env:
+          FETCH_SCRIPT: ./searxng_extra/update/${{ matrix.fetch }}
+        run: |
+          V=1 ./manage pyenv.cmd python "$FETCH_SCRIPT"
+
+      - name: Create Pull Request
+        id: cpr
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: '[data] update searx.data - ${{ matrix.fetch }}'
+          committer: searxng-bot <noreply@github.com>
+          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
+          signoff: false
+          branch: update_data_${{ matrix.fetch }}
+          delete-branch: true
+          draft: false
+          title: '[data] update searx.data - ${{ matrix.fetch }}'
+          body: |
+            update searx.data - ${{ matrix.fetch }}
+          labels: |
+            data
+
+      - name: Check outputs
+        run: |
+          echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
+          echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}"

.github/workflows/integration.yml

@@ -0,0 +1,190 @@
+name: Integration
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        os: [ubuntu-24.04]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Ubuntu packages
+        run: |
+          sudo ./utils/searxng.sh install packages
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          architecture: 'x64'
+      - name: Run tests
+        run: make V=1 ci.test
+
+  themes:
+    name: Themes
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Ubuntu packages
+        run: sudo ./utils/searxng.sh install buildhost
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          architecture: 'x64'
+      - name: Cache Python dependencies
+        id: cache-python
+        uses: actions/cache@v4
+        with:
+          path: |
+            ./local
+            ./.nvm
+            ./node_modules
+          key: python-ubuntu-24.04-3.12-${{ hashFiles('requirements*.txt', 'setup.py','.nvmrc', 'package.json') }}
+      - name: Install node dependencies
+        run: make V=1 node.env
+      - name: Build themes
+        run: make V=1 themes.all
+
+  documentation:
+    name: Documentation
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write  # for JamesIves/github-pages-deploy-action to push changes in repo
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: '0'
+          persist-credentials: false
+      - name: Install Ubuntu packages
+        run: sudo ./utils/searxng.sh install buildhost
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          architecture: 'x64'
+      - name: Cache Python dependencies
+        id: cache-python
+        uses: actions/cache@v4
+        with:
+          path: |
+            ./local
+            ./.nvm
+            ./node_modules
+          key: python-ubuntu-24.04-3.12-${{ hashFiles('requirements*.txt', 'setup.py','.nvmrc', 'package.json') }}
+      - name: Build documentation
+        run: |
+          make V=1 docs.clean docs.html
+      - name: Deploy
+        if: github.ref == 'refs/heads/master'
+        uses: JamesIves/github-pages-deploy-action@3.7.1
+        with:
+          GITHUB_TOKEN: ${{ github.token }}
+          BRANCH: gh-pages
+          FOLDER: dist/docs
+          CLEAN: true  # Automatically remove deleted files from the deploy branch
+          SINGLE_COMMIT: true
+          COMMIT_MESSAGE: '[doc] build from commit ${{ github.sha }}'
+
+  babel:
+    name: Update translations branch
+    runs-on: ubuntu-24.04
+    if: ${{ github.repository_owner == 'searxng' && github.ref == 'refs/heads/master' }}
+    needs:
+      - python
+      - themes
+      - documentation
+    permissions:
+      contents: write  # for make V=1 weblate.push.translations
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: '0'
+          token: ${{ secrets.WEBLATE_GITHUB_TOKEN }}
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          architecture: 'x64'
+      - name: Cache Python dependencies
+        id: cache-python
+        uses: actions/cache@v4
+        with:
+          path: |
+            ./local
+            ./.nvm
+            ./node_modules
+          key: python-ubuntu-20.04-3.12-${{ hashFiles('requirements*.txt', 'setup.py','.nvmrc', 'package.json') }}
+      - name: weblate & git setup
+        env:
+          WEBLATE_CONFIG: ${{ secrets.WEBLATE_CONFIG }}
+        run: |
+          mkdir -p ~/.config
+          echo "${WEBLATE_CONFIG}" > ~/.config/weblate
+          git config --global user.email "searxng-bot@users.noreply.github.com"
+          git config --global user.name "searxng-bot"
+      - name: Update transations
+        id: update
+        run: |
+          make V=1 weblate.push.translations
+
+  dockers:
+    name: Docker
+    if: github.ref == 'refs/heads/master'
+    needs:
+      - python
+      - themes
+      - documentation
+    env:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        if: env.DOCKERHUB_USERNAME != null
+        uses: actions/checkout@v4
+        with:
+          # make sure "make docker.push" can get the git history
+          fetch-depth: '0'
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          architecture: 'x64'
+      - name: Cache Python dependencies
+        id: cache-python
+        uses: actions/cache@v4
+        with:
+          path: |
+            ./local
+            ./.nvm
+            ./node_modules
+          key: python-ubuntu-20.04-3.12-${{ hashFiles('requirements*.txt', 'setup.py','.nvmrc', 'package.json') }}
+      - name: Set up QEMU
+        if: env.DOCKERHUB_USERNAME != null
+        uses: docker/setup-qemu-action@v1
+      - name: Set up Docker Buildx
+        if: env.DOCKERHUB_USERNAME != null
+        uses: docker/setup-buildx-action@v1
+      - name: Login to DockerHub
+        if: env.DOCKERHUB_USERNAME != null
+        uses: docker/login-action@v1
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Build and push
+        if: env.DOCKERHUB_USERNAME != null
+        run: make -e GIT_URL=$(git remote get-url origin) docker.buildx

.github/workflows/security.yml

@@ -0,0 +1,28 @@
+name: "Security checks"
+on:  # yamllint disable-line rule:truthy
+  schedule:
+    - cron: "42 05 * * *"
+  workflow_dispatch:
+
+jobs:
+  dockers:
+    name: Trivy ${{ matrix.image }}
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@master
+        with:
+          image-ref: 'searxng/searxng:latest'
+          ignore-unfixed: false
+          vuln-type: 'os,library'
+          severity: 'UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL'
+          format: 'sarif'
+          output: 'trivy-results.sarif'
+
+      - name: Upload Trivy scan results to GitHub Security tab
+        uses: github/codeql-action/upload-sarif@v2
+        with:
+          sarif_file: 'trivy-results.sarif'

.github/workflows/translations-update.yml

@@ -0,0 +1,59 @@
+name: "Update translations"
+on:  # yamllint disable-line rule:truthy
+  schedule:
+    - cron: "05 07 * * 5"
+  workflow_dispatch:
+
+jobs:
+  babel:
+    name: "create PR for additions from weblate"
+    runs-on: ubuntu-24.04
+    if: ${{ github.repository_owner == 'searxng' && github.ref == 'refs/heads/master' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: '0'
+          token: ${{ secrets.WEBLATE_GITHUB_TOKEN }}
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          architecture: 'x64'
+      - name: Cache Python dependencies
+        id: cache-python
+        uses: actions/cache@v4
+        with:
+          path: |
+            ./local
+            ./.nvm
+            ./node_modules
+          key: python-ubuntu-24.04-3.12-${{ hashFiles('requirements*.txt', 'setup.py','.nvmrc', 'package.json') }}
+      - name: weblate & git setup
+        env:
+          WEBLATE_CONFIG: ${{ secrets.WEBLATE_CONFIG }}
+        run: |
+          mkdir -p ~/.config
+          echo "${WEBLATE_CONFIG}" > ~/.config/weblate
+          git config --global user.email "searxng-bot@users.noreply.github.com"
+          git config --global user.name "searxng-bot"
+      - name: Merge and push transation updates
+        run: |
+          make V=1 weblate.translations.commit
+      - name: Create Pull Request
+        id: cpr
+        uses: peter-evans/create-pull-request@v3
+        with:
+          token: ${{ secrets.WEBLATE_GITHUB_TOKEN }}
+          commit-message: '[l10n] update translations from Weblate'
+          committer: searxng-bot <searxng-bot@users.noreply.github.com>
+          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
+          signoff: false
+          branch: translations_update
+          delete-branch: true
+          draft: false
+          title: '[l10n] update translations from Weblate'
+          body: |
+            update translations from Weblate
+          labels: |
+            translation

.gitignore

@@ -1,25 +1,28 @@
-.coverage
-.installed.cfg
-engines.cfg
-env
-robot_log.html
-robot_output.xml
-robot_report.html
-setup.cfg
+# to sync with .dockerignore & pyrightconfig.json
 
 *.pyc
 */*.pyc
 *~
+*.swp
+geckodriver.log
 
-bin/
-build/
+.coverage
 coverage/
-develop-eggs/
+
+.nvm/
+cache/
+build/
 dist/
-eggs/
-include/
-lib/
 local/
-parts/
-searx.egg-info/
-var/
+gh-pages/
+*.egg-info/
+
+/package-lock.json
+/node_modules/
+
+.idea/
+
+searx/version_frozen.py
+.dir-locals.el
+
+.python-version

.landscape.yaml

@@ -1,3 +0,0 @@
-strictness: high
-ignore-paths:
-  - bootstrap.py

.nvmrc

@@ -0,0 +1 @@
+v23.5

.pylintrc

@@ -0,0 +1,408 @@
+# -*- coding: utf-8; mode: conf-unix -*-
+# lint Python modules using external checkers.
+#
+# This is the main checker controlling the other ones and the reports
+# generation. It is itself both a raw checker and an astng checker in order
+# to:
+# * handle message activation / deactivation at the module level
+# * handle some basic but necessary stats'data (number of classes, methods...)
+#
+[MASTER]
+
+# A comma-separated list of package or module names from where C extensions may
+# be loaded. Extensions are loading into the active Python interpreter and may
+# run arbitrary code
+extension-pkg-whitelist=lxml.etree
+
+# Add files or directories to the blacklist. They should be base names, not
+# paths.
+ignore=CVS, .git, .svn
+
+# Add files or directories matching the regex patterns to the blacklist. The
+# regex matches against base names, not paths.
+ignore-patterns=
+
+# Python code to execute, usually for sys.path manipulation such as
+# pygtk.require().
+#init-hook=
+
+# Use multiple processes to speed up Pylint.
+jobs=0
+
+# List of plugins (as comma separated values of python modules names) to load,
+# usually to register additional checkers.
+load-plugins=
+
+# Pickle collected data for later comparisons.
+persistent=yes
+
+# Specify a configuration file.
+#rcfile=
+
+# Allow loading of arbitrary C extensions. Extensions are imported into the
+# active Python interpreter and may run arbitrary code.
+unsafe-load-any-extension=no
+
+
+[MESSAGES CONTROL]
+
+# Only show warnings with the listed confidence levels. Leave empty to show
+# all. Valid levels: HIGH, INFERENCE, INFERENCE_FAILURE, UNDEFINED
+confidence=
+
+# Disable the message, report, category or checker with the given id(s). You
+# can either give multiple identifiers separated by comma (,) or put this
+# option multiple times (only on the command line, not in the configuration
+# file where it should appear only once).You can also use "--disable=all" to
+# disable everything first and then reenable specific checks. For example, if
+# you want to run only the similarities checker, you can use "--disable=all
+# --enable=similarities". If you want to run only the classes checker, but have
+# no Warning level messages displayed, use"--disable=all --enable=classes
+# --disable=W"
+disable=duplicate-code,
+        missing-function-docstring,
+        consider-using-f-string,
+
+# Enable the message, report, category or checker with the given id(s). You can
+# either give multiple identifier separated by comma (,) or put this option
+# multiple time (only on the command line, not in the configuration file where
+# it should appear only once). See also the "--disable" option for examples.
+enable=
+
+
+[REPORTS]
+
+# Python expression which should return a note less than 10 (10 is the highest
+# note). You have access to the variables errors warning, statement which
+# respectively contain the number of errors / warnings messages and the total
+# number of statements analyzed. This is used by the global evaluation report
+# (RP0004).
+evaluation=10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)
+
+# Template used to display messages. This is a python new-style format string
+# used to format the message information. See doc for all details
+
+# HINT: do not set this here, use argument --msg-template=...
+#msg-template={path}:{line}: [{msg_id}({symbol}),{obj}] {msg}
+
+# Set the output format. Available formats are text, parseable, colorized, json
+# and msvs (visual studio).You can also give a reporter class, eg
+# mypackage.mymodule.MyReporterClass.
+
+# HINT: do not set this here, use argument --output-format=...
+#output-format=text
+
+# Tells whether to display a full report or only the messages
+reports=no
+
+# Activate the evaluation score.
+score=yes
+
+
+[REFACTORING]
+
+# Maximum number of nested blocks for function / method body
+max-nested-blocks=5
+
+
+[BASIC]
+
+# Regular expression matching correct argument names
+argument-rgx=(([a-z][a-zA-Z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Regular expression matching correct attribute names
+attr-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*)|([A-Z0-9_]*))$
+
+# Bad variable names which should always be refused, separated by a comma
+bad-names=foo,bar,baz,toto,tutu,tata
+
+# Regular expression matching correct class attribute names
+class-attribute-rgx=([A-Za-z_][A-Za-z0-9_]{2,30}|(__.*__))$
+
+# Regular expression matching correct class names
+class-rgx=[A-Z_][a-zA-Z0-9]+$
+
+# Regular expression matching correct constant names
+const-rgx=(([a-zA-Z_][a-zA-Z0-9_]*)|(__.*__))$
+#const-rgx=[f]?[A-Z_][a-zA-Z0-9_]{2,30}$
+
+# Minimum line length for functions/classes that require docstrings, shorter
+# ones are exempt.
+docstring-min-length=-1
+
+# Regular expression matching correct function names
+function-rgx=(([a-z][a-zA-Z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Good variable names which should always be accepted, separated by a comma
+good-names=i,j,k,ex,Run,_,log,cfg,id
+
+# Include a hint for the correct naming format with invalid-name
+include-naming-hint=no
+
+# Regular expression matching correct inline iteration names
+inlinevar-rgx=[A-Za-z_][A-Za-z0-9_]*$
+
+# Regular expression matching correct method names
+method-rgx=(([a-z][a-zA-Z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Regular expression matching correct module names
+#module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$
+module-rgx=([a-z_][a-z0-9_]*)$
+
+# Colon-delimited sets of names that determine each other's naming style when
+# the name regexes allow several styles.
+name-group=
+
+# Regular expression which should only match function or class names that do
+# not require a docstring.
+no-docstring-rgx=^_
+
+# List of decorators that produce properties, such as abc.abstractproperty. Add
+# to this list to register other decorators that produce valid properties.
+property-classes=abc.abstractproperty
+
+# Regular expression matching correct variable names
+variable-rgx=(([a-z][a-zA-Z0-9_]{2,30})|(_[a-z0-9_]*)|([a-z]))$
+
+
+[FORMAT]
+
+# Expected format of line ending, e.g. empty (any line ending), LF or CRLF.
+expected-line-ending-format=
+
+# Regexp for a line that is allowed to be longer than the limit.
+ignore-long-lines=^\s*(# )?<?https?://\S+>?$
+
+# Number of spaces of indent required inside a hanging  or continued line.
+indent-after-paren=4
+
+# String used as indentation unit. This is usually "    " (4 spaces) or "\t" (1
+# tab).
+indent-string='    '
+
+# Maximum number of characters on a single line.
+max-line-length=120
+
+# Maximum number of lines in a module
+max-module-lines=2000
+
+# Allow the body of a class to be on the same line as the declaration if body
+# contains single statement.No config file found, using default configuration
+
+single-line-class-stmt=no
+
+# Allow the body of an if to be on the same line as the test if there is no
+# else.
+single-line-if-stmt=no
+
+
+[LOGGING]
+
+# Logging modules to check that the string format arguments are in logging
+# function parameter format
+logging-modules=logging
+
+
+[MISCELLANEOUS]
+
+# List of note tags to take in consideration, separated by a comma.
+notes=FIXME,XXX,TODO
+
+
+[SIMILARITIES]
+
+# Ignore comments when computing similarities.
+ignore-comments=yes
+
+# Ignore docstrings when computing similarities.
+ignore-docstrings=yes
+
+# Ignore imports when computing similarities.
+ignore-imports=no
+
+# Minimum lines number of a similarity.
+min-similarity-lines=4
+
+
+[SPELLING]
+
+# Spelling dictionary name. Available dictionaries: none. To make it working
+# install python-enchant package.
+spelling-dict=
+
+# List of comma separated words that should not be checked.
+spelling-ignore-words=
+
+# A path to a file that contains private dictionary; one word per line.
+spelling-private-dict-file=
+
+# Tells whether to store unknown words to indicated private dictionary in
+# --spelling-private-dict-file option instead of raising a message.
+spelling-store-unknown-words=no
+
+
+[TYPECHECK]
+
+# List of decorators that produce context managers, such as
+# contextlib.contextmanager. Add to this list to register other decorators that
+# produce valid context managers.
+contextmanager-decorators=contextlib.contextmanager
+
+# List of members which are set dynamically and missed by pylint inference
+# system, and so shouldn't trigger E1101 when accessed. Python regular
+# expressions are accepted.
+generated-members=
+
+# Tells whether missing members accessed in mixin class should be ignored. A
+# mixin class is detected if its name ends with "mixin" (case insensitive).
+ignore-mixin-members=yes
+
+# This flag controls whether pylint should warn about no-member and similar
+# checks whenever an opaque object is returned when inferring. The inference
+# can return multiple potential results while evaluating a Python object, but
+# some branches might not be evaluated, which results in partial inference. In
+# that case, it might be useful to still emit no-member and other checks for
+# the rest of the inferred objects.
+ignore-on-opaque-inference=yes
+
+# List of class names for which member attributes should not be checked (useful
+# for classes with dynamically set attributes). This supports the use of
+# qualified names.
+ignored-classes=optparse.Values,thread._local,_thread._local
+
+# List of module names for which member attributes should not be checked
+# (useful for modules/projects where namespaces are manipulated during runtime
+# and thus existing member attributes cannot be deduced by static analysis. It
+# supports qualified module names, as well as Unix pattern matching.
+ignored-modules=
+
+# Show a hint with possible names when a member name was not found. The aspect
+# of finding the hint is based on edit distance.
+missing-member-hint=yes
+
+# The minimum edit distance a name should have in order to be considered a
+# similar match for a missing member name.
+missing-member-hint-distance=1
+
+# The total number of similar names that should be taken in consideration when
+# showing a hint for a missing member.
+missing-member-max-choices=1
+
+
+[VARIABLES]
+
+# List of additional names supposed to be defined in builtins. Remember that
+# you should avoid to define new builtins when possible.
+additional-builtins=
+
+# Tells whether unused global variables should be treated as a violation.
+allow-global-unused-variables=yes
+
+# List of strings which can identify a callback function by name. A callback
+# name must start or end with one of those strings.
+callbacks=cb_,_cb
+
+# A regular expression matching the name of dummy variables (i.e. expectedly
+# not used).
+dummy-variables-rgx=_+$|(_[a-zA-Z0-9_]*[a-zA-Z0-9]+?$)|dummy|^ignored_|^unused_
+
+# Argument names that match this expression will be ignored. Default to name
+# with leading underscore
+ignored-argument-names=_.*|^ignored_|^unused_
+
+# Tells whether we should check for unused import in __init__ files.
+init-import=no
+
+# List of qualified module names which can have objects that can redefine
+# builtins.
+redefining-builtins-modules=six.moves,future.builtins
+
+
+[CLASSES]
+
+# List of method names used to declare (i.e. assign) instance attributes.
+defining-attr-methods=__init__,__new__,setUp
+
+# List of member names, which should be excluded from the protected access
+# warning.
+exclude-protected=_asdict,_fields,_replace,_source,_make
+
+# List of valid names for the first argument in a class method.
+valid-classmethod-first-arg=cls
+
+# List of valid names for the first argument in a metaclass class method.
+valid-metaclass-classmethod-first-arg=mcs
+
+
+[DESIGN]
+
+# Maximum number of arguments for function / method
+max-args=8
+max-positional-arguments=14
+
+# Maximum number of attributes for a class (see R0902).
+max-attributes=20
+
+# Maximum number of boolean expressions in a if statement
+max-bool-expr=5
+
+# Maximum number of branch for function / method body
+max-branches=12
+
+# Maximum number of locals for function / method body
+max-locals=20
+
+# Maximum number of parents for a class (see R0901).
+max-parents=7
+
+# Maximum number of public methods for a class (see R0904).
+max-public-methods=20
+
+# Maximum number of return / yield for function / method body
+max-returns=6
+
+# Maximum number of statements in function / method body
+max-statements=50
+
+# Minimum number of public methods for a class (see R0903).
+min-public-methods=2
+
+
+[IMPORTS]
+
+# Allow wildcard imports from modules that define __all__.
+allow-wildcard-with-all=no
+
+# Analyse import fallback blocks. This can be used to support both Python 2 and
+# 3 compatible code, which means that the block might have code that exists
+# only in one or another interpreter, leading to false positives when analysed.
+analyse-fallback-blocks=no
+
+# Deprecated modules which should not be used, separated by a comma
+deprecated-modules=optparse,tkinter.tix
+
+# Create a graph of external dependencies in the given file (report RP0402 must
+# not be disabled)
+ext-import-graph=
+
+# Create a graph of every (i.e. internal and external) dependencies in the
+# given file (report RP0402 must not be disabled)
+import-graph=
+
+# Create a graph of internal dependencies in the given file (report RP0402 must
+# not be disabled)
+int-import-graph=
+
+# Force import order to recognize a module as part of the standard
+# compatibility libraries.
+known-standard-library=
+
+# Force import order to recognize a module as part of a third party library.
+known-third-party=enchant
+
+
+[EXCEPTIONS]
+
+# Exceptions that will emit a warning when being caught. Defaults to
+# "Exception"
+overgeneral-exceptions=builtins.Exception

.tool-versions

@@ -0,0 +1,4 @@
+nodejs 23.5.0
+python 3.13.1
+shellcheck 0.10.0
+sqlite 3.47.2

.travis.yml

@@ -1,26 +0,0 @@
-language: python
-python:
-  - "2.7"
-before_install:
-  - "export DISPLAY=:99.0"
-  - "sh -e /etc/init.d/xvfb start"
-  - npm install -g less grunt-cli
-  - ( cd searx/static/oscar;npm install )
-install:
-  - "make"
-  - pip install coveralls
-script:
-  - "make tests"
-  - "make robot"
-  - "make styles"
-  - "make grunt"
-  - make coverage
-after_success:
-  coveralls
-notifications:
-  irc:
-    channels:
-      - "irc.freenode.org#searx"
-    template:
-      - "%{repository}/#%{build_number}/%{branch} (%{author}): %{message} %{build_url}"
-    on_success: change

.vscode/launch.json

@@ -0,0 +1,23 @@
+{
+    // See https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "SearXNG",
+            "type": "python",
+            "request": "launch",
+            "module": "searx.webapp",
+            "env": {
+                "FLASK_APP": "webapp",
+                "FLASK_DEBUG": "1",
+                "SEARXNG_DEBUG": "1",
+            },
+            "args": [
+                "run"
+            ],
+            "jinja": true,
+            "justMyCode": true,
+            "python": "${workspaceFolder}/local/py3/bin/python",
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+    "python.testing.unittestArgs": [
+        "-v",
+        "-s",
+        "./tests",
+        "-p",
+        "test_*.py"
+    ],
+    "python.testing.pytestEnabled": false,
+    "python.testing.unittestEnabled": true,
+}

.vscode/tasks.json

@@ -0,0 +1,36 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "make run",
+            "type": "shell",
+            "command": "make run",
+            "problemMatcher": [],
+            "isBackground": true,
+            "presentation": {
+                "reveal": "always",
+                "panel": "dedicated"
+            },
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "make docs.live",
+            "type": "shell",
+            "command": "make docs.live",
+            "problemMatcher": [],
+            "isBackground": true,
+            "presentation": {
+                "reveal": "always",
+                "panel": "dedicated"
+            },
+            "group": {
+                "kind": "build"
+            }
+        }
+    ]
+}

.weblate

@@ -0,0 +1,3 @@
+[weblate]
+url = https://translate.codeberg.org/api/
+translation = searxng/searxng

.yamllint.yml

@@ -0,0 +1,16 @@
+extends: default
+
+rules:
+
+  indentation:
+    spaces: 2
+
+  # 120 chars should be enough, but don't fail if a line is longer
+  line-length:
+    max: 120
+    level: warning
+    allow-non-breakable-words: true
+
+  # we don't have multiple document per file
+  document-start: disable
+  document-end: disable

AUTHORS.rst

@@ -1,14 +1,17 @@
-Searx was created and is maintained by Adam Tauber.
+searxng is a fork from `searx <https://github.com/searx/searx>`_ and is
+maintained by Markus Heiser (`@return42 <https://github.com/return42>`_)
 
-Major contributing authors:
+People who have submitted patches/translations, reported bugs, consulted
+features or generally made searx better:
 
-- Adam Tauber <asciimoo@gmail.com> `@asciimoo <https://github.com/asciimoo>`_
-- Matej Cotman
-- Thomas Pointhuber
-- Alexandre Flament
-
-People who have submitted patches/translates, reported bugs, consulted features or
-generally made searx better:
+- Adam Tauber `@asciimoo <https://github.com/asciimoo>`_
+- Matej Cotman `@matejc <https://github.com/matejc>`_
+- Émilien Devos `@unixfox <https://github.com/unixfox>`_
+- Thomas Pointhuber `pointhi <https://github.com/pointhi>`_
+- Noémi Ványi `@kvch <https://github.com/kvch>`_
+- `@Cqoicebordel <https://github.com/Cqoicebordel>`_
+- Marc Abonce Seguin `@MarcAbonce <https://github.com/MarcAbonce>`_
+- `@pofilo <https://github.com/pofilo>`_
 
 - Laszlo Hammerl
 - Stefan Marsiske
@@ -27,5 +30,148 @@ generally made searx better:
 - Martin Zimmermann
 - @courgette
 - @kernc
-- @Cqoicebordel
 - @Reventl0v
+- Caner Başaran
+- Benjamin Sonntag
+- @opi
+- @dimqua
+- Giorgos Logiotatidis
+- Luc Didry
+- Niklas Haas
+- @underr
+- Emmanuel Benazera
+- @GreenLunar
+- Kang-min Liu
+- Kirill Isakov
+- Guilhem Bonnefille
+- @jibe-b
+- Christian Pietsch @pietsch
+- @Maxqia
+- Ashutosh Das @pyprism
+- YuLun Shih @imZack
+- Dmitry Mikhirev @mikhirev
+- David A Roberts `@davidar <https://github.com/davidar>`_
+- Jan Verbeek @blyxxyz
+- Ammar Najjar @ammarnajjar
+- @stepshal
+- François Revol @mmuman
+- Harry Wood @harry-wood
+- Thomas Renard @threnard
+- Pydo `<https://github.com/pydo>`_
+- Athemis `<https://github.com/Athemis>`_
+- Stefan Antoni `<http://stefan.antoni.io>`
+- @firebovine
+- Lorenzo J. Lucchini @luccoj
+- @eig8phei
+- @maxigas
+- Jannik Winkel @kiney
+- @juanitobananas
+- Vache Asatryan @vachi
+- Luca CPZ @lcpz
+- @nikaiw
+- Thirnearez
+- Hypolite Petovan @MrPetovan
+- @woorst
+- @Apply55gx
+- @pyrrh0n1c
+- @cclauss
+- QGW @moon2l
+- Pierre-Alain Toret @daftaupe
+- Matthew Olmsted @icegiant
+- Michael Tran @trankmichael
+- Joseph Nuthalapati @josephkiranbabu
+- @maiki
+- Richard Didier @zeph33
+- Michael Vieria @Themimitoof
+- Richard Nespithal @rndevfx
+- Stanislas @angristan
+- @rinpatch
+- g. s. @usernameisntallowed
+- Léo Bourrel @bourrel
+- @cy8aer
+- @Popolon
+- Alice Ferrazzi @aliceinwire
+- @LiquidLemon
+- @dadosch
+- Václav Zouzalík @Venca24
+- @ZEROF
+- Ivan Skytte Jørgensen @isj-privacore
+- @miicha
+- Étienne Deparis @milouse
+- @pelag0s
+- Denis Wernert @d-tux
+- Robin Hallabro-Kokko @hallabro
+- Jonas Zohren @jfowl
+- Elias Ojala @theel0ja
+- @brunob
+- Nick Espig @nachtalb
+- Rachmadani Haryono @rachmadaniHaryono
+- Frank de Lange @yetangitu
+- Nicolas Gelot @nfk
+- @volth
+- Mathieu Brunot @madmath03
+- @lorddavidiii
+- @x250
+- Robby O'Connor @robbyoconnor
+- Finn @0xhtml
+- @tmikaeld
+- @hobbestigrou
+- Vipul @finn0
+- @CaffeinatedTech
+- Robin Schneider @ypid
+- @splintah
+- Lukas van den Berk @lukasvdberk
+- @piplongrun
+- Jason Kaltsikis @jjasonkal
+- Sion Kazama @KazamaSion
+- @resynth1943
+- Mostafa Ahangarha @ahangarha
+- @gordon-quad
+- Sophie Tauchert @999eagle
+- @bauruine
+- Michael Ilsaas `<https://mikeri.net>`_
+- @renyhp
+- rachmadani haryono @rachmadaniHaryono
+- Mohamad Safadieh @msafadieh
+- @gardouille
+- @resynth1943
+- @Eliesemoule
+- @gardouille
+- @GazoilKerozen
+- Lukáš Kucharczyk @KucharczykL
+- Lynda Lopez @lyndalopez544
+- M. Efe Çetin @efectn
+- Nícholas Kegler @nicholasks
+- @pierrechtux
+- Scott Wallace @scottwallacesh
+- @Singustromo
+- @TheEvilSkeleton
+- @Wonderfall
+- @mrwormo
+- Xiaoyu WEI @xywei
+- @joshu9h
+- Daniel Hones
+- @cyclaero
+- @thezeroalpha
+- @Tobi823
+- @archiecodes
+- @BBaoVanC
+- @datagram1
+- @lucky13820
+- @jhigginbotham
+- @xenrox
+- @OliveiraHermogenes
+- Paul Alcock @Guilvareux
+- Sam A. `<https://samsapti.dev>`_
+- @XavierHorwood
+- Ahmad Alkadri `<https://github.com/ahmad-alkadri>`_
+- Milad Laly @Milad-Laly
+- @llmII
+- @blob42 `<https://blob42.xyz>`_
+- Paolo Basso `<https://github.com/paolobasso99>`
+- Bernie Huang `<https://github.com/BernieHuang2008>`
+- Austin Olacsi `<https://github.com/Austin-Olacsi>`
+- @micsthepick
+- Daniel Kukula `<https://github.com/dkuku>`
+- Patrick Evans `https://github.com/holysoles`
+- Daniel Mowitz `<https://daniel.mowitz.rocks>`

CHANGELOG.rst

@@ -1,26 +1,14 @@
-0.6.0
-=====
+=======
+SearXNG
+=======
 
--  Changelog added
--  New engines
-   -  Flickr (api)
-   -  Subtitleseeker
-   -  photon
-   -  500px
-   -  Searchcode
-   -  Searchcode doc
-   -  Kickass torrent
--  Precise search request timeout handling
--  Better favicon support
--  Stricter config parsing
--  Translation updates
--  Multiple ui fixes
--  Flickr (noapi) engine fix
--  Pep8 fixes
+SearXNG development has been started in the middle of 2021 as a fork of the
+searx project.  Since it beginning its a rolling release pulled from SearXNG's
+master branch:
 
+- The CHANGELOG_ is replaced by the commit history of the master branch.
+- Since merged PR-229_, the version number is based on the git commit
 
-News
-~~~~
+.. _CHANGELOG: https://github.com/searxng/searxng/commits/master
+.. _PR-229: https://github.com/searxng/searxng/pull/229
 
-Health status of searx instances and engines: http://stats.searx.oe5tpo.com
-(source: https://github.com/pointhi/searx_stats)

CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# How to contribute
+
+## Resources in the documentation
+
+* [Development quickstart](https://docs.searxng.org/dev/quickstart.html)
+* [Contribution guide](https://docs.searxng.org/dev/contribution_guide.html)
+
+## Submitting PRs
+
+Please follow the provided PR template when writing a description for your changes.
+
+Do not take criticism personally. When you get feedback, it is about your work,
+not your character, personality, etc. Keep in mind we all want to make the project better.
+
+When something is not clear, please ask questions to clear things up.
+
+If you would like to introduce a big architectural changes or do a refactoring
+either in the codebase or the development tools, please open an issue with a proposal
+first. This way we can think together about the problem and probably come up
+with a better solution.
+
+## Coding conventions and guidelines
+
+### Commit messages
+
+* Always write descriptive commit messages ("fix bug" is not acceptable).
+* Use the present tense ("Add feature" not "Added feature").
+* Use the imperative mood ("Move cursor to..." not "Moves cursor to...").
+* Limit the first line to 72 characters or less.
+* Include the number of the issue you are fixing.
+
+### Coding guidelines
+
+As a Python project, we must follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) and [PEP 20](https://www.python.org/dev/peps/pep-0020/) guidelines.
+
+Furthermore, follow the Clean code conventions. The most important
+in this project are the following rules:
+
+* Simpler is better. [KISS principle](https://en.wikipedia.org/wiki/KISS_principle)
+* Be consistent.
+* Every function must do one thing.
+* Use descriptive names for functions and variables.
+* Always look for the root cause.
+* Keep configurable data high level.
+* Avoid negative conditionals.
+* Prefer fewer arguments.
+* Do not add obvious comment to code.
+* Do not comment out code, just delete lines.
+

Dockerfile

@@ -0,0 +1,89 @@
+FROM alpine:3.20
+ENTRYPOINT ["/sbin/tini","--","/usr/local/searxng/dockerfiles/docker-entrypoint.sh"]
+EXPOSE 8080
+VOLUME /etc/searxng
+
+ARG SEARXNG_GID=977
+ARG SEARXNG_UID=977
+
+RUN addgroup -g ${SEARXNG_GID} searxng && \
+    adduser -u ${SEARXNG_UID} -D -h /usr/local/searxng -s /bin/sh -G searxng searxng
+
+ENV INSTANCE_NAME=searxng \
+    AUTOCOMPLETE= \
+    BASE_URL= \
+    MORTY_KEY= \
+    MORTY_URL= \
+    SEARXNG_SETTINGS_PATH=/etc/searxng/settings.yml \
+    UWSGI_SETTINGS_PATH=/etc/searxng/uwsgi.ini \
+    UWSGI_WORKERS=%k \
+    UWSGI_THREADS=4
+
+WORKDIR /usr/local/searxng
+
+COPY requirements.txt ./requirements.txt
+
+RUN apk add --no-cache -t build-dependencies \
+    build-base \
+    py3-setuptools \
+    python3-dev \
+    libffi-dev \
+    libxslt-dev \
+    libxml2-dev \
+    openssl-dev \
+    tar \
+    git \
+ && apk add --no-cache \
+    ca-certificates \
+    python3 \
+    py3-pip \
+    libxml2 \
+    libxslt \
+    openssl \
+    tini \
+    uwsgi \
+    uwsgi-python3 \
+    brotli \
+ && pip3 install --break-system-packages --no-cache -r requirements.txt \
+ && apk del build-dependencies \
+ && rm -rf /root/.cache
+
+COPY --chown=searxng:searxng dockerfiles ./dockerfiles
+COPY --chown=searxng:searxng searx ./searx
+
+ARG TIMESTAMP_SETTINGS=0
+ARG TIMESTAMP_UWSGI=0
+ARG VERSION_GITCOMMIT=unknown
+
+RUN su searxng -c "/usr/bin/python3 -m compileall -q searx" \
+ && touch -c --date=@${TIMESTAMP_SETTINGS} searx/settings.yml \
+ && touch -c --date=@${TIMESTAMP_UWSGI} dockerfiles/uwsgi.ini \
+ && find /usr/local/searxng/searx/static -a \( -name '*.html' -o -name '*.css' -o -name '*.js' \
+    -o -name '*.svg' -o -name '*.ttf' -o -name '*.eot' \) \
+    -type f -exec gzip -9 -k {} \+ -exec brotli --best {} \+
+
+# Keep these arguments at the end to prevent redundant layer rebuilds
+ARG LABEL_DATE=
+ARG GIT_URL=unknown
+ARG SEARXNG_GIT_VERSION=unknown
+ARG SEARXNG_DOCKER_TAG=unknown
+ARG LABEL_VCS_REF=
+ARG LABEL_VCS_URL=
+LABEL maintainer="searxng <${GIT_URL}>" \
+      description="A privacy-respecting, hackable metasearch engine." \
+      version="${SEARXNG_GIT_VERSION}" \
+      org.label-schema.schema-version="1.0" \
+      org.label-schema.name="searxng" \
+      org.label-schema.version="${SEARXNG_GIT_VERSION}" \
+      org.label-schema.url="${LABEL_VCS_URL}" \
+      org.label-schema.vcs-ref=${LABEL_VCS_REF} \
+      org.label-schema.vcs-url=${LABEL_VCS_URL} \
+      org.label-schema.build-date="${LABEL_DATE}" \
+      org.label-schema.usage="https://github.com/searxng/searxng-docker" \
+      org.opencontainers.image.title="searxng" \
+      org.opencontainers.image.version="${SEARXNG_DOCKER_TAG}" \
+      org.opencontainers.image.url="${LABEL_VCS_URL}" \
+      org.opencontainers.image.revision=${LABEL_VCS_REF} \
+      org.opencontainers.image.source=${LABEL_VCS_URL} \
+      org.opencontainers.image.created="${LABEL_DATE}" \
+      org.opencontainers.image.documentation="https://github.com/searxng/searxng-docker"

LICENSE

@@ -1,14 +1,661 @@
-searx is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
 
-searx is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU Affero General Public License for more details.
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
 
-You should have received a copy of the GNU Affero General Public License
-along with searx. If not, see < http://www.gnu.org/licenses/ >.
+                            Preamble
 
-(C) 2013- by Adam Tauber, <asciimoo@gmail.com>
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<http://www.gnu.org/licenses/>.

Makefile

@@ -1,62 +1,103 @@
-# convenience makefile to boostrap & run buildout
-# use `make options=-v` to run buildout with extra options
+# -*- coding: utf-8; mode: makefile-gmake -*-
+# SPDX-License-Identifier: AGPL-3.0-or-later
 
-version = 2.7
-python = bin/python
-options =
+.DEFAULT_GOAL=help
+export MTOOLS=./manage
 
-all: .installed.cfg
+include utils/makefile.include
 
-.installed.cfg: bin/buildout buildout.cfg setup.py
-	bin/buildout $(options)
+all: clean install
 
-bin/buildout: $(python) buildout.cfg bootstrap.py
-	$(python) bootstrap.py
-	@touch $@
+PHONY += help
 
-$(python):
-	virtualenv -p python$(version) --no-site-packages .
-	@touch $@
+help:
+	@./manage --help
+	@echo '----'
+	@echo 'run            - run developer instance'
+	@echo 'install        - developer install of SearxNG into virtualenv'
+	@echo 'uninstall      - uninstall developer installation'
+	@echo 'clean          - clean up working tree'
+	@echo 'search.checker - check search engines'
+	@echo 'test           - run shell & CI tests'
+	@echo 'test.shell     - test shell scripts'
+	@echo 'ci.test        - run CI tests'
 
-tests: .installed.cfg
-	@bin/test
-	@grunt test --gruntfile searx/static/oscar/gruntfile.js
 
-robot: .installed.cfg
-	@bin/robot
+PHONY += run
+run:  install
+	$(Q)./manage webapp.run
 
-flake8: .installed.cfg
-	@bin/flake8 setup.py
-	@bin/flake8 ./searx/
+PHONY += install uninstall
+install uninstall:
+	$(Q)./manage pyenv.$@
 
-coverage: .installed.cfg
-	@bin/coverage run bin/test
-	@bin/coverage report
-	@bin/coverage html
+PHONY += clean
+clean: py.clean docs.clean node.clean nvm.clean test.clean
+	$(Q)./manage build_msg CLEAN  "common files"
+	$(Q)find . -name '*.orig' -exec rm -f {} +
+	$(Q)find . -name '*.rej' -exec rm -f {} +
+	$(Q)find . -name '*~' -exec rm -f {} +
+	$(Q)find . -name '*.bak' -exec rm -f {} +
 
-production: bin/buildout production.cfg setup.py
-	bin/buildout -c production.cfg $(options)
-	@echo "* Please modify `readlink --canonicalize-missing ./searx/settings.py`"
-	@echo "* Hint 1: on production, disable debug mode and change secret_key"
-	@echo "* Hint 2: searx will be executed at server startup by crontab"
-	@echo "* Hint 3: to run immediatley, execute 'bin/supervisord'"
+lxc.clean:
+	$(Q)rm -rf lxc-env
 
-minimal: bin/buildout minimal.cfg setup.py
-	bin/buildout -c minimal.cfg $(options)
+PHONY += search.checker search.checker.%
+search.checker: install
+	$(Q)./manage pyenv.cmd searxng-checker -v
 
-styles:
-	@lessc -x searx/static/default/less/style.less > searx/static/default/css/style.css
-	@lessc -x searx/static/oscar/less/bootstrap/bootstrap.less > searx/static/oscar/css/bootstrap.min.css
-	@lessc -x searx/static/oscar/less/oscar/oscar.less > searx/static/oscar/css/oscar.min.css
+search.checker.%: install
+	$(Q)./manage pyenv.cmd searxng-checker -v "$(subst _, ,$(patsubst search.checker.%,%,$@))"
 
-grunt:
-	@grunt --gruntfile searx/static/oscar/gruntfile.js
+PHONY += test ci.test test.shell
+ci.test: test.yamllint test.black test.types.ci  test.pylint test.unit test.robot test.rst test.shell test.pybabel test.themes
+test:    test.yamllint test.black test.types.dev test.pylint test.unit test.robot test.rst test.shell
+test.shell:
+	$(Q)shellcheck -x -s dash \
+		dockerfiles/docker-entrypoint.sh
+	$(Q)shellcheck -x -s bash \
+		utils/brand.sh \
+		$(MTOOLS) \
+		utils/lib.sh \
+		utils/lib_sxng*.sh \
+		utils/lib_go.sh \
+		utils/lib_nvm.sh \
+		utils/lib_redis.sh \
+		utils/searxng.sh \
+		utils/lxc.sh \
+		utils/lxc-searxng.env \
+		utils/searx.sh \
+		utils/filtron.sh \
+		utils/morty.sh
+	$(Q)$(MTOOLS) build_msg TEST "$@ OK"
 
-locales:
-	@pybabel compile -d searx/translations
 
-clean:
-	@rm -rf .installed.cfg .mr.developer.cfg bin parts develop-eggs \
-		searx.egg-info lib include .coverage coverage searx/static/default/css/*.css
+# wrap ./manage script
 
-.PHONY: all tests robot flake8 coverage production minimal styles locales clean
+MANAGE += weblate.translations.commit weblate.push.translations
+MANAGE += data.all data.traits data.useragents data.locales
+MANAGE += docs.html docs.live docs.gh-pages docs.prebuild docs.clean
+MANAGE += docker.build docker.push docker.buildx
+MANAGE += gecko.driver
+MANAGE += node.env node.env.dev node.clean
+MANAGE += py.build py.clean
+MANAGE += pyenv pyenv.install pyenv.uninstall
+MANAGE += format.python
+MANAGE += test.yamllint test.pylint test.black test.pybabel test.unit test.coverage test.robot test.rst test.clean test.themes test.types.dev test.types.ci
+MANAGE += themes.all themes.fix themes.test
+MANAGE += themes.simple themes.simple.pygments themes.simple.fix
+MANAGE += static.build.commit static.build.drop static.build.restore
+MANAGE += nvm.install nvm.clean nvm.status nvm.nodejs
+
+PHONY += $(MANAGE)
+
+$(MANAGE):
+	$(Q)$(MTOOLS) $@
+
+# short hands of selected targets
+
+PHONY += docs docker themes
+
+docs: docs.html
+docker:  docker.build
+themes: themes.all

PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+## What does this PR do?
+
+<!-- MANDATORY -->
+
+<!-- explain the changes in your PR, algorithms, design, architecture -->
+
+## Why is this change important?
+
+<!-- MANDATORY -->
+
+<!-- explain the motivation behind your PR -->
+
+## How to test this PR locally?
+
+<!-- commands to run the tests or instructions to test the changes -->
+
+## Author's checklist
+
+<!-- additional notes for reviewers -->
+
+## Related issues
+
+<!--
+Closes #234
+-->

README.rst

@@ -1,160 +1,134 @@
-searx
+.. SPDX-License-Identifier: AGPL-3.0-or-later
+
+----
+
+.. figure:: https://raw.githubusercontent.com/searxng/searxng/master/src/brand/searxng.svg
+   :target: https://docs.searxng.org/
+   :alt: SearXNG
+   :width: 100%
+   :align: center
+
+----
+
+This is a clone of the original SearXNG project.
+The only addition by retoor is the compose.yml file.
+Running this server is just `docker compose up` and it will run on 127.0.0.1:8088.
+
+Privacy-respecting, hackable `metasearch engine`_
+
+Searx.space_ lists ready-to-use running instances.
+
+A user_, admin_ and developer_ handbook is available on the homepage_.
+
+|SearXNG install|
+|SearXNG homepage|
+|SearXNG wiki|
+|AGPL License|
+|Issues|
+|commits|
+|weblate|
+|SearXNG logo|
+
+----
+
+.. _searx.space: https://searx.space
+.. _user: https://docs.searxng.org/user
+.. _admin: https://docs.searxng.org/admin
+.. _developer: https://docs.searxng.org/dev
+.. _homepage: https://docs.searxng.org/
+.. _metasearch engine: https://en.wikipedia.org/wiki/Metasearch_engine
+
+.. |SearXNG logo| image:: https://raw.githubusercontent.com/searxng/searxng/master/src/brand/searxng-wordmark.svg
+   :target: https://docs.searxng.org/
+   :width: 5%
+
+.. |SearXNG install| image:: https://img.shields.io/badge/-install-blue
+   :target: https://docs.searxng.org/admin/installation.html
+
+.. |SearXNG homepage| image:: https://img.shields.io/badge/-homepage-blue
+   :target: https://docs.searxng.org/
+
+.. |SearXNG wiki| image:: https://img.shields.io/badge/-wiki-blue
+   :target: https://github.com/searxng/searxng/wiki
+
+.. |AGPL License|  image:: https://img.shields.io/badge/license-AGPL-blue.svg
+   :target: https://github.com/searxng/searxng/blob/master/LICENSE
+
+.. |Issues| image:: https://img.shields.io/github/issues/searxng/searxng?color=yellow&label=issues
+   :target: https://github.com/searxng/searxng/issues
+
+.. |PR| image:: https://img.shields.io/github/issues-pr-raw/searxng/searxng?color=yellow&label=PR
+   :target: https://github.com/searxng/searxng/pulls
+
+.. |commits| image:: https://img.shields.io/github/commit-activity/y/searxng/searxng?color=yellow&label=commits
+   :target: https://github.com/searxng/searxng/commits/master
+
+.. |weblate| image:: https://translate.codeberg.org/widgets/searxng/-/searxng/svg-badge.svg
+   :target: https://translate.codeberg.org/projects/searxng/
+
+
+Contact
+=======
+
+Ask questions or chat with the SearXNG community (this not a chatbot) on
+
+IRC
+  `#searxng on libera.chat <https://web.libera.chat/?channel=#searxng>`_
+  which is bridged to Matrix.
+
+Matrix
+  `#searxng:matrix.org <https://matrix.to/#/#searxng:matrix.org>`_
+
+
+Setup
 =====
 
-A privacy-respecting, hackable `metasearch
-engine <https://en.wikipedia.org/wiki/Metasearch_engine>`__.
+- A well maintained `Docker image`_, also built for ARM64 and ARM/v7
+  architectures.
+- Alternatively there are *up to date* `installation scripts`_.
+- For individual setup consult our detailed `Step by step`_ instructions.
+- To fine-tune your instance, take a look at the `Administrator documentation`_.
 
-List of `running
-instances <https://github.com/asciimoo/searx/wiki/Searx-instances>`__.
+.. _Administrator documentation: https://docs.searxng.org/admin/index.html
+.. _Step by step: https://docs.searxng.org/admin/installation-searxng.html
+.. _installation scripts: https://docs.searxng.org/admin/installation-scripts.html
+.. _Docker image: https://github.com/searxng/searxng-docker
 
-See the `wiki <https://github.com/asciimoo/searx/wiki>`__ for more information.
+Translations
+============
 
-|Flattr searx|
+.. _Weblate: https://translate.codeberg.org/projects/searxng/searxng/
 
-Features
-~~~~~~~~
+Help translate SearXNG at `Weblate`_
 
--  Tracking free
--  Supports multiple output formats
-    -  json ``curl https://searx.me/?format=json&q=[query]``
-    -  csv ``curl https://searx.me/?format=csv&q=[query]``
-    -  opensearch/rss ``curl https://searx.me/?format=rss&q=[query]``
--  Opensearch support (you can set as default search engine)
--  Configurable search engines/categories
--  Different search languages
--  Duckduckgo like !bang functionality with engine shortcuts
--  Parallel queries - relatively fast
+.. figure:: https://translate.codeberg.org/widgets/searxng/-/multi-auto.svg
+   :target: https://translate.codeberg.org/projects/searxng/
 
-Installation
-~~~~~~~~~~~~
 
--  clone source:
-   ``git clone git@github.com:asciimoo/searx.git && cd searx``
--  install dependencies: ``pip install -r requirements.txt``
--  edit your
-   `settings.yml <https://github.com/asciimoo/searx/blob/master/settings.yml>`__
-   (set your ``secret_key``!)
--  run ``python searx/webapp.py`` to start the application
+Contributing
+============
 
-For all the details, follow this `step by step
-installation <https://github.com/asciimoo/searx/wiki/Installation>`__
+.. _development quickstart: https://docs.searxng.org/dev/quickstart.html
+.. _developer documentation: https://docs.searxng.org/dev/index.html
 
-Alternative (Recommended) Installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Are you a developer?  Have a look at our `development quickstart`_ guide, it's
+very easy to contribute.  Additionally we have a `developer documentation`_.
 
--  clone source:
-   ``git clone git@github.com:asciimoo/searx.git && cd searx``
--  build in current folder: ``make minimal``
--  run ``bin/searx-run`` to start the application
 
-Development
-~~~~~~~~~~~
+Codespaces
+==========
 
-Just run ``make``. Versions of dependencies are pinned down inside
-``versions.cfg`` to produce most stable build. Also remember, NO make
-command should be run as root, not even ``make production``
+You can contribute from your browser using `GitHub Codespaces`_:
 
-Deployment
-~~~~~~~~~~
+- Fork the repository
+- Click on the ``<> Code`` green button
+- Click on the ``Codespaces`` tab instead of ``Local``
+- Click on ``Create codespace on master``
+- VSCode is going to start in the browser
+- Wait for ``git pull && make install`` to appear and then disappear
+- You have `120 hours per month`_ (see also your `list of existing Codespaces`_)
+- You can start SearXNG using ``make run`` in the terminal or by pressing ``Ctrl+Shift+B``
 
--  clone source:
-   ``git clone git@github.com:asciimoo/searx.git && cd searx``
--  build in current folder: ``make production``
--  run ``bin/supervisord`` to start the application
-
-Upgrading
-~~~~~~~~~
-
--  inside previously cloned searx directory run: ``git stash`` to
-   temporarily save any changes you have made
--  pull source: ``git pull origin master``
--  re-build in current folder: ``make production``
--  run ``bin/supervisorctl stop searx`` to stop searx, if it does not,
-   then run ``fuser -k 8888/tcp``
--  run ``bin/supervisorctl reload`` to re-read supervisor config and
-   start searx
-
-Command make
-~~~~~~~~~~~~
-
-``make``
-''''''''
-
-Builds development environment with testing support.
-
-``make tests``
-''''''''''''''
-
-Runs tests. You can write tests
-`here <https://github.com/asciimoo/searx/tree/master/searx/tests>`__ and
-remember 'untested code is broken code'.
-
-``make robot``
-''''''''''''''
-
-Runs robot (Selenium) tests, you must have ``firefox`` installed because
-this functional tests actually run the browser and perform operations on
-it. Also searx is executed with
-`settings\_robot <https://github.com/asciimoo/searx/blob/master/searx/settings_robot.py>`__.
-
-``make flake8``
-'''''''''''''''
-
-'pep8 is a tool to check your Python code against some of the style
-conventions in `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`__.'
-
-``make coverage``
-'''''''''''''''''
-
-Checks coverage of tests, after running this, execute this:
-``firefox ./coverage/index.html``
-
-``make production``
-'''''''''''''''''''
-
-Used to make co-called production environment - without tests (you
-should ran tests before deploying searx on the server). This installs
-supervisord, so if searx crashes, it will try to pick itself up again.
-And crontab entry is added to start supervisord at server boot.
-
-``make minimal``
-''''''''''''''''
-
-Minimal build - without test frameworks, the quickest build option.
-
-``make clean``
-''''''''''''''
-
-Deletes several folders and files (see ``Makefile`` for more), so that
-next time you run any other ``make`` command it will rebuild everithing.
-
-TODO
-~~~~
-
--  Moar engines
--  Better ui
--  Browser integration
--  Documentation
--  Fix ``flake8`` errors, ``make flake8`` will be merged into
-   ``make tests`` when it does not fail anymore
--  Tests
--  When we have more tests, we can integrate Travis-CI
-
-Bugs
-~~~~
-
-Bugs or suggestions? Visit the `issue
-tracker <https://github.com/asciimoo/searx/issues>`__.
-
-`License <https://github.com/asciimoo/searx/blob/master/LICENSE>`__
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-More about searx
-~~~~~~~~~~~~~~~~
-
--  `ohloh <https://www.ohloh.net/p/searx/>`__
--  `twitter <https://twitter.com/Searx_engine>`__
--  IRC: #searx @ freenode
-
-.. |Flattr searx| image:: http://api.flattr.com/button/flattr-badge-large.png
-   :target: https://flattr.com/submit/auto?user_id=asciimoo&url=https://github.com/asciimoo/searx&title=searx&language=&tags=github&category=software
+.. _GitHub Codespaces: https://docs.github.com/en/codespaces/overview
+.. _120 hours per month: https://github.com/settings/billing
+.. _list of existing Codespaces: https://github.com/codespaces

SECURITY.md

@@ -0,0 +1,10 @@
+# Security Policy
+
+We love responsible reports of (potential) security issues in SearXNG.
+
+You can contact us at security@searxng.org.
+
+Be sure to provide as much information as possible and if found
+also reproduction steps of the identified vulnerability. Also
+add the specific URL of the project as well as code you found
+the issue in to your report.

babel.cfg

@@ -1,3 +1,6 @@
+[extractors]
+searxng_msg = searx.babel_extract.extract
+[ignore: **/node_modules/**]
 [python: **.py]
 [jinja2: **/templates/**.html]
-extensions=jinja2.ext.autoescape,jinja2.ext.with_
+[searxng_msg: **/searxng.msg]

base.cfg

@@ -1,23 +0,0 @@
-[buildout]
-extends = versions.cfg
-versions = versions
-unzip = true
-newest = false
-extends = versions.cfg
-versions = versions
-prefer-final = true
-develop = .
-
-extensions =
-    buildout_versions
-
-eggs =
-    searx
-
-parts =
-    omelette
-
-
-[omelette]
-recipe = collective.recipe.omelette
-eggs = ${buildout:eggs}

bootstrap.py

@@ -1,277 +0,0 @@
-##############################################################################
-#
-# Copyright (c) 2006 Zope Foundation and Contributors.
-# All Rights Reserved.
-#
-# This software is subject to the provisions of the Zope Public License,
-# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
-# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
-# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
-# FOR A PARTICULAR PURPOSE.
-#
-##############################################################################
-"""Bootstrap a buildout-based project
-
-Simply run this script in a directory containing a buildout.cfg.
-The script accepts buildout command-line options, so you can
-use the -c option to specify an alternate configuration file.
-"""
-
-import os, shutil, sys, tempfile, urllib, urllib2, subprocess
-from optparse import OptionParser
-
-if sys.platform == 'win32':
-    def quote(c):
-        if ' ' in c:
-            return '"%s"' % c  # work around spawn lamosity on windows
-        else:
-            return c
-else:
-    quote = str
-
-# See zc.buildout.easy_install._has_broken_dash_S for motivation and comments.
-stdout, stderr = subprocess.Popen(
-    [sys.executable, '-Sc',
-     'try:\n'
-     '    import ConfigParser\n'
-     'except ImportError:\n'
-     '    print 1\n'
-     'else:\n'
-     '    print 0\n'],
-    stdout=subprocess.PIPE, stderr=subprocess.PIPE).communicate()
-has_broken_dash_S = bool(int(stdout.strip()))
-
-# In order to be more robust in the face of system Pythons, we want to
-# run without site-packages loaded.  This is somewhat tricky, in
-# particular because Python 2.6's distutils imports site, so starting
-# with the -S flag is not sufficient.  However, we'll start with that:
-if not has_broken_dash_S and 'site' in sys.modules:
-    # We will restart with python -S.
-    args = sys.argv[:]
-    args[0:0] = [sys.executable, '-S']
-    args = map(quote, args)
-    os.execv(sys.executable, args)
-# Now we are running with -S.  We'll get the clean sys.path, import site
-# because distutils will do it later, and then reset the path and clean
-# out any namespace packages from site-packages that might have been
-# loaded by .pth files.
-clean_path = sys.path[:]
-import site  # imported because of its side effects
-sys.path[:] = clean_path
-for k, v in sys.modules.items():
-    if k in ('setuptools', 'pkg_resources') or (
-        hasattr(v, '__path__') and
-        len(v.__path__) == 1 and
-        not os.path.exists(os.path.join(v.__path__[0], '__init__.py'))):
-        # This is a namespace package.  Remove it.
-        sys.modules.pop(k)
-
-is_jython = sys.platform.startswith('java')
-
-setuptools_source = 'http://peak.telecommunity.com/dist/ez_setup.py'
-distribute_source = 'http://python-distribute.org/distribute_setup.py'
-distribute_source = 'https://bitbucket.org/pypa/setuptools/raw/f657df1f1ed46596d236376649c99a470662b4ba/distribute_setup.py'
-
-# parsing arguments
-def normalize_to_url(option, opt_str, value, parser):
-    if value:
-        if '://' not in value:  # It doesn't smell like a URL.
-            value = 'file://%s' % (
-                urllib.pathname2url(
-                    os.path.abspath(os.path.expanduser(value))),)
-        if opt_str == '--download-base' and not value.endswith('/'):
-            # Download base needs a trailing slash to make the world happy.
-            value += '/'
-    else:
-        value = None
-    name = opt_str[2:].replace('-', '_')
-    setattr(parser.values, name, value)
-
-usage = '''\
-[DESIRED PYTHON FOR BUILDOUT] bootstrap.py [options]
-
-Bootstraps a buildout-based project.
-
-Simply run this script in a directory containing a buildout.cfg, using the
-Python that you want bin/buildout to use.
-
-Note that by using --setup-source and --download-base to point to
-local resources, you can keep this script from going over the network.
-'''
-
-parser = OptionParser(usage=usage)
-parser.add_option("-v", "--version", dest="version",
-                          help="use a specific zc.buildout version")
-parser.add_option("-d", "--distribute",
-                   action="store_true", dest="use_distribute", default=False,
-                   help="Use Distribute rather than Setuptools.")
-parser.add_option("--setup-source", action="callback", dest="setup_source",
-                  callback=normalize_to_url, nargs=1, type="string",
-                  help=("Specify a URL or file location for the setup file. "
-                        "If you use Setuptools, this will default to " +
-                        setuptools_source + "; if you use Distribute, this "
-                        "will default to " + distribute_source + "."))
-parser.add_option("--download-base", action="callback", dest="download_base",
-                  callback=normalize_to_url, nargs=1, type="string",
-                  help=("Specify a URL or directory for downloading "
-                        "zc.buildout and either Setuptools or Distribute. "
-                        "Defaults to PyPI."))
-parser.add_option("--eggs",
-                  help=("Specify a directory for storing eggs.  Defaults to "
-                        "a temporary directory that is deleted when the "
-                        "bootstrap script completes."))
-parser.add_option("-t", "--accept-buildout-test-releases",
-                  dest='accept_buildout_test_releases',
-                  action="store_true", default=False,
-                  help=("Normally, if you do not specify a --version, the "
-                        "bootstrap script and buildout gets the newest "
-                        "*final* versions of zc.buildout and its recipes and "
-                        "extensions for you.  If you use this flag, "
-                        "bootstrap and buildout will get the newest releases "
-                        "even if they are alphas or betas."))
-parser.add_option("-c", None, action="store", dest="config_file",
-                   help=("Specify the path to the buildout configuration "
-                         "file to be used."))
-
-options, args = parser.parse_args()
-
-if options.eggs:
-    eggs_dir = os.path.abspath(os.path.expanduser(options.eggs))
-else:
-    eggs_dir = tempfile.mkdtemp()
-
-if options.setup_source is None:
-    if options.use_distribute:
-        options.setup_source = distribute_source
-    else:
-        options.setup_source = setuptools_source
-
-if options.accept_buildout_test_releases:
-    args.insert(0, 'buildout:accept-buildout-test-releases=true')
-
-try:
-    import pkg_resources
-    import setuptools  # A flag.  Sometimes pkg_resources is installed alone.
-    if not hasattr(pkg_resources, '_distribute'):
-        raise ImportError
-except ImportError:
-    ez_code = urllib2.urlopen(
-        options.setup_source).read().replace('\r\n', '\n')
-    ez = {}
-    exec ez_code in ez
-    setup_args = dict(to_dir=eggs_dir, download_delay=0)
-    if options.download_base:
-        setup_args['download_base'] = options.download_base
-    if options.use_distribute:
-        setup_args['no_fake'] = True
-        if sys.version_info[:2] == (2, 4):
-            setup_args['version'] = '0.6.32'
-    ez['use_setuptools'](**setup_args)
-    if 'pkg_resources' in sys.modules:
-        reload(sys.modules['pkg_resources'])
-    import pkg_resources
-    # This does not (always?) update the default working set.  We will
-    # do it.
-    for path in sys.path:
-        if path not in pkg_resources.working_set.entries:
-            pkg_resources.working_set.add_entry(path)
-
-cmd = [quote(sys.executable),
-       '-c',
-       quote('from setuptools.command.easy_install import main; main()'),
-       '-mqNxd',
-       quote(eggs_dir)]
-
-if not has_broken_dash_S:
-    cmd.insert(1, '-S')
-
-find_links = options.download_base
-if not find_links:
-    find_links = os.environ.get('bootstrap-testing-find-links')
-if not find_links and options.accept_buildout_test_releases:
-    find_links = 'http://downloads.buildout.org/'
-if find_links:
-    cmd.extend(['-f', quote(find_links)])
-
-if options.use_distribute:
-    setup_requirement = 'distribute'
-else:
-    setup_requirement = 'setuptools'
-ws = pkg_resources.working_set
-setup_requirement_path = ws.find(
-    pkg_resources.Requirement.parse(setup_requirement)).location
-env = dict(
-    os.environ,
-    PYTHONPATH=setup_requirement_path)
-
-requirement = 'zc.buildout'
-version = options.version
-if version is None and not options.accept_buildout_test_releases:
-    # Figure out the most recent final version of zc.buildout.
-    import setuptools.package_index
-    _final_parts = '*final-', '*final'
-
-    def _final_version(parsed_version):
-        for part in parsed_version:
-            if (part[:1] == '*') and (part not in _final_parts):
-                return False
-        return True
-    index = setuptools.package_index.PackageIndex(
-        search_path=[setup_requirement_path])
-    if find_links:
-        index.add_find_links((find_links,))
-    req = pkg_resources.Requirement.parse(requirement)
-    if index.obtain(req) is not None:
-        best = []
-        bestv = None
-        for dist in index[req.project_name]:
-            distv = dist.parsed_version
-            if distv >= pkg_resources.parse_version('2dev'):
-                continue
-            if _final_version(distv):
-                if bestv is None or distv > bestv:
-                    best = [dist]
-                    bestv = distv
-                elif distv == bestv:
-                    best.append(dist)
-        if best:
-            best.sort()
-            version = best[-1].version
-
-if version:
-    requirement += '=='+version
-else:
-    requirement += '<2dev'
-
-cmd.append(requirement)
-
-if is_jython:
-    import subprocess
-    exitcode = subprocess.Popen(cmd, env=env).wait()
-else:  # Windows prefers this, apparently; otherwise we would prefer subprocess
-    exitcode = os.spawnle(*([os.P_WAIT, sys.executable] + cmd + [env]))
-if exitcode != 0:
-    sys.stdout.flush()
-    sys.stderr.flush()
-    print ("An error occurred when trying to install zc.buildout. "
-           "Look above this message for any errors that "
-           "were output by easy_install.")
-    sys.exit(exitcode)
-
-ws.add_entry(eggs_dir)
-ws.require(requirement)
-import zc.buildout.buildout
-
-# If there isn't already a command in the args, add bootstrap
-if not [a for a in args if '=' not in a]:
-    args.append('bootstrap')
-
-
-# if -c was provided, we push it back into args for buildout's main function
-if options.config_file is not None:
-    args[0:0] = ['-c', options.config_file]
-
-zc.buildout.buildout.main(args)
-if not options.eggs:  # clean up temporary egg directory
-    shutil.rmtree(eggs_dir)

buildout.cfg

@@ -1,30 +0,0 @@
-[buildout]
-extends = base.cfg
-develop = .
-
-eggs =
-    searx [test]
-
-parts +=
-    pyscripts
-    robot
-    test
-
-
-[pyscripts]
-recipe = zc.recipe.egg:script
-eggs = ${buildout:eggs}
-interpreter = py
-dependent-scripts = true
-
-
-[robot]
-recipe = zc.recipe.testrunner
-eggs = ${buildout:eggs}
-defaults = ['--color', '--auto-progress', '--layer', 'SearxRobotLayer']
-
-
-[test]
-recipe = zc.recipe.testrunner
-eggs = ${buildout:eggs}
-defaults = ['--color', '--auto-progress', '--layer', 'SearxTestLayer', '--layer', '!SearxRobotLayer']

compose.yml

@@ -0,0 +1,30 @@
+services:
+  searxng:
+    restart: always
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        SEARXNG_GID: 977
+        SEARXNG_UID: 977
+        LABEL_DATE: ""
+        GIT_URL: "unknown"
+        SEARXNG_GIT_VERSION: "unknown"
+        SEARXNG_DOCKER_TAG: "unknown"
+        LABEL_VCS_REF: ""
+        LABEL_VCS_URL: ""
+    volumes:
+      - ./searx:/etc/searxng
+    ports:
+      - "127.0.0.1:8088:8080"
+    environment:
+      INSTANCE_NAME: searxng
+      AUTOCOMPLETE: ""
+      BASE_URL: ""
+      MORTY_KEY: ""
+      MORTY_URL: ""
+      SEARXNG_SETTINGS_PATH: /etc/searxng/settings.yml
+      UWSGI_SETTINGS_PATH: /etc/searxng/uwsgi.ini
+      UWSGI_WORKERS: "%k"
+      UWSGI_THREADS: 4
+    entrypoint: ["/sbin/tini", "--", "/usr/local/searxng/dockerfiles/docker-entrypoint.sh"]

dockerfiles/docker-entrypoint.sh

@@ -0,0 +1,178 @@
+#!/bin/sh
+
+help() {
+    cat <<EOF
+Command line:
+  -h  Display this help
+  -d  Dry run to update the configuration files.
+  -f  Always update on the configuration files (existing files are renamed with
+      the .old suffix).  Without this option, the new configuration files are
+      copied with the .new suffix
+Environment variables:
+  INSTANCE_NAME settings.yml : general.instance_name
+  AUTOCOMPLETE  settings.yml : search.autocomplete
+  BASE_URL      settings.yml : server.base_url
+  MORTY_URL     settings.yml : result_proxy.url
+  MORTY_KEY     settings.yml : result_proxy.key
+  BIND_ADDRESS  uwsgi bind to the specified TCP socket using HTTP protocol.
+                Default value: ${DEFAULT_BIND_ADDRESS}
+Volume:
+  /etc/searxng  the docker entry point copies settings.yml and uwsgi.ini in
+                this directory (see the -f command line option)"
+
+EOF
+}
+
+export DEFAULT_BIND_ADDRESS="0.0.0.0:8080"
+export BIND_ADDRESS="${BIND_ADDRESS:-${DEFAULT_BIND_ADDRESS}}"
+
+# Parse command line
+FORCE_CONF_UPDATE=0
+DRY_RUN=0
+
+while getopts "fdh" option
+do
+    case $option in
+
+        f) FORCE_CONF_UPDATE=1 ;;
+        d) DRY_RUN=1 ;;
+
+        h)
+            help
+            exit 0
+            ;;
+        *)
+            echo "unknow option ${option}"
+            exit 42
+            ;;
+    esac
+done
+
+get_searxng_version(){
+    su searxng -c \
+       'python3 -c "import six; import searx.version; six.print_(searx.version.VERSION_STRING)"' \
+       2>/dev/null
+}
+
+SEARXNG_VERSION="$(get_searxng_version)"
+export SEARXNG_VERSION
+echo "SearXNG version ${SEARXNG_VERSION}"
+
+# helpers to update the configuration files
+patch_uwsgi_settings() {
+    CONF="$1"
+
+    # update uwsg.ini
+    sed -i \
+        -e "s|workers = .*|workers = ${UWSGI_WORKERS:-%k}|g" \
+        -e "s|threads = .*|threads = ${UWSGI_THREADS:-4}|g" \
+        "${CONF}"
+}
+
+patch_searxng_settings() {
+    CONF="$1"
+
+    # Make sure that there is trailing slash at the end of BASE_URL
+    # see https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#Shell-Parameter-Expansion
+    export BASE_URL="${BASE_URL%/}/"
+
+    # update settings.yml
+    sed -i \
+        -e "s|base_url: false|base_url: ${BASE_URL}|g" \
+        -e "s/instance_name: \"SearXNG\"/instance_name: \"${INSTANCE_NAME}\"/g" \
+        -e "s/autocomplete: \"\"/autocomplete: \"${AUTOCOMPLETE}\"/g" \
+        -e "s/ultrasecretkey/$(openssl rand -hex 32)/g" \
+        "${CONF}"
+
+    # Morty configuration
+
+    if [ -n "${MORTY_KEY}" ] && [ -n "${MORTY_URL}" ]; then
+        sed -i -e "s/image_proxy: false/image_proxy: true/g" \
+            "${CONF}"
+        cat >> "${CONF}" <<-EOF
+
+# Morty configuration
+result_proxy:
+   url: ${MORTY_URL}
+   key: !!binary "${MORTY_KEY}"
+EOF
+    fi
+}
+
+update_conf() {
+    FORCE_CONF_UPDATE=$1
+    CONF="$2"
+    NEW_CONF="${2}.new"
+    OLD_CONF="${2}.old"
+    REF_CONF="$3"
+    PATCH_REF_CONF="$4"
+
+    if [ -f "${CONF}" ]; then
+        if [ "${REF_CONF}" -nt "${CONF}" ]; then
+            # There is a new version
+            if [ "$FORCE_CONF_UPDATE" -ne 0 ]; then
+                # Replace the current configuration
+                printf '⚠️  Automatically update %s to the new version\n' "${CONF}"
+                if [ ! -f "${OLD_CONF}" ]; then
+                    printf 'The previous configuration is saved to %s\n' "${OLD_CONF}"
+                    mv "${CONF}" "${OLD_CONF}"
+                fi
+                cp "${REF_CONF}" "${CONF}"
+                $PATCH_REF_CONF "${CONF}"
+            else
+                # Keep the current configuration
+                printf '⚠️  Check new version %s to make sure SearXNG is working properly\n' "${NEW_CONF}"
+                cp "${REF_CONF}" "${NEW_CONF}"
+                $PATCH_REF_CONF "${NEW_CONF}"
+            fi
+        else
+            printf 'Use existing %s\n' "${CONF}"
+        fi
+    else
+        printf 'Create %s\n' "${CONF}"
+        cp "${REF_CONF}" "${CONF}"
+        $PATCH_REF_CONF "${CONF}"
+    fi
+}
+
+# searx compatibility: copy /etc/searx/* to /etc/searxng/*
+SEARX_CONF=0
+if [ -f "/etc/searx/settings.yml" ]; then
+    if  [ ! -f "${SEARXNG_SETTINGS_PATH}" ]; then
+        printf '⚠️  /etc/searx/settings.yml is copied to /etc/searxng\n'
+        cp "/etc/searx/settings.yml" "${SEARXNG_SETTINGS_PATH}"
+    fi
+    SEARX_CONF=1
+fi
+if [ -f "/etc/searx/uwsgi.ini" ]; then
+    printf '⚠️  /etc/searx/uwsgi.ini is ignored. Use the volume /etc/searxng\n'
+    SEARX_CONF=1
+fi
+if [ "$SEARX_CONF" -eq "1" ]; then
+    printf '⚠️  The deprecated volume /etc/searx is mounted. Please update your configuration to use /etc/searxng ⚠️\n'
+    cat << EOF > /etc/searx/deprecated_volume_read_me.txt
+This Docker image uses the volume /etc/searxng
+Update your configuration:
+* remove uwsgi.ini (or very carefully update your existing uwsgi.ini using https://github.com/searxng/searxng/blob/master/dockerfiles/uwsgi.ini )
+* mount /etc/searxng instead of /etc/searx
+EOF
+fi
+# end of searx compatibility
+
+# make sure there are uwsgi settings
+update_conf "${FORCE_CONF_UPDATE}" "${UWSGI_SETTINGS_PATH}" "/usr/local/searxng/dockerfiles/uwsgi.ini" "patch_uwsgi_settings"
+
+# make sure there are searxng settings
+update_conf "${FORCE_CONF_UPDATE}" "${SEARXNG_SETTINGS_PATH}" "/usr/local/searxng/searx/settings.yml" "patch_searxng_settings"
+
+# dry run (to update configuration files, then inspect them)
+if [ $DRY_RUN -eq 1 ]; then
+    printf 'Dry run\n'
+    exit
+fi
+
+unset MORTY_KEY
+
+# Start uwsgi
+printf 'Listen on %s\n' "${BIND_ADDRESS}"
+exec uwsgi --master --uid searxng --gid searxng --http-socket "${BIND_ADDRESS}" "${UWSGI_SETTINGS_PATH}"

dockerfiles/uwsgi.ini

@@ -0,0 +1,54 @@
+[uwsgi]
+# Who will run the code
+uid = searxng
+gid = searxng
+
+# Number of workers (usually CPU count)
+# default value: %k (= number of CPU core, see Dockerfile)
+workers = $(UWSGI_WORKERS)
+
+# Number of threads per worker
+# default value: 4 (see Dockerfile)
+threads = $(UWSGI_THREADS)
+
+# The right granted on the created socket
+chmod-socket = 666
+
+# Plugin to use and interpreter config
+single-interpreter = true
+master = true
+plugin = python3
+lazy-apps = true
+enable-threads = true
+
+# Module to import
+module = searx.webapp
+
+# Virtualenv and python path
+pythonpath = /usr/local/searxng/
+chdir = /usr/local/searxng/searx/
+
+# automatically set processes name to something meaningful
+auto-procname = true
+
+# Disable request logging for privacy
+disable-logging = true
+log-5xx = true
+
+# Set the max size of a request (request-body excluded)
+buffer-size = 8192
+
+# No keep alive
+# See https://github.com/searx/searx-docker/issues/24
+add-header = Connection: close
+
+# Follow SIGTERM convention
+# See https://github.com/searxng/searxng/issues/3427
+die-on-term
+
+# uwsgi serves the static files
+static-map = /static=/usr/local/searxng/searx/static
+# expires set to one day
+static-expires = /* 86400
+static-gzip-all = True
+offload-threads = %k

docs/_themes/searxng/static/searxng.css

@@ -0,0 +1,151 @@
+@import url("pocoo.css");
+
+a, a.reference, a.footnote-reference {
+  color: #004b6b;
+  border-color: #004b6b;
+}
+
+a:hover {
+  color: #6d4100;
+  border-color: #6d4100;
+}
+
+p.version-warning {
+  background-color: #004b6b;
+}
+
+aside.sidebar {
+  background-color: whitesmoke;
+  border-color: lightsteelblue;
+  border-radius: 3pt;
+}
+
+div.sphinxsidebar p.caption {
+  display: none;
+}
+
+p.sidebar-title, .sidebar p {
+  margin: 6pt;
+}
+
+.sidebar li,
+.hlist li {
+  list-style-type: disclosure-closed;
+}
+
+.sphinxsidebar .current > a {
+  font-weight: bold;
+}
+
+/* admonitions
+*/
+
+div.admonition, div.topic, nav.contents, div.toctree-wrapper {
+  background-color: #fafafa;
+  margin: 8px 0px;
+  padding: 1em;
+  border-radius: 3pt 0 0 3pt;
+  border-top: none;
+  border-right: none;
+  border-bottom: none;
+  border-left: 5pt solid #ccc;
+  list-style-type: disclosure-closed;
+}
+
+div.toctree-wrapper p.caption {
+  font-weight: normal;
+  font-size: 24px;
+  margin: 0 0 10px 0;
+  padding: 0;
+  line-height: 1;
+  display: inline;
+}
+
+p.admonition-title:after {
+  content: none;
+}
+
+.admonition.hint      { border-color: #416dc0b0; }
+.admonition.note      { border-color: #6c856cb0; }
+.admonition.tip       { border-color: #85c5c2b0; }
+.admonition.attention { border-color: #ecec97b0; }
+.admonition.caution   { border-color: #a6c677b0; }
+.admonition.danger    { border-color: #d46262b0; }
+.admonition.important { border-color: #dfa3a3b0; }
+.admonition.error     { border-color: red; }
+.admonition.warning   { border-color: darkred; }
+
+.admonition.admonition-generic-admonition-title {
+    border-color: #416dc0b0;
+}
+
+
+/* admonitions with (rendered) reST markup examples (:class: rst-example)
+ *
+ * .. admonition:: title of the example
+ *     :class: rst-example
+ *     ....
+*/
+
+div.rst-example {
+  background-color: inherit;
+  margin: 0;
+  border-top: none;
+  border-right: 1px solid #ccc;
+  border-bottom: none;
+  border-left: none;
+  border-radius: none;
+  padding: 0;
+}
+
+div.rst-example > p.admonition-title {
+  font-family: Sans Serif;
+  font-style: italic;
+  font-size: 0.8em;
+  display: block;
+  border-bottom: 1px solid #ccc;
+  padding: 0.5em 1em;
+  text-align: right;
+}
+
+/* code block in figures
+ */
+
+div.highlight pre {
+    text-align: left;
+}
+
+/* Table theme
+*/
+
+thead, tfoot {
+  background-color: #fff;
+}
+
+th:hover, td:hover {
+  background-color: #ffc;
+}
+
+thead th, tfoot th, tfoot td, tbody th {
+  background-color: #fffaef;
+}
+
+tbody tr:nth-child(odd) {
+  background-color: #fff;
+}
+
+tbody tr:nth-child(even) {
+  background-color: #fafafa;
+}
+
+caption {
+  font-family: Sans Serif;
+  padding: 0.5em;
+  margin: 0.5em 0 0.5em 0;
+  caption-side: top;
+  text-align: left;
+}
+
+div.sphinx-tabs {
+    clear: both;
+}

docs/_themes/searxng/theme.conf

@@ -0,0 +1,7 @@
+[theme]
+inherit = pocoo
+stylesheet = searxng.css
+
+[options]
+touch_icon =
+globaltoc_maxdepth = 5

docs/admin/answer-captcha.rst

@@ -0,0 +1,69 @@
+===============================
+Answer CAPTCHA from server's IP
+===============================
+
+With a SSH tunnel we can send requests from server's IP and solve a CAPTCHA that
+blocks requests from this IP.  If your SearXNG instance is hosted at
+``example.org`` and your login is ``user`` you can setup a proxy simply by
+:man:`ssh`:
+
+.. code:: bash
+
+   # SOCKS server: socks://127.0.0.1:8080
+
+   $ ssh -q -N -D 8080 user@example.org
+
+The ``socks://localhost:8080`` from above can be tested by:
+
+.. tabs::
+
+  .. group-tab:: server's IP
+
+     .. code:: bash
+
+        $ curl -x socks://127.0.0.1:8080 http://ipecho.net/plain
+        n.n.n.n
+
+  .. group-tab:: desktop's IP
+
+     .. code:: bash
+
+        $ curl http://ipecho.net/plain
+        x.x.x.x
+
+In the settings of the WEB browser open the *"Network Settings"* and setup a
+proxy on ``SOCKS5 127.0.0.1:8080`` (see screenshot below).  In the WEB browser
+check the IP from the server is used:
+
+- http://ipecho.net/plain
+
+Now open the search engine that blocks requests from your server's IP.  If you
+have `issues with the qwant engine
+<https://github.com/searxng/searxng/issues/2011#issuecomment-1553317619>`__,
+solve the CAPTCHA from `qwant.com <https://www.qwant.com/>`__.
+
+-----
+
+.. tabs::
+
+  .. group-tab:: Firefox
+
+     .. kernel-figure:: answer-captcha/ffox-setting-proxy-socks.png
+        :alt: FFox proxy on SOCKS5, 127.0.0.1:8080
+
+        Firefox's network settings
+
+
+.. admonition:: :man:`ssh` manual:
+
+   -D [bind_address:]port
+     Specifies a local “dynamic” application-level port forwarding.  This works
+     by allocating a socket to listen to port on the local side ..  Whenever a
+     connection is made to this port, the connection is forwarded over the
+     secure channel, and the application protocol is then used to determine
+     where to connect to from the remote machine .. ssh will act as a SOCKS
+     server ..
+
+   -N
+      Do not execute a remote command.  This is useful for just forwarding ports.
+

docs/admin/api.rst

@@ -0,0 +1,92 @@
+.. _adminapi:
+
+==================
+Administration API
+==================
+
+Get configuration data
+======================
+
+.. code:: http
+
+    GET /config  HTTP/1.1
+
+Sample response
+---------------
+
+.. code:: json
+
+   {
+     "autocomplete": "",
+     "categories": [
+       "map",
+       "it",
+       "images",
+     ],
+     "default_locale": "",
+     "default_theme": "simple",
+     "engines": [
+       {
+         "categories": [
+           "map"
+         ],
+         "enabled": true,
+         "name": "openstreetmap",
+         "shortcut": "osm"
+       },
+       {
+         "categories": [
+           "it"
+         ],
+         "enabled": true,
+         "name": "arch linux wiki",
+         "shortcut": "al"
+       },
+       {
+         "categories": [
+           "images"
+         ],
+         "enabled": true,
+         "name": "google images",
+         "shortcut": "goi"
+       },
+       {
+         "categories": [
+           "it"
+         ],
+         "enabled": false,
+         "name": "bitbucket",
+         "shortcut": "bb"
+       },
+     ],
+     "instance_name": "searx",
+     "locales": {
+       "de": "Deutsch (German)",
+       "en": "English",
+       "eo": "Esperanto (Esperanto)",
+     },
+     "plugins": [
+       {
+         "enabled": true,
+         "name": "HTTPS rewrite"
+       }
+     ],
+     "safe_search": 0
+   }
+
+
+Embed search bar
+================
+
+The search bar can be embedded into websites.  Just paste the example into the
+HTML of the site.  URL of the SearXNG instance and values are customizable.
+
+.. code:: html
+
+   <form method="post" action="https://example.org/">
+     <!-- search      --> <input type="text" name="q">
+     <!-- categories  --> <input type="hidden" name="categories" value="general,social media">
+     <!-- language    --> <input type="hidden" name="lang" value="all">
+     <!-- locale      --> <input type="hidden" name="locale" value="en">
+     <!-- date filter --> <input type="hidden" name="time_range" value="month">
+   </form>

docs/admin/arch_public.dot

@@ -0,0 +1,30 @@
+digraph G {
+
+  node [style=filled, shape=box, fillcolor="#ffffcc", fontname=Sans];
+  edge [fontname="Sans"];
+
+  browser [label="browser", shape=tab, fillcolor=aliceblue];
+  rp      [label="reverse proxy"];
+  static  [label="static files", shape=folder, href="url to configure static files", fillcolor=lightgray];
+  uwsgi   [label="uwsgi", shape=parallelogram href="https://docs.searxng.org/utils/searx.sh.html"]
+  redis     [label="redis DB", shape=cylinder];
+  searxng1  [label="SearXNG #1", fontcolor=blue3];
+  searxng2  [label="SearXNG #2", fontcolor=blue3];
+  searxng3  [label="SearXNG #3", fontcolor=blue3];
+  searxng4  [label="SearXNG #4", fontcolor=blue3];
+
+  browser -> rp [label="HTTPS"]
+
+  subgraph cluster_searxng {
+      label = "SearXNG instance" fontname=Sans;
+      bgcolor="#fafafa";
+      { rank=same; static rp };
+      rp -> static  [label="optional: reverse proxy serves static files", fillcolor=slategray, fontcolor=slategray];
+      rp -> uwsgi [label="http:// (tcp) or unix:// (socket)"];
+      uwsgi -> searxng1 -> redis;
+      uwsgi -> searxng2 -> redis;
+      uwsgi -> searxng3 -> redis;
+      uwsgi -> searxng4 -> redis;
+  }
+
+}

docs/admin/architecture.rst

@@ -0,0 +1,38 @@
+.. _architecture:
+
+============
+Architecture
+============
+
+.. sidebar:: Further reading
+
+   - Reverse Proxy: :ref:`Apache <apache searxng site>` & :ref:`nginx <nginx
+     searxng site>`
+   - uWSGI: :ref:`searxng uwsgi`
+   - SearXNG: :ref:`installation basic`
+
+Herein you will find some hints and suggestions about typical architectures of
+SearXNG infrastructures.
+
+.. _architecture uWSGI:
+
+uWSGI Setup
+===========
+
+We start with a *reference* setup for public SearXNG instances which can be build
+up and maintained by the scripts from our :ref:`toolboxing`.
+
+.. _arch public:
+
+.. kernel-figure:: arch_public.dot
+   :alt: arch_public.dot
+
+   Reference architecture of a public SearXNG setup.
+
+The reference installation activates ``server.limiter``, ``server.image_proxy``
+and ``ui.static_use_hash`` (:origin:`/etc/searxng/settings.yml
+<utils/templates/etc/searxng/settings.yml>`)
+
+.. literalinclude:: ../../utils/templates/etc/searxng/settings.yml
+   :language: yaml
+   :end-before: # preferences:

docs/admin/buildhosts.rst

@@ -0,0 +1,163 @@
+.. _buildhosts:
+
+==========
+Buildhosts
+==========
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+To get best results from build, it's recommend to install additional packages on
+build hosts (see :ref:`searxng.sh`).
+
+.. _searxng.sh install buildhost:
+
+Build and Development tools
+===========================
+
+To Install tools used by build and development tasks in once:
+
+.. tabs::
+
+  .. group-tab:: SearXNG's development tools
+
+     .. code:: sh
+
+        $ sudo -H ./utils/searxng.sh install buildhost
+
+This will install packages needed by SearXNG:
+
+.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+   :start-after: START distro-packages
+   :end-before: END distro-packages
+
+and packages needed to build documentation and run tests:
+
+.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+   :start-after: START build-packages
+   :end-before: END build-packages
+
+.. _docs build:
+
+Build docs
+==========
+
+.. _Graphviz: https://graphviz.gitlab.io
+.. _ImageMagick: https://www.imagemagick.org
+.. _XeTeX: https://tug.org/xetex/
+.. _dvisvgm: https://dvisvgm.de/
+
+.. sidebar:: Sphinx build needs
+
+   - ImageMagick_
+   - Graphviz_
+   - XeTeX_
+   - dvisvgm_
+
+Most of the sphinx requirements are installed from :origin:`setup.py` and the
+docs can be build from scratch with ``make docs.html``.  For better math and
+image processing additional packages are needed.  The XeTeX_ needed not only for
+PDF creation, it's also needed for :ref:`math` when HTML output is build.
+
+To be able to do :ref:`sphinx:math-support` without CDNs, the math are rendered
+as images (``sphinx.ext.imgmath`` extension).
+
+Here is the extract from the :origin:`docs/conf.py` file, setting math renderer
+to ``imgmath``:
+
+.. literalinclude:: ../conf.py
+   :language: python
+   :start-after: # sphinx.ext.imgmath setup
+   :end-before: # sphinx.ext.imgmath setup END
+
+If your docs build (``make docs.html``) shows warnings like this::
+
+   WARNING: dot(1) not found, for better output quality install \
+            graphviz from https://www.graphviz.org
+   ..
+   WARNING: LaTeX command 'latex' cannot be run (needed for math \
+            display), check the imgmath_latex setting
+
+you need to install additional packages on your build host, to get better HTML
+output (:ref:`install buildhost <searxng.sh install buildhost>`).
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code-block:: sh
+
+         $ sudo apt install graphviz imagemagick texlive-xetex librsvg2-bin
+
+   .. group-tab:: Arch Linux
+
+      .. code-block:: sh
+
+         $ sudo pacman -S graphviz imagemagick texlive-bin extra/librsvg
+
+   .. group-tab::  Fedora / RHEL
+
+      .. code-block:: sh
+
+         $ sudo dnf install graphviz graphviz-gd ImageMagick texlive-xetex-bin librsvg2-tools
+
+
+For PDF output you also need:
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: sh
+
+         $ sudo apt texlive-latex-recommended texlive-extra-utils ttf-dejavu
+
+   .. group-tab:: Arch Linux
+
+      .. code:: sh
+
+      	 $ sudo pacman -S texlive-core texlive-latexextra ttf-dejavu
+
+   .. group-tab::  Fedora / RHEL
+
+      .. code:: sh
+
+      	 $ sudo dnf install \
+             texlive-collection-fontsrecommended texlive-collection-latex \
+             dejavu-sans-fonts dejavu-serif-fonts dejavu-sans-mono-fonts
+
+.. _sh lint:
+
+Lint shell scripts
+==================
+
+.. _ShellCheck: https://github.com/koalaman/shellcheck
+
+To lint shell scripts we use ShellCheck_ - a shell script static analysis tool
+(:ref:`install buildhost <searxng.sh install buildhost>`).
+
+.. SNIP sh lint requirements
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code-block:: sh
+
+         $ sudo apt install shellcheck
+
+   .. group-tab:: Arch Linux
+
+      .. code-block:: sh
+
+         $ sudo pacman -S shellcheck
+
+   .. group-tab::  Fedora / RHEL
+
+      .. code-block:: sh
+
+         $ sudo dnf install ShellCheck
+
+.. SNAP sh lint requirements

docs/admin/index.rst

@@ -0,0 +1,23 @@
+===========================
+Administrator documentation
+===========================
+
+.. toctree::
+   :maxdepth: 2
+
+   settings/index
+   installation
+   installation-docker
+   installation-scripts
+   installation-searxng
+   installation-uwsgi
+   installation-nginx
+   installation-apache
+   update-searxng
+   answer-captcha
+   searx.favicons
+   searx.limiter
+   api
+   architecture
+   plugins
+   buildhosts

docs/admin/installation-apache.rst

@@ -0,0 +1,388 @@
+.. _installation apache:
+
+======
+Apache
+======
+
+.. _Apache: https://httpd.apache.org/
+.. _Apache Debian:
+    https://cwiki.apache.org/confluence/display/HTTPD/DistrosDefaultLayout#DistrosDefaultLayout-Debian,Ubuntu(Apachehttpd2.x):
+.. _apache2.README.Debian:
+    https://salsa.debian.org/apache-team/apache2/raw/master/debian/apache2.README.Debian
+.. _Apache Arch Linux:
+    https://wiki.archlinux.org/index.php/Apache_HTTP_Server
+.. _Apache Fedora:
+    https://docs.fedoraproject.org/en-US/quick-docs/getting-started-with-apache-http-server/index.html
+.. _Apache directives:
+    https://httpd.apache.org/docs/trunk/mod/directives.html
+.. _Getting Started:
+    https://httpd.apache.org/docs/current/en/getting-started.html
+.. _Terms Used to Describe Directives:
+    https://httpd.apache.org/docs/current/en/mod/directive-dict.html
+.. _Configuration Files:
+    https://httpd.apache.org/docs/current/en/configuring.html
+.. _ProxyPreserveHost: https://httpd.apache.org/docs/trunk/mod/mod_proxy.html#proxypreservehost
+.. _LoadModule:
+    https://httpd.apache.org/docs/mod/mod_so.html#loadmodule
+.. _IncludeOptional:
+    https://httpd.apache.org/docs/mod/core.html#includeoptional
+.. _DocumentRoot:
+    https://httpd.apache.org/docs/trunk/mod/core.html#documentroot
+.. _Location:
+    https://httpd.apache.org/docs/trunk/mod/core.html#location
+.. _uWSGI Apache support:
+    https://uwsgi-docs.readthedocs.io/en/latest/Apache.html
+.. _mod_proxy_uwsgi:
+    https://uwsgi-docs.readthedocs.io/en/latest/Apache.html#mod-proxy-uwsgi
+.. _mod_proxy_http:
+    https://httpd.apache.org/docs/current/mod/mod_proxy_http.html
+.. _mod_proxy:
+    https://httpd.apache.org/docs/current/mod/mod_proxy.html
+
+
+This section explains how to set up a SearXNG instance using the HTTP server Apache_.
+If you did use the :ref:`installation scripts` and do not have any special preferences
+you can install the :ref:`SearXNG site <apache searxng site>` using
+:ref:`searxng.sh <searxng.sh overview>`:
+
+.. code:: bash
+
+   $ sudo -H ./utils/searxng.sh install apache
+
+If you have special interests or problems with setting up Apache, the following
+section might give you some guidance.
+
+
+.. sidebar:: further read
+
+   - `Apache Arch Linux`_
+   - `Apache Debian`_
+   - `apache2.README.Debian`_
+   - `Apache Fedora`_
+   - `Apache directives`_
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+
+The Apache HTTP server
+======================
+
+If Apache_ is not installed, install it now. If apache_ is new to you, the
+`Getting Started`_, `Configuration Files`_ and `Terms Used to Describe
+Directives`_ documentation gives first orientation.  There is also a list of
+`Apache directives`_ *to keep in the pocket*.
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: bash
+
+         sudo -H apt-get install apache2
+
+   .. group-tab:: Arch Linux
+
+      .. code:: bash
+
+         sudo -H pacman -S apache
+         sudo -H systemctl enable httpd
+         sudo -H systemctl start http
+
+   .. group-tab::  Fedora / RHEL
+
+      .. code:: bash
+
+         sudo -H dnf install httpd
+         sudo -H systemctl enable httpd
+         sudo -H systemctl start httpd
+
+Now at http://localhost you should see some kind of *Welcome* or *Test* page.
+How this default site is configured, depends on the linux distribution
+(compare `Apache directives`_).
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: bash
+
+         less /etc/apache2/sites-enabled/000-default.conf
+
+      In this file, there is a line setting the `DocumentRoot`_ directive:
+
+      .. code:: apache
+
+         DocumentRoot /var/www/html
+
+      And the *welcome* page is the HTML file at ``/var/www/html/index.html``.
+
+   .. group-tab:: Arch Linux
+
+      .. code:: bash
+
+         less /etc/httpd/conf/httpd.conf
+
+      In this file, there is a line setting the `DocumentRoot`_ directive:
+
+      .. code:: apache
+
+         DocumentRoot "/srv/http"
+         <Directory "/srv/http">
+             Options Indexes FollowSymLinks
+             AllowOverride None
+             Require all granted
+         </Directory>
+
+      The *welcome* page of Arch Linux is a page showing the directory located
+      at ``DocumentRoot``.  This *directory* page is generated by the Module
+      `mod_autoindex <https://httpd.apache.org/docs/2.4/mod/mod_autoindex.html>`_:
+
+      .. code:: apache
+
+         LoadModule autoindex_module modules/mod_autoindex.so
+         ...
+         Include conf/extra/httpd-autoindex.conf
+
+   .. group-tab::  Fedora / RHEL
+
+      .. code:: bash
+
+         less /etc/httpd/conf/httpd.conf
+
+      In this file, there is a line setting the ``DocumentRoot`` directive:
+
+      .. code:: apache
+
+          DocumentRoot "/var/www/html"
+          ...
+          <Directory "/var/www">
+              AllowOverride None
+              # Allow open access:
+              Require all granted
+          </Directory>
+
+      On fresh installations, the ``/var/www`` is empty and the *default
+      welcome page* is shown, the configuration is located at::
+
+        less /etc/httpd/conf.d/welcome.conf
+
+
+.. _Debian's Apache layout:
+
+Debian's Apache layout
+----------------------
+
+Be aware, Debian's Apache layout is quite different from the standard Apache
+configuration.  For details look at the apache2.README.Debian_
+(``/usr/share/doc/apache2/README.Debian.gz``).  Some commands you should know on
+Debian:
+
+* :man:`apache2ctl`:  Apache HTTP server control interface
+* :man:`a2enmod`, :man:`a2dismod`: switch on/off modules
+* :man:`a2enconf`, :man:`a2disconf`: switch on/off configurations
+* :man:`a2ensite`, :man:`a2dissite`: switch on/off sites
+
+.. _apache modules:
+
+Apache modules
+--------------
+
+To load additional modules, in most distributions you have to uncomment the
+lines with the corresponding LoadModule_ directive, except in :ref:`Debian's
+Apache layout`.
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      :ref:`Debian's Apache layout` uses :man:`a2enmod` and :man:`a2dismod` to
+      activate or disable modules:
+
+      .. code:: bash
+
+         sudo -H a2enmod ssl
+         sudo -H a2enmod headers
+         sudo -H a2enmod proxy
+         sudo -H a2enmod proxy_http
+         sudo -H a2enmod proxy_uwsgi
+
+   .. group-tab:: Arch Linux
+
+      In the ``/etc/httpd/conf/httpd.conf`` file, activate LoadModule_
+      directives:
+
+      .. code:: apache
+
+         LoadModule ssl_module           modules/mod_ssl.so
+         LoadModule headers_module       modules/mod_headers.so
+         LoadModule proxy_module         modules/mod_proxy.so
+         LoadModule proxy_http_module    modules/mod_proxy_http.so
+         LoadModule proxy_uwsgi_module   modules/mod_proxy_uwsgi.so
+
+   .. group-tab::  Fedora / RHEL
+
+      In the ``/etc/httpd/conf/httpd.conf`` file, activate LoadModule_
+      directives:
+
+      .. code:: apache
+
+         LoadModule ssl_module           modules/mod_ssl.so
+         LoadModule headers_module       modules/mod_headers.so
+         LoadModule proxy_module         modules/mod_proxy.so
+         LoadModule proxy_http_module    modules/mod_proxy_http.so
+         LoadModule proxy_uwsgi_module   modules/mod_proxy_uwsgi.so
+
+
+.. _apache sites:
+
+Apache sites
+------------
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      In :ref:`Debian's Apache layout` you create a ``searxng.conf`` with the
+      ``<Location /searxng >`` directive and save this file in the *sites
+      available* folder at ``/etc/apache2/sites-available``.  To enable the
+      ``searxng.conf`` use :man:`a2ensite`:
+
+      .. code:: bash
+
+         sudo -H a2ensite searxng.conf
+
+   .. group-tab:: Arch Linux
+
+      In the ``/etc/httpd/conf/httpd.conf`` file add a IncludeOptional_
+      directive:
+
+      .. code:: apache
+
+         IncludeOptional sites-enabled/*.conf
+
+      Create two folders, one for the *available sites* and one for the *enabled sites*:
+
+      .. code:: bash
+
+         mkdir -p /etc/httpd/sites-available
+         mkdir -p /etc/httpd/sites-enabled
+
+      Create configuration at ``/etc/httpd/sites-available`` and place a
+      symlink to ``sites-enabled``:
+
+      .. code:: bash
+
+         sudo -H ln -s /etc/httpd/sites-available/searxng.conf \
+                       /etc/httpd/sites-enabled/searxng.conf
+
+   .. group-tab::  Fedora / RHEL
+
+      In the ``/etc/httpd/conf/httpd.conf`` file add a IncludeOptional_
+      directive:
+
+      .. code:: apache
+
+         IncludeOptional sites-enabled/*.conf
+
+      Create two folders, one for the *available sites* and one for the *enabled sites*:
+
+      .. code:: bash
+
+         mkdir -p /etc/httpd/sites-available
+         mkdir -p /etc/httpd/sites-enabled
+
+      Create configuration at ``/etc/httpd/sites-available`` and place a
+      symlink to ``sites-enabled``:
+
+      .. code:: bash
+
+         sudo -H ln -s /etc/httpd/sites-available/searxng.conf \
+                       /etc/httpd/sites-enabled/searxng.conf
+
+
+.. _apache searxng site:
+
+Apache's SearXNG site
+=====================
+
+.. _mod_uwsgi: https://uwsgi-docs.readthedocs.io/en/latest/Apache.html#mod-uwsgi
+
+.. sidebar:: uWSGI
+
+   Use mod_proxy_uwsgi_ / don't use the old mod_uwsgi_ anymore.
+
+To proxy the incoming requests to the SearXNG instance Apache needs the
+mod_proxy_ module (:ref:`apache modules`).
+
+.. sidebar:: HTTP headers
+
+   With ProxyPreserveHost_ the incoming ``Host`` header is passed to the proxied
+   host.
+
+Depending on what your SearXNG installation is listening on, you need a http
+mod_proxy_http_) or socket (mod_proxy_uwsgi_) communication to upstream.
+
+The :ref:`installation scripts` installs the :ref:`reference setup
+<use_default_settings.yml>` and a :ref:`uwsgi setup` that listens on a socket by default.
+You can install and activate your own ``searxng.conf`` like shown in
+:ref:`apache sites`.
+
+.. tabs::
+
+   .. group-tab:: socket
+
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+         :start-after: START apache socket
+         :end-before: END apache socket
+
+   .. group-tab:: http
+
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+         :start-after: START apache http
+         :end-before: END apache http
+
+.. _restart apache:
+
+Restart service:
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: bash
+
+         sudo -H systemctl restart apache2
+         sudo -H service uwsgi restart searxng
+
+   .. group-tab:: Arch Linux
+
+      .. code:: bash
+
+         sudo -H systemctl restart httpd
+         sudo -H systemctl restart uwsgi@searxng
+
+   .. group-tab::  Fedora / RHEL
+
+      .. code:: bash
+
+         sudo -H systemctl restart httpd
+         sudo -H touch /etc/uwsgi.d/searxng.ini
+
+
+disable logs
+============
+
+For better privacy you can disable Apache logs.  In the examples above activate
+one of the lines and `restart apache`_:
+
+.. code:: apache
+
+   SetEnvIf Request_URI "/searxng" dontlog
+   # CustomLog /dev/null combined env=dontlog
+
+The ``CustomLog`` directive disables logs for the entire (virtual) server, use it
+when the URL of the service does not have a path component (``/searxng``), so when
+SearXNG is located at root (``/``).

docs/admin/installation-docker.rst

@@ -0,0 +1,197 @@
+.. _installation docker:
+
+================
+Docker Container
+================
+
+.. _ENTRYPOINT: https://docs.docker.com/engine/reference/builder/#entrypoint
+.. _searxng/searxng @dockerhub: https://hub.docker.com/r/searxng/searxng
+.. _searxng-docker: https://github.com/searxng/searxng-docker
+.. _[caddy]: https://hub.docker.com/_/caddy
+.. _Redis: https://redis.io/
+
+----
+
+.. sidebar:: info
+
+   - `searxng/searxng @dockerhub`_
+   - :origin:`Dockerfile`
+   - `Docker overview <https://docs.docker.com/get-started/overview>`_
+   - `Docker Cheat Sheet <https://docs.docker.com/get-started/docker_cheatsheet.pdf>`_
+   - `Alpine Linux <https://alpinelinux.org>`_
+     `(wiki) <https://en.wikipedia.org/wiki/Alpine_Linux>`__
+     `apt packages <https://pkgs.alpinelinux.org/packages>`_
+   - Alpine's ``/bin/sh`` is :man:`dash`
+
+**If you intend to create a public instance using Docker, use our well maintained
+docker container**
+
+- `searxng/searxng @dockerhub`_.
+
+.. sidebar:: hint
+
+   The rest of this article is of interest only to those who want to create and
+   maintain their own Docker images.
+
+The sources are hosted at searxng-docker_ and the container includes:
+
+- a HTTPS reverse proxy `[caddy]`_ and
+- a Redis_ DB
+
+The `default SearXNG setup <https://github.com/searxng/searxng-docker/blob/master/searxng/settings.yml>`_
+of this container:
+
+- enables :ref:`limiter <limiter>` to protect against bots
+- enables :ref:`image proxy <image_proxy>` for better privacy
+- enables :ref:`cache busting <static_use_hash>` to save bandwidth
+
+----
+
+
+Get Docker
+==========
+
+If you plan to build and maintain a docker image by yourself, make sure you have
+`Docker installed <https://docs.docker.com/get-docker/>`_. On Linux don't
+forget to add your user to the docker group (log out and log back in so that
+your group membership is re-evaluated):
+
+.. code:: sh
+
+   $ sudo usermod -a -G docker $USER
+
+
+searxng/searxng
+===============
+
+.. sidebar:: ``docker run``
+
+   - `-\-rm  <https://docs.docker.com/engine/reference/run/#clean-up---rm>`__
+     automatically clean up when container exits
+   - `-d <https://docs.docker.com/engine/reference/run/#detached--d>`__ start
+     detached container
+   - `-v <https://docs.docker.com/engine/reference/run/#volume-shared-filesystems>`__
+     mount volume ``HOST:CONTAINER``
+
+The docker image is based on :origin:`Dockerfile` and available from
+`searxng/searxng @dockerhub`_.  Using the docker image is quite easy, for
+instance you can pull the `searxng/searxng @dockerhub`_ image and deploy a local
+instance using `docker run <https://docs.docker.com/engine/reference/run/>`_:
+
+.. code:: sh
+
+   $ mkdir my-instance
+   $ cd my-instance
+   $ export PORT=8080
+   $ docker pull searxng/searxng
+   $ docker run --rm \
+                -d -p ${PORT}:8080 \
+                -v "${PWD}/searxng:/etc/searxng" \
+                -e "BASE_URL=http://localhost:$PORT/" \
+                -e "INSTANCE_NAME=my-instance" \
+                searxng/searxng
+   2f998.... # container's ID
+
+The environment variables UWSGI_WORKERS and UWSGI_THREADS overwrite the default
+number of UWSGI processes and UWSGI threads specified in `/etc/searxng/uwsgi.ini`.
+
+Open your WEB browser and visit the URL:
+
+.. code:: sh
+
+   $ xdg-open "http://localhost:$PORT"
+
+Inside ``${PWD}/searxng``, you will find ``settings.yml`` and ``uwsgi.ini``.  You
+can modify these files according to your needs and restart the Docker image.
+
+.. code:: sh
+
+   $ docker container restart 2f998
+
+Use command ``container ls`` to list running containers, add flag `-a
+<https://docs.docker.com/engine/reference/commandline/container_ls>`__ to list
+exited containers also.  With ``container stop`` a running container can be
+stopped.  To get rid of a container use ``container rm``:
+
+.. code:: sh
+
+   $ docker container ls
+   CONTAINER ID   IMAGE             COMMAND                  CREATED         ...
+   2f998d725993   searxng/searxng   "/sbin/tini -- /usr/…"   7 minutes ago   ...
+
+   $ docker container stop 2f998
+   $ docker container rm 2f998
+
+.. sidebar:: Warning
+
+   This might remove all docker items, not only those from SearXNG.
+
+If you won't use docker anymore and want to get rid of all containers & images
+use the following *prune* command:
+
+.. code:: sh
+
+   $ docker stop $(docker ps -aq)       # stop all containers
+   $ docker system prune                # make some housekeeping
+   $ docker rmi -f $(docker images -q)  # drop all images
+
+
+shell inside container
+----------------------
+
+.. sidebar:: Bashism
+
+   - `A tale of two shells: bash or dash <https://lwn.net/Articles/343924/>`_
+   - `How to make bash scripts work in dash <http://mywiki.wooledge.org/Bashism>`_
+   - `Checking for Bashisms  <https://dev.to/bowmanjd/writing-bash-scripts-that-are-not-only-bash-checking-for-bashisms-and-testing-with-dash-1bli>`_
+
+Like in many other distributions, Alpine's `/bin/sh
+<https://wiki.ubuntu.com/DashAsBinSh>`__ is :man:`dash`.  Dash is meant to be
+`POSIX-compliant <https://pubs.opengroup.org/onlinepubs/9699919799>`__.
+Compared to debian, in the Alpine image :man:`bash` is not installed.  The
+:origin:`dockerfiles/docker-entrypoint.sh` script is checked *against dash*
+(``make tests.shell``).
+
+To open a shell inside the container:
+
+.. code:: sh
+
+   $ docker exec -it 2f998 sh
+
+
+Build the image
+===============
+
+It's also possible to build SearXNG from the embedded :origin:`Dockerfile`::
+
+   $ git clone https://github.com/searxng/searxng.git
+   $ cd searxng
+   $ make docker.build
+   ...
+   Successfully built 49586c016434
+   Successfully tagged searxng/searxng:latest
+   Successfully tagged searxng/searxng:1.0.0-209-9c823800-dirty
+
+   $ docker images
+   REPOSITORY        TAG                        IMAGE ID       CREATED          SIZE
+   searxng/searxng   1.0.0-209-9c823800-dirty   49586c016434   13 minutes ago   308MB
+   searxng/searxng   latest                     49586c016434   13 minutes ago   308MB
+   alpine            3.13                       6dbb9cc54074   3 weeks ago      5.61MB
+
+
+Command line
+============
+
+.. sidebar:: docker run
+
+   Use flags ``-it`` for `interactive processes
+   <https://docs.docker.com/engine/reference/run/#foreground>`__.
+
+In the :origin:`Dockerfile` the ENTRYPOINT_ is defined as
+:origin:`dockerfiles/docker-entrypoint.sh`
+
+.. code:: sh
+
+    docker run --rm -it searxng/searxng -h
+
+.. program-output:: ../dockerfiles/docker-entrypoint.sh -h

docs/admin/installation-nginx.rst

@@ -0,0 +1,252 @@
+.. _installation nginx:
+
+=====
+NGINX
+=====
+
+.. _nginx:
+   https://docs.nginx.com/nginx/admin-guide/
+.. _nginx server configuration:
+   https://docs.nginx.com/nginx/admin-guide/web-server/web-server/#setting-up-virtual-servers
+.. _nginx beginners guide:
+   https://nginx.org/en/docs/beginners_guide.html
+.. _Getting Started wiki:
+   https://www.nginx.com/resources/wiki/start/
+.. _uWSGI support from nginx:
+   https://uwsgi-docs.readthedocs.io/en/latest/Nginx.html
+.. _uwsgi_params:
+   https://uwsgi-docs.readthedocs.io/en/latest/Nginx.html#configuring-nginx
+.. _SCRIPT_NAME:
+   https://werkzeug.palletsprojects.com/en/1.0.x/wsgi/#werkzeug.wsgi.get_script_name
+
+This section explains how to set up a SearXNG instance using the HTTP server nginx_.
+If you have used the :ref:`installation scripts` and do not have any special preferences
+you can install the :ref:`SearXNG site <nginx searxng site>` using
+:ref:`searxng.sh <searxng.sh overview>`:
+
+.. code:: bash
+
+   $ sudo -H ./utils/searxng.sh install nginx
+
+If you have special interests or problems with setting up nginx, the following
+section might give you some guidance.
+
+
+.. sidebar:: further reading
+
+   - nginx_
+   - `nginx beginners guide`_
+   - `nginx server configuration`_
+   - `Getting Started wiki`_
+   - `uWSGI support from nginx`_
+
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+
+The nginx HTTP server
+=====================
+
+If nginx_ is not installed, install it now.
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: bash
+
+         sudo -H apt-get install nginx
+
+   .. group-tab:: Arch Linux
+
+      .. code-block:: sh
+
+         sudo -H pacman -S nginx-mainline
+         sudo -H systemctl enable nginx
+         sudo -H systemctl start nginx
+
+   .. group-tab::  Fedora / RHEL
+
+      .. code-block:: sh
+
+         sudo -H dnf install nginx
+         sudo -H systemctl enable nginx
+         sudo -H systemctl start nginx
+
+Now at http://localhost you should see a *Welcome to nginx!* page, on Fedora you
+see a *Fedora Webserver - Test Page*.  The test page comes from the default
+`nginx server configuration`_.  How this default site is configured,
+depends on the linux distribution:
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: bash
+
+         less /etc/nginx/nginx.conf
+
+      There is one line that includes site configurations from:
+
+      .. code:: nginx
+
+         include /etc/nginx/sites-enabled/*;
+
+   .. group-tab:: Arch Linux
+
+      .. code-block:: sh
+
+         less /etc/nginx/nginx.conf
+
+      There is a configuration section named ``server``:
+
+      .. code-block:: nginx
+
+         server {
+             listen       80;
+             server_name  localhost;
+             # ...
+         }
+
+   .. group-tab::  Fedora / RHEL
+
+      .. code-block:: sh
+
+         less /etc/nginx/nginx.conf
+
+      There is one line that includes site configurations from:
+
+      .. code:: nginx
+
+          include /etc/nginx/conf.d/*.conf;
+
+
+.. _nginx searxng site:
+
+NGINX's SearXNG site
+====================
+
+Now you have to create a configuration file (``searxng.conf``) for the SearXNG
+site.  If nginx_ is new to you, the `nginx beginners guide`_ is a good starting
+point and the `Getting Started wiki`_ is always a good resource *to keep in the
+pocket*.
+
+Depending on what your SearXNG installation is listening on, you need a http or socket
+communication to upstream.
+
+.. tabs::
+
+   .. group-tab:: socket
+
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+         :start-after: START nginx socket
+         :end-before: END nginx socket
+
+   .. group-tab:: http
+
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+         :start-after: START nginx http
+         :end-before: END nginx http
+
+The :ref:`installation scripts` installs the :ref:`reference setup
+<use_default_settings.yml>` and a :ref:`uwsgi setup` that listens on a socket by default.
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      Create configuration at ``/etc/nginx/sites-available/`` and place a
+      symlink to ``sites-enabled``:
+
+      .. code:: bash
+
+         sudo -H ln -s /etc/nginx/sites-available/searxng.conf \
+                       /etc/nginx/sites-enabled/searxng.conf
+
+   .. group-tab:: Arch Linux
+
+      In the ``/etc/nginx/nginx.conf`` file, in the ``server`` section add a
+      `include <https://nginx.org/en/docs/ngx_core_module.html#include>`_
+      directive:
+
+      .. code:: nginx
+
+         server {
+             # ...
+             include /etc/nginx/default.d/*.conf;
+             # ...
+         }
+
+      Create two folders, one for the *available sites* and one for the *enabled sites*:
+
+      .. code:: bash
+
+         mkdir -p /etc/nginx/default.d
+         mkdir -p /etc/nginx/default.apps-available
+
+      Create configuration at ``/etc/nginx/default.apps-available`` and place a
+      symlink to ``default.d``:
+
+      .. code:: bash
+
+         sudo -H ln -s /etc/nginx/default.apps-available/searxng.conf \
+                       /etc/nginx/default.d/searxng.conf
+
+   .. group-tab::  Fedora / RHEL
+
+      Create a folder for the *available sites*:
+
+      .. code:: bash
+
+         mkdir -p /etc/nginx/default.apps-available
+
+      Create configuration at ``/etc/nginx/default.apps-available`` and place a
+      symlink to ``conf.d``:
+
+      .. code:: bash
+
+         sudo -H ln -s /etc/nginx/default.apps-available/searxng.conf \
+                       /etc/nginx/conf.d/searxng.conf
+
+Restart services:
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: bash
+
+         sudo -H systemctl restart nginx
+         sudo -H service uwsgi restart searxng
+
+   .. group-tab:: Arch Linux
+
+      .. code:: bash
+
+         sudo -H systemctl restart nginx
+         sudo -H systemctl restart uwsgi@searxng
+
+   .. group-tab:: Fedora / RHEL
+
+      .. code:: bash
+
+         sudo -H systemctl restart nginx
+         sudo -H touch /etc/uwsgi.d/searxng.ini
+
+
+Disable logs
+============
+
+For better privacy you can disable nginx logs in ``/etc/nginx/nginx.conf``.
+
+.. code:: nginx
+
+    http {
+        # ...
+        access_log /dev/null;
+        error_log  /dev/null;
+        # ...
+    }

docs/admin/installation-scripts.rst

@@ -0,0 +1,62 @@
+.. _installation scripts:
+
+===================
+Installation Script
+===================
+
+.. sidebar:: Update the OS first!
+
+   To avoid unwanted side effects, update your OS before installing SearXNG.
+
+The following will install a setup as shown in :ref:`the reference architecture
+<arch public>`.  First you need to get a clone of the repository.  The clone is only needed for
+the installation procedure and some maintenance tasks.
+
+.. sidebar:: further read
+
+   - :ref:`toolboxing`
+
+Jump to a folder that is readable by *others* and start to clone SearXNG,
+alternatively you can create your own fork and clone from there.
+
+.. code:: bash
+
+   $ cd ~/Downloads
+   $ git clone https://github.com/searxng/searxng.git searxng
+   $ cd searxng
+
+.. sidebar:: further read
+
+   - :ref:`inspect searxng`
+
+To install a SearXNG :ref:`reference setup <use_default_settings.yml>`
+including a :ref:`uWSGI setup <architecture uWSGI>` as described in the
+:ref:`installation basic` and in the :ref:`searxng uwsgi` section type:
+
+.. code:: bash
+
+   $ sudo -H ./utils/searxng.sh install all
+
+.. attention::
+
+   For the installation procedure, use a *sudoer* login to run the scripts.  If
+   you install from ``root``, take into account that the scripts are creating a
+   ``searxng`` user.  In the installation procedure this new created user does
+   need to have read access to the cloned SearXNG repository, which is not the case if you clone
+   it into a folder below ``/root``!
+
+.. sidebar:: further read
+
+   - :ref:`update searxng`
+
+.. _caddy: https://hub.docker.com/_/caddy
+
+When all services are installed and running fine, you can add SearXNG to your
+HTTP server.  We do not have any preferences regarding the HTTP server, you can use
+whatever you prefer.
+
+We use caddy in our :ref:`docker image <installation docker>` and we have
+implemented installation procedures for:
+
+- :ref:`installation nginx`
+- :ref:`installation apache`

docs/admin/installation-searxng.rst

@@ -0,0 +1,132 @@
+.. _installation basic:
+
+=========================
+Step by step installation
+=========================
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+
+In this section we show the setup of a SearXNG instance that will be installed
+by the :ref:`installation scripts`.
+
+.. _install packages:
+
+Install packages
+================
+
+.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+   :start-after: START distro-packages
+   :end-before: END distro-packages
+
+.. hint::
+
+   This installs also the packages needed by :ref:`searxng uwsgi`
+
+.. _create searxng user:
+
+Create user
+===========
+
+.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+   :start-after: START create user
+   :end-before: END create user
+
+.. _searxng-src:
+
+Install SearXNG & dependencies
+==============================
+
+Start a interactive shell from new created user and clone SearXNG:
+
+.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+   :start-after: START clone searxng
+   :end-before: END clone searxng
+
+In the same shell create *virtualenv*:
+
+.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+   :start-after: START create virtualenv
+   :end-before: END create virtualenv
+
+To install SearXNG's dependencies, exit the SearXNG *bash* session you opened above
+and start a new one.  Before installing, check if your *virtualenv* was sourced
+from the login (*~/.profile*):
+
+.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+   :start-after: START manage.sh update_packages
+   :end-before: END manage.sh update_packages
+
+.. tip::
+
+   Open a second terminal for the configuration tasks and leave the ``(searx)$``
+   terminal open for the tasks below.
+
+
+.. _use_default_settings.yml:
+
+Configuration
+=============
+
+.. sidebar:: ``use_default_settings: True``
+
+   - :ref:`settings.yml`
+   - :ref:`settings location`
+   - :ref:`settings use_default_settings`
+   - :origin:`/etc/searxng/settings.yml <utils/templates/etc/searxng/settings.yml>`
+
+To create a initial ``/etc/searxng/settings.yml`` we recommend to start with a
+copy of the file :origin:`utils/templates/etc/searxng/settings.yml`.  This setup
+:ref:`use default settings <settings use_default_settings>` from
+:origin:`searx/settings.yml` and is shown in the tab *"Use default settings"*
+below. This setup:
+
+- enables :ref:`limiter <limiter>` to protect against bots
+- enables :ref:`image proxy <image_proxy>` for better privacy
+- enables :ref:`cache busting <static_use_hash>` to save bandwidth
+
+Modify the ``/etc/searxng/settings.yml`` to your needs:
+
+.. tabs::
+
+  .. group-tab:: Use default settings
+
+     .. literalinclude:: ../../utils/templates/etc/searxng/settings.yml
+        :language: yaml
+        :end-before: # hostnames:
+
+     To see the entire file jump to :origin:`utils/templates/etc/searxng/settings.yml`
+
+  .. group-tab:: searx/settings.yml
+
+     .. literalinclude:: ../../searx/settings.yml
+        :language: yaml
+        :end-before: # hostnames:
+
+     To see the entire file jump to :origin:`searx/settings.yml`
+
+For a *minimal setup* you need to set ``server:secret_key``.
+
+.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+   :start-after: START searxng config
+   :end-before: END searxng config
+
+
+Check
+=====
+
+To check your SearXNG setup, optional enable debugging and start the *webapp*.
+SearXNG looks at the exported environment ``$SEARXNG_SETTINGS_PATH`` for a
+configuration file.
+
+.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+   :start-after: START check searxng installation
+   :end-before: END check searxng installation
+
+If everything works fine, hit ``[CTRL-C]`` to stop the *webapp* and disable the
+debug option in ``settings.yml``. You can now exit SearXNG user bash session (enter exit
+command twice).  At this point SearXNG is not demonized; uwsgi allows this.
+

docs/admin/installation-uwsgi.rst

@@ -0,0 +1,268 @@
+.. _searxng uwsgi:
+
+=====
+uWSGI
+=====
+
+.. sidebar:: further reading
+
+   - `systemd.unit`_
+   - `uWSGI Emperor`_
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+
+.. _systemd.unit: https://www.freedesktop.org/software/systemd/man/systemd.unit.html
+.. _One service per app in systemd:
+    https://uwsgi-docs.readthedocs.io/en/latest/Systemd.html#one-service-per-app-in-systemd
+.. _uWSGI Emperor:
+    https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html
+.. _uwsgi ini file:
+   https://uwsgi-docs.readthedocs.io/en/latest/Configuration.html#ini-files
+.. _systemd unit template:
+   http://0pointer.de/blog/projects/instances.html
+
+
+Origin uWSGI
+============
+
+.. _Tyrant mode:
+   https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html#tyrant-mode-secure-multi-user-hosting
+
+How uWSGI is implemented by distributors varies. The uWSGI project itself
+recommends two methods:
+
+1. `systemd.unit`_ template file as described here `One service per app in systemd`_:
+
+  There is one `systemd unit template`_ on the system installed and one `uwsgi
+  ini file`_ per uWSGI-app placed at dedicated locations.  Take archlinux and a
+  ``searxng.ini`` as example::
+
+    systemd template unit: /usr/lib/systemd/system/uwsgi@.service
+            contains: [Service]
+                      ExecStart=/usr/bin/uwsgi --ini /etc/uwsgi/%I.ini
+
+    SearXNG application:   /etc/uwsgi/searxng.ini
+            links to: /etc/uwsgi/apps-available/searxng.ini
+
+  The SearXNG app (template ``/etc/uwsgi/%I.ini``) can be maintained as known
+  from common systemd units:
+
+  .. code:: sh
+
+     $ systemctl enable  uwsgi@searxng
+     $ systemctl start   uwsgi@searxng
+     $ systemctl restart uwsgi@searxng
+     $ systemctl stop    uwsgi@searxng
+
+2. The `uWSGI Emperor`_ which fits for maintaining a large range of uwsgi
+   apps and there is a `Tyrant mode`_ to secure multi-user hosting.
+
+  The Emperor mode is a special uWSGI instance that will monitor specific
+  events.  The Emperor mode (the service) is started by a (common, not template)
+  systemd unit.
+
+  The Emperor service will scan specific directories for `uwsgi ini file`_\s
+  (also know as *vassals*).  If a *vassal* is added, removed or the timestamp is
+  modified, a corresponding action takes place: a new uWSGI instance is started,
+  reload or stopped.  Take Fedora and a ``searxng.ini`` as example::
+
+    to install & start SearXNG instance create --> /etc/uwsgi.d/searxng.ini
+    to reload the instance edit timestamp      --> touch /etc/uwsgi.d/searxng.ini
+    to stop instance remove ini                --> rm /etc/uwsgi.d/searxng.ini
+
+
+Distributors
+============
+
+The `uWSGI Emperor`_ mode and `systemd unit template`_ is what the distributors
+mostly offer their users, even if they differ in the way they implement both
+modes and their defaults.  Another point they might differ in is the packaging of
+plugins (if so, compare :ref:`install packages`) and what the default python
+interpreter is (python2 vs. python3).
+
+While archlinux does not start a uWSGI service by default, Fedora (RHEL) starts
+a Emperor in `Tyrant mode`_ by default (you should have read :ref:`uWSGI Tyrant
+mode pitfalls`).  Worth to know; debian (ubuntu) follow a complete different
+approach, read see :ref:`Debian's uWSGI layout`.
+
+.. _Debian's uWSGI layout:
+
+Debian's uWSGI layout
+---------------------
+
+.. _uwsgi.README.Debian:
+    https://salsa.debian.org/uwsgi-team/uwsgi/-/raw/debian/latest/debian/uwsgi.README.Debian
+
+Be aware, Debian's uWSGI layout is quite different from the standard uWSGI
+configuration.  Your are familiar with :ref:`Debian's Apache layout`? .. they do a
+similar thing for the uWSGI infrastructure. The folders are::
+
+    /etc/uwsgi/apps-available/
+    /etc/uwsgi/apps-enabled/
+
+The `uwsgi ini file`_ is enabled by a symbolic link::
+
+  ln -s /etc/uwsgi/apps-available/searxng.ini /etc/uwsgi/apps-enabled/
+
+More details can be found in the uwsgi.README.Debian_
+(``/usr/share/doc/uwsgi/README.Debian.gz``).  Some commands you should know on
+Debian:
+
+.. code:: none
+
+    Commands recognized by init.d script
+    ====================================
+
+    You can issue to init.d script following commands:
+      * start        | starts daemon
+      * stop         | stops daemon
+      * reload       | sends to daemon SIGHUP signal
+      * force-reload | sends to daemon SIGTERM signal
+      * restart      | issues 'stop', then 'start' commands
+      * status       | shows status of daemon instance (running/not running)
+
+    'status' command must be issued with exactly one argument: '<confname>'.
+
+    Controlling specific instances of uWSGI
+    =======================================
+
+    You could control specific instance(s) by issuing:
+
+        SYSTEMCTL_SKIP_REDIRECT=1 service uwsgi <command> <confname> <confname>...
+
+    where:
+      * <command> is one of 'start', 'stop' etc.
+      * <confname> is the name of configuration file (without extension)
+
+    For example, this is how instance for /etc/uwsgi/apps-enabled/hello.xml is
+    started:
+
+        SYSTEMCTL_SKIP_REDIRECT=1 service uwsgi start hello
+
+
+.. _uWSGI maintenance:
+
+uWSGI maintenance
+=================
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+         :start-after: START searxng uwsgi-description ubuntu-20.04
+         :end-before: END searxng uwsgi-description ubuntu-20.04
+
+   .. hotfix: a bug group-tab need this comment
+
+   .. group-tab:: Arch Linux
+
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+         :start-after: START searxng uwsgi-description arch
+         :end-before: END searxng uwsgi-description arch
+
+   .. hotfix: a bug group-tab need this comment
+
+   .. group-tab::  Fedora / RHEL
+
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+         :start-after: START searxng uwsgi-description fedora
+         :end-before: END searxng uwsgi-description fedora
+
+
+.. _uwsgi setup:
+
+uWSGI setup
+===========
+
+Create the configuration ini-file according to your distribution and restart the
+uwsgi application.  As shown below, the :ref:`installation scripts` installs by
+default:
+
+- a uWSGI setup that listens on a socket and
+- enables :ref:`cache busting <static_use_hash>`.
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+         :start-after: START searxng uwsgi-appini ubuntu-20.04
+         :end-before: END searxng uwsgi-appini ubuntu-20.04
+
+   .. hotfix: a bug group-tab need this comment
+
+   .. group-tab:: Arch Linux
+
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+         :start-after: START searxng uwsgi-appini arch
+         :end-before: END searxng uwsgi-appini arch
+
+   .. hotfix: a bug group-tab need this comment
+
+   .. group-tab::  Fedora / RHEL
+
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+         :start-after: START searxng uwsgi-appini fedora
+         :end-before: END searxng uwsgi-appini fedora
+
+
+.. _uWSGI Tyrant mode pitfalls:
+
+Pitfalls of the Tyrant mode
+===========================
+
+The implementation of the process owners and groups in the `Tyrant mode`_ is
+somewhat unusual and requires special consideration.  In `Tyrant mode`_ mode the
+Emperor will run the vassal using the UID/GID of the vassal configuration file
+(user and group of the app ``.ini`` file).
+
+.. _#2099@uWSGI: https://github.com/unbit/uwsgi/issues/2099
+.. _#752@uWSGI: https://github.com/unbit/uwsgi/pull/752
+.. _#2425uWSGI: https://github.com/unbit/uwsgi/issues/2425
+
+Without option ``emperor-tyrant-initgroups=true`` in ``/etc/uwsgi.ini`` the
+process won't get the additional groups, but this option is not available in
+2.0.x branch (see `#2099@uWSGI`_) the feature `#752@uWSGI`_ has been merged (on
+Oct. 2014) to the master branch of uWSGI but had never been released; the last
+major release is from Dec. 2013, since the there had been only bugfix releases
+(see `#2425uWSGI`_). To shorten up:
+
+  **In Tyrant mode, there is no way to get additional groups, and the uWSGI
+  process misses additional permissions that may be needed.**
+
+For example on Fedora (RHEL): If you try to install a redis DB with socket
+communication and you want to connect to it from the SearXNG uWSGI, you will see a
+*Permission denied* in the log of your instance::
+
+  ERROR:searx.redisdb: [searxng (993)] can't connect redis DB ...
+  ERROR:searx.redisdb:   Error 13 connecting to unix socket: /usr/local/searxng-redis/run/redis.sock. Permission denied.
+  ERROR:searx.plugins.limiter: init limiter DB failed!!!
+
+Even if your *searxng* user of the uWSGI process is added to additional groups
+to give access to the socket from the redis DB::
+
+  $ groups searxng
+  searxng : searxng searxng-redis
+
+To see the effective groups of the uwsgi process, you have to look at the status
+of the process, by example::
+
+  $ ps -aef | grep '/usr/sbin/uwsgi --ini searxng.ini'
+  searxng       93      92  0 12:43 ?        00:00:00 /usr/sbin/uwsgi --ini searxng.ini
+  searxng      186      93  0 12:44 ?        00:00:01 /usr/sbin/uwsgi --ini searxng.ini
+
+Here you can see that the additional "Groups" of PID 186 are unset (missing gid
+of ``searxng-redis``)::
+
+  $ cat /proc/186/task/186/status
+  ...
+  Uid:      993     993     993     993
+  Gid:      993     993     993     993
+  FDSize:   128
+  Groups:
+  ...

docs/admin/installation.rst

@@ -0,0 +1,22 @@
+.. _installation:
+
+============
+Installation
+============
+
+*You're spoilt for choice*, choose your preferred method of installation.
+
+- :ref:`installation docker`
+- :ref:`installation scripts`
+- :ref:`installation basic`
+
+The :ref:`installation basic` is an excellent illustration of *how a SearXNG
+instance is build up* (see :ref:`architecture uWSGI`).  If you do not have any
+special preferences, it's recommended to use the :ref:`installation docker` or the
+:ref:`installation scripts`.
+
+.. attention::
+
+   SearXNG is growing rapidly, you should regularly read our :ref:`migrate and
+   stay tuned` section.  If you want to upgrade an existing instance or migrate
+   from searx to SearXNG, you should read this section first!

docs/admin/plugins.rst

@@ -0,0 +1,36 @@
+.. _plugins admin:
+
+===============
+List of plugins
+===============
+
+.. sidebar:: Further reading ..
+
+   - :ref:`SearXNG settings <settings plugins>`
+   - :ref:`dev plugin`
+   - :ref:`builtin plugins`
+
+Configuration defaults (at built time):
+
+:DO: Default on
+
+.. _configured plugins:
+
+.. jinja:: searx
+
+   .. flat-table:: Plugins configured at built time (defaults)
+      :header-rows: 1
+      :stub-columns: 1
+      :widths: 3 1 9
+
+      * - Name
+        - DO
+        - Description
+
+      {% for plg in plugins %}
+
+      * - {{plg.info.name}}
+        - {{(plg.default_on and "y") or ""}}
+        - {{plg.info.description}}
+
+      {% endfor %}

docs/admin/searx.favicons.rst

@@ -0,0 +1,251 @@
+.. _favicons:
+
+========
+Favicons
+========
+
+.. sidebar:: warning
+
+   Don't activate the favicons before reading the documentation.
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+Activating the favicons in SearXNG is very easy, but this **generates a
+significantly higher load** in the client/server communication and increases
+resources needed on the server.
+
+To mitigate these disadvantages, various methods have been implemented,
+including a *cache*.  The cache must be parameterized according to your own
+requirements and maintained regularly.
+
+To activate favicons in SearXNG's result list, set a default
+``favicon_resolver`` in the :ref:`search <settings search>` settings:
+
+.. code:: yaml
+
+   search:
+     favicon_resolver: "duckduckgo"
+
+By default and without any extensions, SearXNG serves these resolvers:
+
+- ``duckduckgo``
+- ``allesedv``
+- ``google``
+- ``yandex``
+
+With the above setting favicons are displayed, the user has the option to
+deactivate this feature in his settings.  If the user is to have the option of
+selecting from several *resolvers*, a further setting is required / but this
+setting will be discussed :ref:`later <register resolvers>` in this article,
+first we have to setup the favicons cache.
+
+Infrastructure
+==============
+
+The infrastructure for providing the favicons essentially consists of three
+parts:
+
+- :py:obj:`Favicons-Proxy <.favicons.proxy>` (aka *proxy*)
+- :py:obj:`Favicons-Resolvers <.favicons.resolvers>` (aka *resolver*)
+- :py:obj:`Favicons-Cache <.favicons.cache>` (aka *cache*)
+
+To protect the privacy of users, the favicons are provided via a *proxy*.  This
+*proxy* is automatically activated with the above activation of a *resolver*.
+Additional requests are required to provide the favicons: firstly, the *proxy*
+must process the incoming requests and secondly, the *resolver* must make
+outgoing requests to obtain the favicons from external sources.
+
+A *cache* has been developed to massively reduce both, incoming and outgoing
+requests.  This *cache* is also activated automatically with the above
+activation of a *resolver*.  In its defaults, however, the *cache* is minimal
+and not well suitable for a production environment!
+
+.. _favicon cache setup:
+
+Setting up the cache
+====================
+
+To parameterize the *cache* and more settings of the favicons infrastructure, a
+TOML_ configuration is created in the file ``/etc/searxng/favicons.toml``.
+
+.. code:: toml
+
+   [favicons]
+
+   cfg_schema = 1   # config's schema version no.
+
+   [favicons.cache]
+
+   db_url = "/var/cache/searxng/faviconcache.db"  # default: "/tmp/faviconcache.db"
+   LIMIT_TOTAL_BYTES = 2147483648                 # 2 GB / default: 50 MB
+   # HOLD_TIME = 5184000                            # 60 days / default: 30 days
+   # BLOB_MAX_BYTES = 40960                         # 40 KB / default 20 KB
+   # MAINTENANCE_MODE = "off"                       # default: "auto"
+   # MAINTENANCE_PERIOD = 600                       # 10min / default: 1h
+
+:py:obj:`cfg_schema <.FaviconConfig.cfg_schema>`:
+  Is required to trigger any processes required for future upgrades / don't
+  change it.
+
+:py:obj:`cache.db_url <.FaviconCacheConfig.db_url>`:
+  The path to the (SQLite_) database file.  The default path is in the `/tmp`_
+  folder, which is deleted on every reboot and is therefore unsuitable for a
+  production environment.  The FHS_ provides the folder  for the
+  application cache
+
+  The FHS_ provides the folder `/var/cache`_ for the cache of applications, so a
+  suitable storage location of SearXNG's caches is folder ``/var/cache/searxng``.
+  In container systems, a volume should be mounted for this folder and in a
+  standard installation (compare :ref:`create searxng user`), the folder must be
+  created and the user under which the SearXNG process is running must be given
+  write permission to this folder.
+
+  .. code:: bash
+
+     $ sudo mkdir /var/cache/searxng
+     $ sudo chown root:searxng /var/cache/searxng/
+     $ sudo chmod g+w /var/cache/searxng/
+
+:py:obj:`cache.LIMIT_TOTAL_BYTES <.FaviconCacheConfig.LIMIT_TOTAL_BYTES>`:
+  Maximum of bytes stored in the cache of all blobs.  The limit is only reached
+  at each maintenance interval after which the oldest BLOBs are deleted; the
+  limit is exceeded during the maintenance period.
+
+  .. attention::
+
+     If the maintenance period is too long or maintenance is switched
+     off completely, the cache grows uncontrollably.
+
+SearXNG hosters can change other parameters of the cache as required:
+
+- :py:obj:`cache.HOLD_TIME <.FaviconCacheConfig.HOLD_TIME>`
+- :py:obj:`cache.BLOB_MAX_BYTES <.FaviconCacheConfig.BLOB_MAX_BYTES>`
+
+
+Maintenance of the cache
+------------------------
+
+Regular maintenance of the cache is required!  By default, regular maintenance
+is triggered automatically as part of the client requests:
+
+- :py:obj:`cache.MAINTENANCE_MODE <.FaviconCacheConfig.MAINTENANCE_MODE>` (default ``auto``)
+- :py:obj:`cache.MAINTENANCE_PERIOD <.FaviconCacheConfig.MAINTENANCE_PERIOD>` (default ``6000`` / 1h)
+
+As an alternative to maintenance as part of the client request process, it is
+also possible to carry out maintenance using an external process. For example,
+by creating a :man:`crontab` entry for maintenance:
+
+.. code:: bash
+
+   $ python -m searx.favicons cache maintenance
+
+The following command can be used to display the state of the cache:
+
+.. code:: bash
+
+   $ python -m searx.favicons cache state
+
+
+.. _favicon proxy setup:
+
+Proxy configuration
+===================
+
+Most of the options of the :py:obj:`Favicons-Proxy <.favicons.proxy>` are
+already set sensibly with settings from the :ref:`settings.yml <searxng
+settings.yml>` and should not normally be adjusted.
+
+.. code:: toml
+
+   [favicons.proxy]
+
+   max_age = 5184000             # 60 days / default: 7 days (604800 sec)
+
+
+:py:obj:`max_age <.FaviconProxyConfig.max_age>`:
+  The `HTTP Cache-Control max-age`_ response directive indicates that the
+  response remains fresh until N seconds after the response is generated.  This
+  setting therefore determines how long a favicon remains in the client's cache.
+  As a rule, in the favicons infrastructure of SearXNG's this setting only
+  affects favicons whose byte size exceeds :ref:`BLOB_MAX_BYTES <favicon cache
+  setup>` (the other favicons that are already in the cache are embedded as
+  `data URL`_ in the :py:obj:`generated HTML <.favicons.proxy.favicon_url>`,
+  which can greatly reduce the number of additional requests).
+
+.. _register resolvers:
+
+Register resolvers
+------------------
+
+A :py:obj:`resolver <.favicon.resolvers>` is a function that obtains the favicon
+from an external source.  The resolver functions available to the user are
+registered with their fully qualified name (FQN_) in a ``resolver_map``.
+
+If no ``resolver_map`` is defined in the ``favicon.toml``, the favicon
+infrastructure of SearXNG generates this ``resolver_map`` automatically
+depending on the ``settings.yml``.  SearXNG would automatically generate the
+following TOML configuration from the following YAML configuration:
+
+.. code:: yaml
+
+   search:
+     favicon_resolver: "duckduckgo"
+
+.. code:: toml
+
+   [favicons.proxy.resolver_map]
+
+   "duckduckgo" = "searx.favicons.resolvers.duckduckgo"
+
+If this automatism is not desired, then (and only then) a separate
+``resolver_map`` must be created.  For example, to give the user two resolvers to
+choose from, the following configuration could be used:
+
+.. code:: toml
+
+   [favicons.proxy.resolver_map]
+
+   "duckduckgo" = "searx.favicons.resolvers.duckduckgo"
+   "allesedv" = "searx.favicons.resolvers.allesedv"
+   # "google" = "searx.favicons.resolvers.google"
+   # "yandex" = "searx.favicons.resolvers.yandex"
+
+.. note::
+
+   With each resolver, the resource requirement increases significantly.
+
+The number of resolvers increases:
+
+- the number of incoming/outgoing requests and
+- the number of favicons to be stored in the cache.
+
+In the following we list the resolvers available in the core of SearXNG, but via
+the FQN_ it is also possible to implement your own resolvers and integrate them
+into the *proxy*:
+
+- :py:obj:`searx.favicons.resolvers.duckduckgo`
+- :py:obj:`searx.favicons.resolvers.allesedv`
+- :py:obj:`searx.favicons.resolvers.google`
+- :py:obj:`searx.favicons.resolvers.yandex`
+
+
+
+.. _SQLite:
+   https://www.sqlite.org/
+.. _FHS:
+   https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html
+.. _`/var/cache`:
+   https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch05s05.html
+.. _`/tmp`:
+   https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch03s18.html
+.. _TOML:
+    https://toml.io/en/
+.. _HTTP Cache-Control max-age:
+   https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#response_directives
+.. _data URL:
+   https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs
+.. _FQN: https://en.wikipedia.org/wiki/Fully_qualified_name
+

docs/admin/searx.limiter.rst

@@ -0,0 +1,17 @@
+.. _limiter:
+
+=======
+Limiter
+=======
+
+.. sidebar:: info
+
+   The limiter requires a :ref:`Redis <settings redis>` database.
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. automodule:: searx.limiter
+   :members:

docs/admin/settings/index.rst

@@ -0,0 +1,27 @@
+.. _searxng settings.yml:
+
+========
+Settings
+========
+
+.. sidebar:: Further reading ..
+
+   - :ref:`engine settings`
+   - :ref:`engine file`
+
+.. toctree::
+   :maxdepth: 2
+
+   settings
+   settings_engine
+   settings_brand
+   settings_general
+   settings_search
+   settings_server
+   settings_ui
+   settings_redis
+   settings_outgoing
+   settings_categories_as_tabs
+   settings_plugins
+
+

docs/admin/settings/settings.rst

@@ -0,0 +1,117 @@
+.. _settings.yml:
+
+================
+``settings.yml``
+================
+
+This page describe the options possibilities of the :origin:`searx/settings.yml`
+file.
+
+.. sidebar:: Further reading ..
+
+   - :ref:`use_default_settings.yml`
+   - :ref:`search API`
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. _settings location:
+
+settings.yml location
+=====================
+
+The initial ``settings.yml`` we be load from these locations:
+
+1. the full path specified in the ``SEARXNG_SETTINGS_PATH`` environment variable.
+2. ``/etc/searxng/settings.yml``
+
+If these files don't exist (or are empty or can't be read), SearXNG uses the
+:origin:`searx/settings.yml` file.  Read :ref:`settings use_default_settings` to
+see how you can simplify your *user defined* ``settings.yml``.
+
+
+
+.. _settings use_default_settings:
+
+use_default_settings
+====================
+
+.. sidebar:: ``use_default_settings: true``
+
+   - :ref:`settings location`
+   - :ref:`use_default_settings.yml`
+   - :origin:`/etc/searxng/settings.yml <utils/templates/etc/searxng/settings.yml>`
+
+The user defined ``settings.yml`` is loaded from the :ref:`settings location`
+and can relied on the default configuration :origin:`searx/settings.yml` using:
+
+ ``use_default_settings: true``
+
+``server:``
+  In the following example, the actual settings are the default settings defined
+  in :origin:`searx/settings.yml` with the exception of the ``secret_key`` and
+  the ``bind_address``:
+
+  .. code:: yaml
+
+    use_default_settings: true
+    server:
+        secret_key: "ultrasecretkey"   # change this!
+        bind_address: "0.0.0.0"
+
+``engines:``
+  With ``use_default_settings: true``, each settings can be override in a
+  similar way, the ``engines`` section is merged according to the engine
+  ``name``.  In this example, SearXNG will load all the default engines, will
+  enable the ``bing`` engine and define a :ref:`token <private engines>` for
+  the arch linux engine:
+
+  .. code:: yaml
+
+    use_default_settings: true
+    server:
+      secret_key: "ultrasecretkey"   # change this!
+    engines:
+      - name: arch linux wiki
+        tokens: ['$ecretValue']
+      - name: bing
+        disabled: false
+
+
+``engines:`` / ``remove:``
+  It is possible to remove some engines from the default settings. The following
+  example is similar to the above one, but SearXNG doesn't load the the google
+  engine:
+
+  .. code:: yaml
+
+    use_default_settings:
+      engines:
+        remove:
+          - google
+    server:
+      secret_key: "ultrasecretkey"   # change this!
+    engines:
+      - name: arch linux wiki
+        tokens: ['$ecretValue']
+
+``engines:`` / ``keep_only:``
+  As an alternative, it is possible to specify the engines to keep. In the
+  following example, SearXNG has only two engines:
+
+  .. code:: yaml
+
+    use_default_settings:
+      engines:
+        keep_only:
+          - google
+          - duckduckgo
+    server:
+      secret_key: "ultrasecretkey"   # change this!
+    engines:
+      - name: google
+        tokens: ['$ecretValue']
+      - name: duckduckgo
+        tokens: ['$ecretValue']

docs/admin/settings/settings_brand.rst

@@ -0,0 +1,25 @@
+.. _settings brand:
+
+==========
+``brand:``
+==========
+
+.. code:: yaml
+
+   brand:
+     issue_url: https://github.com/searxng/searxng/issues
+     docs_url: https://docs.searxng.org
+     public_instances: https://searx.space
+     wiki_url: https://github.com/searxng/searxng/wiki
+
+``issue_url`` :
+  If you host your own issue tracker change this URL.
+
+``docs_url`` :
+  If you host your own documentation change this URL.
+
+``public_instances`` :
+  If you host your own https://searx.space change this URL.
+
+``wiki_url`` :
+  Link to your wiki (or ``false``)

docs/admin/settings/settings_categories_as_tabs.rst

@@ -0,0 +1,31 @@
+.. _settings categories_as_tabs:
+
+=======================
+``categories_as_tabs:``
+=======================
+
+A list of the categories that are displayed as tabs in the user interface.
+Categories not listed here can still be searched with the :ref:`search-syntax`.
+
+.. code:: yaml
+
+  categories_as_tabs:
+    general:
+    images:
+    videos:
+    news:
+    map:
+    music:
+    it:
+    science:
+    files:
+    social media:
+
+Engines are added to ``categories:`` (compare :ref:`engine categories`), the
+categories listed in ``categories_as_tabs`` are shown as tabs in the UI.  If
+there are no active engines in a category, the tab is not displayed (e.g. if a
+user disables all engines in a category).
+
+On the preferences page (``/preferences``) -- under *engines* -- there is an
+additional tab, called *other*.  In this tab are all engines listed that are not
+in one of the UI tabs (not included in ``categories_as_tabs``).

docs/admin/settings/settings_engine.rst

@@ -0,0 +1,244 @@
+.. _settings engine:
+
+===========
+``engine:``
+===========
+
+.. sidebar:: Further reading ..
+
+   - :ref:`configured engines`
+   - :ref:`engines-dev`
+
+In the code example below a *full fledged* example of a YAML setup from a dummy
+engine is shown.  Most of the options have a default value or even are optional.
+
+.. hint::
+
+   A few more options are possible, but they are pretty specific to some
+   engines (:ref:`engine implementations`).
+
+.. code:: yaml
+
+   - name: example engine
+     engine: example
+     shortcut: demo
+     base_url: 'https://{language}.example.com/'
+     send_accept_language_header: false
+     categories: general
+     timeout: 3.0
+     api_key: 'apikey'
+     disabled: false
+     language: en_US
+     tokens: [ 'my-secret-token' ]
+     weight: 1
+     display_error_messages: true
+     about:
+        website: https://example.com
+        wikidata_id: Q306656
+        official_api_documentation: https://example.com/api-doc
+        use_official_api: true
+        require_api_key: true
+        results: HTML
+
+     # overwrite values from section 'outgoing:'
+     enable_http2: false
+     retries: 1
+     max_connections: 100
+     max_keepalive_connections: 10
+     keepalive_expiry: 5.0
+     using_tor_proxy: false
+     proxies:
+       http:
+         - http://proxy1:8080
+         - http://proxy2:8080
+       https:
+         - http://proxy1:8080
+         - http://proxy2:8080
+         - socks5://user:password@proxy3:1080
+         - socks5h://user:password@proxy4:1080
+
+     # other network settings
+     enable_http: false
+     retry_on_http_error: true # or 403 or [404, 429]
+
+
+``name`` :
+  Name that will be used across SearXNG to define this engine.  In settings, on
+  the result page...
+
+``engine`` :
+  Name of the python file used to handle requests and responses to and from this
+  search engine.
+
+``shortcut`` :
+  Code used to execute bang requests (in this case using ``!bi``)
+
+``base_url`` : optional
+  Part of the URL that should be stable across every request.  Can be useful to
+  use multiple sites using only one engine, or updating the site URL without
+  touching at the code.
+
+``send_accept_language_header`` :
+  Several engines that support languages (or regions) deal with the HTTP header
+  ``Accept-Language`` to build a response that fits to the locale.  When this
+  option is activated, the language (locale) that is selected by the user is used
+  to build and send a ``Accept-Language`` header in the request to the origin
+  search engine.
+
+.. _engine categories:
+
+``categories`` : optional
+  Specifies to which categories the engine should be added.  Engines can be
+  assigned to multiple categories.
+
+  Categories can be shown as tabs (:ref:`settings categories_as_tabs`) in the
+  UI.  A search in a tab (in the UI) will query all engines that are active in
+  this tab.  In the preferences page (``/preferences``) -- under *engines* --
+  users can select what engine should be active when querying in this tab.
+
+  Alternatively, :ref:`\!bang <search-syntax>` can be used to search all engines
+  in a category, regardless of whether they are active or not, or whether they
+  are in a tab of the UI or not.  For example, ``!dictionaries`` can be used to
+  query all search engines in that category (group).
+
+``timeout`` : optional
+  Timeout of the search with the current search engine.  Overwrites
+  ``request_timeout`` from :ref:`settings outgoing`.  **Be careful, it will
+  modify the global timeout of SearXNG.**
+
+``api_key`` : optional
+  In a few cases, using an API needs the use of a secret key.  How to obtain them
+  is described in the file.
+
+``disabled`` : optional
+  To disable by default the engine, but not deleting it.  It will allow the user
+  to manually activate it in the settings.
+
+``inactive``: optional
+  Remove the engine from the settings (*disabled & removed*).
+
+``language`` : optional
+  If you want to use another language for a specific engine, you can define it
+  by using the ISO code of language (and region), like ``fr``, ``en-US``,
+  ``de-DE``.
+
+``tokens`` : optional
+  A list of secret tokens to make this engine *private*, more details see
+  :ref:`private engines`.
+
+``weight`` : default ``1``
+  Weighting of the results of this engine.
+
+``display_error_messages`` : default ``true``
+  When an engine returns an error, the message is displayed on the user interface.
+
+``network`` : optional
+  Use the network configuration from another engine.
+  In addition, there are two default networks:
+
+  - ``ipv4`` set ``local_addresses`` to ``0.0.0.0`` (use only IPv4 local addresses)
+  - ``ipv6`` set ``local_addresses`` to ``::`` (use only IPv6 local addresses)
+
+``enable_http`` : optional
+  Enable HTTP for this engine (by default only HTTPS is enabled).
+
+``retry_on_http_error`` : optional
+  Retry request on some HTTP status code.
+
+  Example:
+
+  * ``true`` : on HTTP status code between 400 and 599.
+  * ``403`` : on HTTP status code 403.
+  * ``[403, 429]``: on HTTP status code 403 and 429.
+
+``proxies`` :
+  Overwrites proxy settings from :ref:`settings outgoing`.
+
+``using_tor_proxy`` :
+  Using tor proxy (``true``) or not (``false``) for this engine.  The default is
+  taken from ``using_tor_proxy`` of the :ref:`settings outgoing`.
+
+.. _Pool limit configuration: https://www.python-httpx.org/advanced/#pool-limit-configuration
+
+``max_keepalive_connection#s`` :
+  `Pool limit configuration`_, overwrites value ``pool_maxsize`` from
+   :ref:`settings outgoing` for this engine.
+
+``max_connections`` :
+  `Pool limit configuration`_, overwrites value ``pool_connections`` from
+  :ref:`settings outgoing` for this engine.
+
+``keepalive_expiry`` :
+  `Pool limit configuration`_, overwrites value ``keepalive_expiry`` from
+  :ref:`settings outgoing` for this engine.
+
+
+.. _private engines:
+
+Private Engines (``tokens``)
+============================
+
+Administrators might find themselves wanting to limit access to some of the
+enabled engines on their instances.  It might be because they do not want to
+expose some private information through :ref:`offline engines`.  Or they would
+rather share engines only with their trusted friends or colleagues.
+
+.. sidebar:: info
+
+   Initial sponsored by `Search and Discovery Fund
+   <https://nlnet.nl/discovery>`_ of `NLnet Foundation <https://nlnet.nl/>`_.
+
+To solve this issue the concept of *private engines* exists.
+
+A new option was added to engines named `tokens`.  It expects a list of strings.
+If the user making a request presents one of the tokens of an engine, they can
+access information about the engine and make search requests.
+
+Example configuration to restrict access to the Arch Linux Wiki engine:
+
+.. code:: yaml
+
+  - name: arch linux wiki
+    engine: archlinux
+    shortcut: al
+    tokens: [ 'my-secret-token' ]
+
+Unless a user has configured the right token, the engine is going to be hidden
+from them.  It is not going to be included in the list of engines on the
+Preferences page and in the output of `/config` REST API call.
+
+Tokens can be added to one's configuration on the Preferences page under "Engine
+tokens".  The input expects a comma separated list of strings.
+
+The distribution of the tokens from the administrator to the users is not carved
+in stone.  As providing access to such engines implies that the admin knows and
+trusts the user, we do not see necessary to come up with a strict process.
+Instead, we would like to add guidelines to the documentation of the feature.
+
+
+Example: Multilingual Search
+============================
+
+SearXNG does not support true multilingual search.  You have to use the language
+prefix in your search query when searching in a different language.
+
+But there is a workaround: By adding a new search engine with a different
+language, SearXNG will search in your default and other language.
+
+Example configuration in settings.yml for a German and English speaker:
+
+.. code-block:: yaml
+
+    search:
+        default_lang : "de"
+        ...
+
+    engines:
+      - name : google english
+        engine : google
+        language : en
+        ...
+
+When searching, the default google engine will return German results and
+"google english" will return English results.
+

docs/admin/settings/settings_general.rst

@@ -0,0 +1,42 @@
+.. _settings general:
+
+============
+``general:``
+============
+
+.. code:: yaml
+
+   general:
+     debug: false
+     instance_name:  "SearXNG"
+     privacypolicy_url: false
+     donation_url: false
+     contact_url: false
+     enable_metrics: true
+     open_metrics: ''
+
+``debug`` : ``$SEARXNG_DEBUG``
+  Allow a more detailed log if you run SearXNG directly. Display *detailed* error
+  messages in the browser too, so this must be deactivated in production.
+
+``donation_url`` :
+  Set value to ``true`` to use your own donation page written in the
+  :ref:`searx/info/en/donate.md <searx.infopage>` and use ``false`` to disable
+  the donation link altogether.
+
+``privacypolicy_url``:
+  Link to privacy policy.
+
+``contact_url``:
+  Contact ``mailto:`` address or WEB form.
+
+``enable_metrics``:
+  Enabled by default. Record various anonymous metrics available at ``/stats``,
+  ``/stats/errors`` and ``/preferences``.
+
+``open_metrics``:
+  Disabled by default. Set to a secret password to expose an
+  `OpenMetrics API <https://github.com/prometheus/OpenMetrics>`_ at ``/metrics``,
+  e.g. for usage with Prometheus. The ``/metrics`` endpoint is using HTTP Basic Auth,
+  where the password is the value of ``open_metrics`` set above. The username used for
+  Basic Auth can be randomly chosen as only the password is being validated.

docs/admin/settings/settings_outgoing.rst

@@ -0,0 +1,110 @@
+.. _settings outgoing:
+
+=============
+``outgoing:``
+=============
+
+Communication with search engines.
+
+.. code:: yaml
+
+   outgoing:
+     request_timeout: 2.0       # default timeout in seconds, can be override by engine
+     max_request_timeout: 10.0  # the maximum timeout in seconds
+     useragent_suffix: ""       # information like an email address to the administrator
+     pool_connections: 100      # Maximum number of allowable connections, or null
+                                # for no limits. The default is 100.
+     pool_maxsize: 10           # Number of allowable keep-alive connections, or null
+                                # to always allow. The default is 10.
+     enable_http2: true         # See https://www.python-httpx.org/http2/
+     # uncomment below section if you want to use a custom server certificate
+     # see https://www.python-httpx.org/advanced/#changing-the-verification-defaults
+     # and https://www.python-httpx.org/compatibility/#ssl-configuration
+     #  verify: ~/.mitmproxy/mitmproxy-ca-cert.cer
+     #
+     # uncomment below section if you want to use a proxyq see: SOCKS proxies
+     #   https://2.python-requests.org/en/latest/user/advanced/#proxies
+     # are also supported: see
+     #   https://2.python-requests.org/en/latest/user/advanced/#socks
+     #
+     #  proxies:
+     #    all://:
+     #      - http://proxy1:8080
+     #      - http://proxy2:8080
+     #
+     #  using_tor_proxy: true
+     #
+     # Extra seconds to add in order to account for the time taken by the proxy
+     #
+     #  extra_proxy_timeout: 10.0
+     #
+
+``request_timeout`` :
+  Global timeout of the requests made to others engines in seconds.  A bigger
+  timeout will allow to wait for answers from slow engines, but in consequence
+  will slow SearXNG reactivity (the result page may take the time specified in the
+  timeout to load).  Can be override by ``timeout`` in the :ref:`settings engine`.
+
+``useragent_suffix`` :
+  Suffix to the user-agent SearXNG uses to send requests to others engines.  If an
+  engine wish to block you, a contact info here may be useful to avoid that.
+
+.. _Pool limit configuration: https://www.python-httpx.org/advanced/#pool-limit-configuration
+
+``pool_maxsize``:
+  Number of allowable keep-alive connections, or ``null`` to always allow.  The
+  default is 10.  See ``max_keepalive_connections`` `Pool limit configuration`_.
+
+``pool_connections`` :
+  Maximum number of allowable connections, or ``null`` # for no limits.  The
+  default is 100.  See ``max_connections`` `Pool limit configuration`_.
+
+``keepalive_expiry`` :
+  Number of seconds to keep a connection in the pool.  By default 5.0 seconds.
+  See ``keepalive_expiry`` `Pool limit configuration`_.
+
+.. _httpx proxies: https://www.python-httpx.org/advanced/#http-proxying
+
+``proxies`` :
+  Define one or more proxies you wish to use, see `httpx proxies`_.
+  If there are more than one proxy for one protocol (http, https),
+  requests to the engines are distributed in a round-robin fashion.
+
+``source_ips`` :
+  If you use multiple network interfaces, define from which IP the requests must
+  be made. Example:
+
+  * ``0.0.0.0`` any local IPv4 address.
+  * ``::`` any local IPv6 address.
+  * ``192.168.0.1``
+  * ``[ 192.168.0.1, 192.168.0.2 ]`` these two specific IP addresses
+  * ``fe80::60a2:1691:e5a2:ee1f``
+  * ``fe80::60a2:1691:e5a2:ee1f/126`` all IP addresses in this network.
+  * ``[ 192.168.0.1, fe80::/126 ]``
+
+``retries`` :
+  Number of retry in case of an HTTP error.  On each retry, SearXNG uses an
+  different proxy and source ip.
+
+``enable_http2`` :
+  Enable by default. Set to ``false`` to disable HTTP/2.
+
+.. _httpx verification defaults: https://www.python-httpx.org/advanced/#changing-the-verification-defaults
+.. _httpx ssl configuration: https://www.python-httpx.org/compatibility/#ssl-configuration
+
+``verify``: : ``$SSL_CERT_FILE``, ``$SSL_CERT_DIR``
+  Allow to specify a path to certificate.
+  see `httpx verification defaults`_.
+
+  In addition to ``verify``, SearXNG supports the ``$SSL_CERT_FILE`` (for a file) and
+  ``$SSL_CERT_DIR`` (for a directory) OpenSSL variables.
+  see `httpx ssl configuration`_.
+
+``max_redirects`` :
+  30 by default. Maximum redirect before it is an error.
+
+``using_tor_proxy`` :
+  Using tor proxy (``true``) or not (``false``) for all engines.  The default is
+  ``false`` and can be overwritten in the :ref:`settings engine`
+
+

docs/admin/settings/settings_plugins.rst

@@ -0,0 +1,67 @@
+.. _settings plugins:
+
+=======
+Plugins
+=======
+
+.. sidebar:: Further reading ..
+
+   - :ref:`plugins admin`
+   - :ref:`dev plugin`
+   - :ref:`builtin plugins`
+
+
+The built-in plugins can be activated or deactivated via the settings
+(:ref:`settings enabled_plugins`) and external plugins can be integrated into
+SearXNG (:ref:`settings external_plugins`).
+
+
+.. _settings enabled_plugins:
+
+``enabled_plugins:`` (internal)
+===============================
+
+In :ref:`plugins admin` you find a complete list of all plugins, the default
+configuration looks like:
+
+.. code:: yaml
+
+   enabled_plugins:
+     - 'Basic Calculator'
+     - 'Hash plugin'
+     - 'Self Information'
+     - 'Tracker URL remover'
+     - 'Unit converter plugin'
+     - 'Ahmia blacklist'
+
+
+.. _settings external_plugins:
+
+``plugins:`` (external)
+=======================
+
+SearXNG supports *external plugins* / there is no need to install one, SearXNG
+runs out of the box.  But to demonstrate; in the example below we install the
+SearXNG plugins from *The Green Web Foundation* `[ref]
+<https://www.thegreenwebfoundation.org/news/searching-the-green-web-with-searx/>`__:
+
+.. code:: bash
+
+   $ sudo utils/searxng.sh instance cmd bash -c
+   (searxng-pyenv)$ pip install git+https://github.com/return42/tgwf-searx-plugins
+
+In the :ref:`settings.yml` activate the ``plugins:`` section and add module
+``only_show_green_results`` from ``tgwf-searx-plugins``.
+
+.. code:: yaml
+
+   plugins:
+     - only_show_green_results
+     # - mypackage.mymodule.MyPlugin
+     # - mypackage.mymodule.MyOtherPlugin
+
+.. hint::
+
+   ``only_show_green_results`` is an old plugin that was still implemented in
+   the old style.  There is a legacy treatment for backward compatibility, but
+   new plugins should be implemented as a :py:obj:`searx.plugins.Plugin` class.

docs/admin/settings/settings_redis.rst

@@ -0,0 +1,49 @@
+.. _settings redis:
+
+==========
+``redis:``
+==========
+
+.. _Redis.from_url(url): https://redis-py.readthedocs.io/en/stable/connections.html#redis.client.Redis.from_url
+
+A redis DB can be connected by an URL, in :py:obj:`searx.redisdb` you
+will find a description to test your redis connection in SearXNG.  When using
+sockets, don't forget to check the access rights on the socket::
+
+  ls -la /usr/local/searxng-redis/run/redis.sock
+  srwxrwx--- 1 searxng-redis searxng-redis ... /usr/local/searxng-redis/run/redis.sock
+
+In this example read/write access is given to the *searxng-redis* group.  To get
+access rights to redis instance (the socket), your SearXNG (or even your
+developer) account needs to be added to the *searxng-redis* group.
+
+``url`` : ``$SEARXNG_REDIS_URL``
+  URL to connect redis database, see `Redis.from_url(url)`_ & :ref:`redis db`::
+
+    redis://[[username]:[password]]@localhost:6379/0
+    rediss://[[username]:[password]]@localhost:6379/0
+    unix://[[username]:[password]]@/path/to/socket.sock?db=0
+
+.. _Redis Developer Notes:
+
+Redis Developer Notes
+=====================
+
+To set up a local redis instance, first set the socket path of the Redis DB
+in your YAML setting:
+
+.. code:: yaml
+
+   redis:
+     url: unix:///usr/local/searxng-redis/run/redis.sock?db=0
+
+Then use the following commands to install the redis instance (:ref:`manage
+redis.help`):
+
+.. code:: sh
+
+   $ ./manage redis.build
+   $ sudo -H ./manage redis.install
+   $ sudo -H ./manage redis.addgrp "${USER}"
+   # don't forget to logout & login to get member of group
+

docs/admin/settings/settings_search.rst

@@ -0,0 +1,109 @@
+.. _settings search:
+
+===========
+``search:``
+===========
+
+.. code:: yaml
+
+   search:
+     safe_search: 0
+     autocomplete: ""
+     favicon_resolver: ""
+     default_lang: ""
+     ban_time_on_fail: 5
+     max_ban_time_on_fail: 120
+     suspended_times:
+       SearxEngineAccessDenied: 86400
+       SearxEngineCaptcha: 86400
+       SearxEngineTooManyRequests: 3600
+       cf_SearxEngineCaptcha: 1296000
+       cf_SearxEngineAccessDenied: 86400
+       recaptcha_SearxEngineCaptcha: 604800
+     formats:
+       - html
+
+``safe_search``:
+  Filter results.
+
+  - ``0``: None
+  - ``1``: Moderate
+  - ``2``: Strict
+
+``autocomplete``:
+  Existing autocomplete backends, leave blank to turn it off.
+
+  - ``baidu```
+  - ``brave```
+  - ``dbpedia```
+  - ``duckduckgo```
+  - ``google```
+  - ``mwmbl```
+  - ``qwant```
+  - ``seznam```
+  - ``startpage```
+  - ``stract```
+  - ``swisscows```
+  - ``wikipedia```
+  - ``yandex```
+
+``favicon_resolver``:
+  To activate favicons in SearXNG's result list select a default
+  favicon-resolver, leave blank to turn off the feature.  Don't activate the
+  favicons before reading the :ref:`Favicons documentation <favicons>`.
+
+``default_lang``:
+  Default search language - leave blank to detect from browser information or
+  use codes from :origin:`searx/languages.py`.
+
+``languages``:
+  List of available languages - leave unset to use all codes from
+  :origin:`searx/languages.py`.  Otherwise list codes of available languages.
+  The ``all`` value is shown as the ``Default language`` in the user interface
+  (in most cases, it is meant to send the query without a language parameter ;
+  in some cases, it means the English language) Example:
+
+  .. code:: yaml
+
+     languages:
+       - all
+       - en
+       - en-US
+       - de
+       - it-IT
+       - fr
+       - fr-BE
+
+``ban_time_on_fail``:
+  Ban time in seconds after engine errors.
+
+``max_ban_time_on_fail``:
+  Max ban time in seconds after engine errors.
+
+``suspended_times``:
+  Engine suspension time after error (in seconds; set to 0 to disable)
+
+  ``SearxEngineAccessDenied``: 86400
+    For error "Access denied" and "HTTP error [402, 403]"
+
+  ``SearxEngineCaptcha``: 86400
+    For error "CAPTCHA"
+
+  ``SearxEngineTooManyRequests``: 3600
+    For error "Too many request" and "HTTP error 429"
+
+  Cloudflare CAPTCHA:
+     - ``cf_SearxEngineCaptcha``: 1296000
+     - ``cf_SearxEngineAccessDenied``: 86400
+
+  Google CAPTCHA:
+    - ``recaptcha_SearxEngineCaptcha``: 604800
+
+``formats``:
+  Result formats available from web, remove format to deny access (use lower
+  case).
+
+  - ``html``
+  - ``csv``
+  - ``json``
+  - ``rss``

docs/admin/settings/settings_server.rst

@@ -0,0 +1,57 @@
+.. _settings server:
+
+===========
+``server:``
+===========
+
+.. code:: yaml
+
+   server:
+       base_url: http://example.org/location  # change this!
+       port: 8888
+       bind_address: "127.0.0.1"
+       secret_key: "ultrasecretkey"           # change this!
+       limiter: false
+       public_instance: false
+       image_proxy: false
+       default_http_headers:
+         X-Content-Type-Options : nosniff
+         X-Download-Options : noopen
+         X-Robots-Tag : noindex, nofollow
+         Referrer-Policy : no-referrer
+
+``base_url`` : ``$SEARXNG_URL``
+  The base URL where SearXNG is deployed.  Used to create correct inbound links.
+
+``port`` & ``bind_address``: ``$SEARXNG_PORT`` & ``$SEARXNG_BIND_ADDRESS``
+  Port number and *bind address* of the SearXNG web application if you run it
+  directly using ``python searx/webapp.py``.  Doesn't apply to a SearXNG
+  services running behind a proxy and using socket communications.
+
+``secret_key`` : ``$SEARXNG_SECRET``
+  Used for cryptography purpose.
+
+``limiter`` :  ``$SEARXNG_LIMITER``
+  Rate limit the number of request on the instance, block some bots.  The
+  :ref:`limiter` requires a :ref:`settings redis` database.
+
+.. _public_instance:
+
+``public_instance`` :  ``$SEARXNG_PUBLIC_INSTANCE``
+
+  Setting that allows to enable features specifically for public instances (not
+  needed for local usage).  By set to ``true`` the following features are
+  activated:
+
+  - :py:obj:`searx.botdetection.link_token` in the :ref:`limiter`
+
+.. _image_proxy:
+
+``image_proxy`` : ``$SEARXNG_IMAGE_PROXY``
+  Allow your instance of SearXNG of being able to proxy images.  Uses memory space.
+
+.. _HTTP headers: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers
+
+``default_http_headers`` :
+  Set additional HTTP headers, see `#755 <https://github.com/searx/searx/issues/715>`__
+

docs/admin/settings/settings_ui.rst

@@ -0,0 +1,74 @@
+.. _settings ui:
+
+=======
+``ui:``
+=======
+
+.. _cache busting:
+   https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#caching_static_assets_with_cache_busting
+
+.. code:: yaml
+
+   ui:
+     static_use_hash: false
+     default_locale: ""
+     query_in_title: false
+     infinite_scroll: false
+     center_alignment: false
+     cache_url: https://web.archive.org/web/
+     default_theme: simple
+     theme_args:
+       simple_style: auto
+     search_on_category_select: true
+     hotkeys: default
+     url_formatting: pretty
+
+.. _static_use_hash:
+
+``static_use_hash`` : ``$SEARXNG_STATIC_USE_HASH``
+  Enables `cache busting`_ of static files.
+
+``default_locale`` :
+  SearXNG interface language.  If blank, the locale is detected by using the
+  browser language.  If it doesn't work, or you are deploying a language
+  specific instance of searx, a locale can be defined using an ISO language
+  code, like ``fr``, ``en``, ``de``.
+
+``query_in_title`` :
+  When true, the result page's titles contains the query it decreases the
+  privacy, since the browser can records the page titles.
+
+``infinite_scroll``:
+  When true, automatically loads the next page when scrolling to bottom of the current page.
+
+``center_alignment`` : default ``false``
+  When enabled, the results are centered instead of being in the left (or RTL)
+  side of the screen.  This setting only affects the *desktop layout*
+  (:origin:`min-width: @tablet <searx/static/themes/simple/src/less/definitions.less>`)
+
+.. cache_url:
+
+``cache_url`` : ``https://web.archive.org/web/``
+  URL prefix of the internet archive or cache, don't forget trailing slash (if
+  needed).  The default is https://web.archive.org/web/ alternatives are:
+
+  - https://webcache.googleusercontent.com/search?q=cache:
+  - https://archive.today/
+
+``default_theme`` :
+  Name of the theme you want to use by default on your SearXNG instance.
+
+``theme_args.simple_style``:
+  Style of simple theme: ``auto``, ``light``, ``dark``, ``black``
+
+``results_on_new_tab``:
+  Open result links in a new tab by default.
+
+``search_on_category_select``:
+  Perform search immediately if a category selected. Disable to select multiple categories.
+
+``hotkeys``:
+  Hotkeys to use in the search interface: ``default``, ``vim`` (Vim-like).
+
+``url_formatting``:
+  Formatting type to use for result URLs: ``pretty``, ``full`` or ``host``.

docs/admin/update-searxng.rst

@@ -0,0 +1,138 @@
+.. _searxng maintenance:
+
+===================
+SearXNG maintenance
+===================
+
+.. sidebar:: further read
+
+   - :ref:`toolboxing`
+   - :ref:`uWSGI maintenance`
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. _update searxng:
+
+How to update
+=============
+
+How to update depends on the :ref:`installation` method.  If you have used the
+:ref:`installation scripts`, use the ``update`` command from the :ref:`searxng.sh`
+script.
+
+.. code:: sh
+
+    sudo -H ./utils/searxng.sh instance update
+
+.. _inspect searxng:
+
+How to inspect & debug
+======================
+
+How to debug depends on the :ref:`installation` method.  If you have used the
+:ref:`installation scripts`, use the ``inspect`` command from the :ref:`searxng.sh`
+script.
+
+.. code:: sh
+
+    sudo -H ./utils/searxng.sh instance inspect
+
+.. _migrate and stay tuned:
+
+Migrate and stay tuned!
+=======================
+
+.. sidebar:: info
+
+   - :pull:`1332`
+   - :pull:`456`
+   - :pull:`A comment about rolling release <446#issuecomment-954730358>`
+
+SearXNG is a *rolling release*; each commit to the master branch is a release.
+SearXNG is growing rapidly, the services and opportunities are change every now
+and then, to name just a few:
+
+- Bot protection has been switched from filtron to SearXNG's :ref:`limiter
+  <limiter>`, this requires a :ref:`Redis <settings redis>` database.
+
+- The image proxy morty is no longer needed, it has been replaced by the
+  :ref:`image proxy <image_proxy>` from SearXNG.
+
+- To save bandwidth :ref:`cache busting <static_use_hash>` has been implemented.
+  To get in use, the ``static-expires`` needs to be set in the :ref:`uwsgi
+  setup`.
+
+To stay tuned and get in use of the new features, instance maintainers have to
+update the SearXNG code regularly (see :ref:`update searxng`).  As the above
+examples show, this is not always enough, sometimes services have to be set up
+or reconfigured and sometimes services that are no longer needed should be
+uninstalled.
+
+.. hint::
+
+   First of all: SearXNG is installed by the script :ref:`searxng.sh`.  If you
+   have old filtron, morty or searx setup you should consider complete
+   uninstall/reinstall.
+
+Here you will find a list of changes that affect the infrastructure.  Please
+check to what extent it is necessary to update your installations:
+
+:pull:`1595`: ``[fix] uWSGI: increase buffer-size``
+  Re-install uWSGI (:ref:`searxng.sh`) or fix your uWSGI ``searxng.ini``
+  file manually.
+
+
+remove obsolete services
+------------------------
+
+If your searx instance was installed *"Step by step"* or by the *"Installation
+scripts"*, you need to undo the installation procedure completely.  If you have
+morty & filtron installed, it is recommended to uninstall these services also.
+In case of scripts, to uninstall use the scripts from the origin you installed
+searx from or try::
+
+  $ sudo -H ./utils/filtron.sh remove all
+  $ sudo -H ./utils/morty.sh   remove all
+  $ sudo -H ./utils/searx.sh   remove all
+
+.. hint::
+
+   If you are migrate from searx take into account that the ``.config.sh`` is no
+   longer used.
+
+If you upgrade from searx or from before :pull:`1332` has been merged and you
+have filtron and/or morty installed, don't forget to remove HTTP sites.
+
+Apache::
+
+  $ sudo -H ./utils/filtron.sh apache remove
+  $ sudo -H ./utils/morty.sh apache remove
+
+nginx::
+
+  $ sudo -H ./utils/filtron.sh nginx remove
+  $ sudo -H ./utils/morty.sh nginx remove
+
+
+
+Check after Installation
+------------------------
+
+Once you have done your installation, you can run a SearXNG *check* procedure,
+to see if there are some left overs.  In this example there exists a *old*
+``/etc/searx/settings.yml``::
+
+   $ sudo -H ./utils/searxng.sh instance check
+
+   SearXNG checks
+   --------------
+   ERROR: settings.yml in /etc/searx/ is deprecated, move file to folder /etc/searxng/
+   INFO:  [OK] (old) account 'searx' does not exists
+   INFO:  [OK] (old) account 'filtron' does not exists
+   INFO:  [OK] (old) account 'morty' does not exists
+   ...
+   INFO    searx.redisdb                 : connecting to Redis db=0 path='/usr/local/searxng-redis/run/redis.sock'
+   INFO    searx.redisdb                 : connected to Redis

docs/build-templates/searxng.rst

@@ -0,0 +1,203 @@
+.. template evaluated by: ./utils/searxng.sh searxng.doc.rst
+.. hint: all dollar-names are variables, dollar sign itself is quoted by: \\$
+
+.. START distro-packages
+
+.. tabs::
+
+  .. group-tab:: Ubuntu / debian
+
+    .. code-block:: sh
+
+      $ sudo -H apt-get install -y \\
+${debian}
+
+  .. group-tab:: Arch Linux
+
+    .. code-block:: sh
+
+      $ sudo -H pacman -S --noconfirm \\
+${arch}
+
+  .. group-tab::  Fedora / RHEL
+
+    .. code-block:: sh
+
+      $ sudo -H dnf install -y \\
+${fedora}
+
+.. END distro-packages
+
+.. START build-packages
+
+.. tabs::
+
+  .. group-tab:: Ubuntu / debian
+
+    .. code-block:: sh
+
+      $ sudo -H apt-get install -y \\
+${debian_build}
+
+  .. group-tab:: Arch Linux
+
+    .. code-block:: sh
+
+      $ sudo -H pacman -S --noconfirm \\
+${arch_build}
+
+  .. group-tab::  Fedora / RHEL
+
+    .. code-block:: sh
+
+      $ sudo -H dnf install -y \\
+${fedora_build}
+
+.. END build-packages
+
+.. START create user
+
+.. tabs::
+
+  .. group-tab:: bash
+
+    .. code-block:: sh
+
+      $ sudo -H useradd --shell /bin/bash --system \\
+          --home-dir \"$SERVICE_HOME\" \\
+          --comment 'Privacy-respecting metasearch engine' \\
+          $SERVICE_USER
+
+      $ sudo -H mkdir \"$SERVICE_HOME\"
+      $ sudo -H chown -R \"$SERVICE_GROUP:$SERVICE_GROUP\" \"$SERVICE_HOME\"
+
+.. END create user
+
+.. START clone searxng
+
+.. tabs::
+
+  .. group-tab:: bash
+
+    .. code-block:: sh
+
+       $ sudo -H -u ${SERVICE_USER} -i
+       (${SERVICE_USER})$ git clone \"$GIT_URL\" \\
+                          \"$SEARXNG_SRC\"
+
+.. END clone searxng
+
+.. START create virtualenv
+
+.. tabs::
+
+  .. group-tab:: bash
+
+    .. code-block:: sh
+
+       (${SERVICE_USER})$ python3 -m venv \"${SEARXNG_PYENV}\"
+       (${SERVICE_USER})$ echo \". ${SEARXNG_PYENV}/bin/activate\" \\
+                          >>  \"$SERVICE_HOME/.profile\"
+
+.. END create virtualenv
+
+.. START manage.sh update_packages
+
+.. tabs::
+
+  .. group-tab:: bash
+
+    .. code-block:: sh
+
+       $ sudo -H -u ${SERVICE_USER} -i
+
+       (${SERVICE_USER})$ command -v python && python --version
+       $SEARXNG_PYENV/bin/python
+       Python 3.11.10
+
+       # update pip's boilerplate ..
+       pip install -U pip
+       pip install -U setuptools
+       pip install -U wheel
+       pip install -U pyyaml
+
+       # jump to SearXNG's working tree and install SearXNG into virtualenv
+       (${SERVICE_USER})$ cd \"$SEARXNG_SRC\"
+       (${SERVICE_USER})$ pip install --use-pep517 --no-build-isolation -e .
+
+
+.. END manage.sh update_packages
+
+.. START searxng config
+
+.. tabs::
+
+  .. group-tab:: Use default settings
+
+    .. code-block:: sh
+
+       $ sudo -H mkdir -p \"$(dirname ${SEARXNG_SETTINGS_PATH})\"
+       $ sudo -H cp \"$SEARXNG_SRC/utils/templates/etc/searxng/settings.yml\" \\
+                    \"${SEARXNG_SETTINGS_PATH}\"
+
+  .. group-tab:: minimal setup
+
+    .. code-block:: sh
+
+       $ sudo -H sed -i -e \"s/ultrasecretkey/\$(openssl rand -hex 16)/g\" \\
+                     \"$SEARXNG_SETTINGS_PATH\"
+
+.. END searxng config
+
+.. START check searxng installation
+
+.. tabs::
+
+  .. group-tab:: bash
+
+    .. code-block:: sh
+
+       # enable debug ..
+       $ sudo -H sed -i -e \"s/debug : False/debug : True/g\" \"$SEARXNG_SETTINGS_PATH\"
+
+       # start webapp
+       $ sudo -H -u ${SERVICE_USER} -i
+       (${SERVICE_USER})$ cd ${SEARXNG_SRC}
+       (${SERVICE_USER})$ export SEARXNG_SETTINGS_PATH=\"${SEARXNG_SETTINGS_PATH}\"
+       (${SERVICE_USER})$ python searx/webapp.py
+
+       # disable debug
+       $ sudo -H sed -i -e \"s/debug : True/debug : False/g\" \"$SEARXNG_SETTINGS_PATH\"
+
+Open WEB browser and visit http://$SEARXNG_INTERNAL_HTTP .  If you are inside a
+container or in a script, test with curl:
+
+.. tabs::
+
+  .. group-tab:: WEB browser
+
+    .. code-block:: sh
+
+       $ xdg-open http://$SEARXNG_INTERNAL_HTTP
+
+  .. group-tab:: curl
+
+    .. code-block:: none
+
+       $ curl --location --verbose --head --insecure $SEARXNG_INTERNAL_HTTP
+
+       *   Trying 127.0.0.1:8888...
+       * TCP_NODELAY set
+       * Connected to 127.0.0.1 (127.0.0.1) port 8888 (#0)
+       > HEAD / HTTP/1.1
+       > Host: 127.0.0.1:8888
+       > User-Agent: curl/7.68.0
+       > Accept: */*
+       >
+       * Mark bundle as not supporting multiuse
+       * HTTP 1.0, assume close after body
+       < HTTP/1.0 200 OK
+       HTTP/1.0 200 OK
+       ...
+
+.. END check searxng installation

docs/conf.py

@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+import  sys, os
+from pathlib import Path
+from pallets_sphinx_themes import ProjectLink
+
+from searx import get_setting
+from searx.version import VERSION_STRING, GIT_URL, GIT_BRANCH
+
+# Project --------------------------------------------------------------
+
+project = 'SearXNG'
+copyright = 'SearXNG team'
+author = 'SearXNG team'
+release, version = VERSION_STRING, VERSION_STRING
+SEARXNG_URL = get_setting('server.base_url') or 'https://example.org/searxng'
+ISSUE_URL = get_setting('brand.issue_url')
+DOCS_URL = get_setting('brand.docs_url')
+PUBLIC_INSTANCES = get_setting('brand.public_instances')
+PRIVACYPOLICY_URL = get_setting('general.privacypolicy_url')
+CONTACT_URL = get_setting('general.contact_url')
+WIKI_URL = get_setting('brand.wiki_url')
+
+SOURCEDIR = Path(__file__).parent.parent / "searx"
+os.environ['SOURCEDIR'] = str(SOURCEDIR)
+
+# hint: sphinx.ext.viewcode won't highlight when 'highlight_language' [1] is set
+#       to string 'none' [2]
+#
+# [1] https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html
+# [2] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-highlight_language
+
+highlight_language = 'default'
+
+# General --------------------------------------------------------------
+
+master_doc = "index"
+source_suffix = '.rst'
+numfig = True
+
+exclude_patterns = ['build-templates/*.rst', 'user/*.md']
+
+import searx.engines
+import searx.plugins
+import searx.webutils
+
+# import searx.webapp is needed to init the engines & plugins, to init a
+# (empty) secret_key is needed.
+searx.settings['server']['secret_key'] = ''
+import searx.webapp
+
+searx.engines.load_engines(searx.settings['engines'])
+
+jinja_contexts = {
+    'searx': {
+        'engines': searx.engines.engines,
+        'plugins': searx.plugins.STORAGE,
+        'version': {
+            'node': os.getenv('NODE_MINIMUM_VERSION')
+        },
+        'enabled_engine_count': sum(not x.disabled for x in searx.engines.engines.values()),
+        'categories': searx.engines.categories,
+        'categories_as_tabs': {c: searx.engines.categories[c] for c in searx.settings['categories_as_tabs']},
+    },
+}
+jinja_filters = {
+    'group_engines_in_tab': searx.webutils.group_engines_in_tab,
+}
+
+# Let the Jinja template in configured_engines.rst access documented_modules
+# to automatically link documentation for modules if it exists.
+def setup(app):
+    ENGINES_DOCNAME = 'user/configured_engines'
+
+    def before_read_docs(app, env, docnames):
+        assert ENGINES_DOCNAME in docnames
+        docnames.remove(ENGINES_DOCNAME)
+        docnames.append(ENGINES_DOCNAME)
+        # configured_engines must come last so that sphinx already has
+        # discovered the python module documentations
+
+    def source_read(app, docname, source):
+        if docname == ENGINES_DOCNAME:
+            jinja_contexts['searx']['documented_modules'] = app.env.domains['py'].modules
+
+    app.connect('env-before-read-docs', before_read_docs)
+    app.connect('source-read', source_read)
+
+# usage::   lorem :patch:`f373169` ipsum
+extlinks = {}
+
+# upstream links
+extlinks['wiki'] = ('https://github.com/searxng/searxng/wiki/%s', ' %s')
+extlinks['pull'] = ('https://github.com/searxng/searxng/pull/%s', 'PR %s')
+extlinks['pull-searx'] = ('https://github.com/searx/searx/pull/%s', 'PR %s')
+
+# links to custom brand
+extlinks['origin'] = (GIT_URL + '/blob/' + GIT_BRANCH + '/%s', 'git://%s')
+extlinks['patch'] = (GIT_URL + '/commit/%s', '#%s')
+extlinks['docs'] = (DOCS_URL + '/%s', 'docs: %s')
+extlinks['pypi'] = ('https://pypi.org/project/%s', 'PyPi: %s')
+extlinks['man'] = ('https://manpages.debian.org/jump?q=%s', '%s')
+#extlinks['role'] = (
+#    'https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-%s', '')
+extlinks['duref'] = (
+    'https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#%s', '%s')
+extlinks['durole'] = (
+    'https://docutils.sourceforge.io/docs/ref/rst/roles.html#%s', '%s')
+extlinks['dudir'] =  (
+    'https://docutils.sourceforge.io/docs/ref/rst/directives.html#%s', '%s')
+extlinks['ctan'] =  (
+    'https://ctan.org/pkg/%s', 'CTAN: %s')
+
+extensions = [
+    'sphinx.ext.imgmath',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.viewcode',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "pallets_sphinx_themes",
+    "sphinx_issues", # https://github.com/sloria/sphinx-issues/blob/master/README.rst
+    "sphinx_jinja",  # https://github.com/tardyp/sphinx-jinja
+    "sphinxcontrib.programoutput",  # https://github.com/NextThought/sphinxcontrib-programoutput
+    'linuxdoc.kernel_include',  # Implementation of the 'kernel-include' reST-directive.
+    'linuxdoc.rstFlatTable',    # Implementation of the 'flat-table' reST-directive.
+    'linuxdoc.kfigure',         # Sphinx extension which implements scalable image handling.
+    "sphinx_tabs.tabs", # https://github.com/djungelorm/sphinx-tabs
+    'myst_parser',  # https://www.sphinx-doc.org/en/master/usage/markdown.html
+    'notfound.extension',  # https://github.com/readthedocs/sphinx-notfound-page
+]
+
+# autodoc_typehints = "description"
+autodoc_default_options = {
+    'member-order': 'bysource',
+}
+
+myst_enable_extensions = [
+  "replacements", "smartquotes"
+]
+
+suppress_warnings = ['myst.domains']
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "babel" : ("https://babel.readthedocs.io/en/latest/", None),
+    "flask": ("https://flask.palletsprojects.com/", None),
+    "flask_babel": ("https://python-babel.github.io/flask-babel/", None),
+    # "werkzeug": ("https://werkzeug.palletsprojects.com/", None),
+    "jinja": ("https://jinja.palletsprojects.com/", None),
+    "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
+    "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
+    "redis": ('https://redis.readthedocs.io/en/stable/', None),
+}
+
+issues_github_path = "searxng/searxng"
+
+# HTML -----------------------------------------------------------------
+
+# https://searxng.github.io/searxng --> '/searxng/'
+# https://docs.searxng.org --> '/'
+notfound_urls_prefix = '/'
+
+sys.path.append(os.path.abspath('_themes'))
+sys.path.insert(0, os.path.abspath("../utils/"))
+html_theme_path = ['_themes']
+html_theme = "searxng"
+
+# sphinx.ext.imgmath setup
+html_math_renderer = 'imgmath'
+imgmath_image_format = 'svg'
+imgmath_font_size = 14
+# sphinx.ext.imgmath setup END
+
+html_show_sphinx = False
+html_theme_options = {"index_sidebar_logo": True}
+html_context = {"project_links": [] }
+html_context["project_links"].append(ProjectLink("Source", GIT_URL + '/tree/' + GIT_BRANCH))
+
+if WIKI_URL:
+    html_context["project_links"].append(ProjectLink("Wiki", WIKI_URL))
+if PUBLIC_INSTANCES:
+    html_context["project_links"].append(ProjectLink("Public instances", PUBLIC_INSTANCES))
+if ISSUE_URL:
+    html_context["project_links"].append(ProjectLink("Issue Tracker", ISSUE_URL))
+if PRIVACYPOLICY_URL:
+    html_context["project_links"].append(ProjectLink("Privacy Policy", PRIVACYPOLICY_URL))
+if CONTACT_URL:
+    html_context["project_links"].append(ProjectLink("Contact", CONTACT_URL))
+
+html_sidebars = {
+    "**": [
+        "globaltoc.html",
+        "project.html",
+        "relations.html",
+        "searchbox.html",
+        "sourcelink.html"
+    ],
+}
+singlehtml_sidebars = {"index": ["project.html", "localtoc.html"]}
+html_logo = "../src/brand/searxng-wordmark.svg"
+html_title = "SearXNG Documentation ({})".format(VERSION_STRING)
+html_show_sourcelink = True
+
+# LaTeX ----------------------------------------------------------------
+
+latex_documents = [
+    (master_doc, "searxng-{}.tex".format(VERSION_STRING), html_title, author, "manual")
+]

docs/dev/answerers/builtins.rst

@@ -0,0 +1,11 @@
+.. _builtin answerers:
+
+==================
+Built-in Answerers
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   random
+   statistics

docs/dev/answerers/development.rst

@@ -0,0 +1,7 @@
+.. _dev answerers:
+
+====================
+Answerer Development
+====================
+
+.. automodule:: searx.answerers

docs/dev/answerers/index.rst

@@ -0,0 +1,9 @@
+=========
+Answerers
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   development
+   builtins

docs/dev/answerers/random.rst

@@ -0,0 +1,8 @@
+.. _answerer.random:
+
+======
+Random
+======
+
+.. autoclass:: searx.answerers.random.SXNGAnswerer
+   :members:

docs/dev/answerers/statistics.rst

@@ -0,0 +1,8 @@
+.. _answerer.statistics:
+
+==========
+Statistics
+==========
+
+.. autoclass:: searx.answerers.statistics.SXNGAnswerer
+   :members:

docs/dev/contribution_guide.rst

@@ -0,0 +1,190 @@
+.. _how to contribute:
+
+=================
+How to contribute
+=================
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+Prime directives: Privacy, Hackability
+======================================
+
+SearXNG has two prime directives, **privacy-by-design and hackability** .  The
+hackability comes in three levels:
+
+- support of search engines
+- plugins to alter search behaviour
+- hacking SearXNG itself
+
+Note the lack of "world domination" among the directives.  SearXNG has no
+intention of wide mass-adoption, rounded corners, etc.  The prime directive
+"privacy" deserves a separate chapter, as it's quite uncommon unfortunately.
+
+Privacy-by-design
+-----------------
+
+SearXNG was born out of the need for a **privacy-respecting** search tool which
+can be extended easily to maximize both, its search and its privacy protecting
+capabilities.
+
+A few widely used features work differently or turned off by default or not
+implemented at all **as a consequence of privacy-by-design**.
+
+If a feature reduces the privacy preserving aspects of searx, it should be
+switched off by default or should not implemented at all.  There are plenty of
+search engines already providing such features.  If a feature reduces the
+protection of searx, users must be informed about the effect of choosing to
+enable it.  Features that protect privacy but differ from the expectations of
+the user should also be explained.
+
+Also, if you think that something works weird with searx, it's might be because
+of the tool you use is designed in a way to interfere with the privacy respect.
+Submitting a bugreport to the vendor of the tool that misbehaves might be a good
+feedback to reconsider the disrespect to its customers (e.g. ``GET`` vs ``POST``
+requests in various browsers).
+
+Remember the other prime directive of SearXNG is to be hackable, so if the above
+privacy concerns do not fancy you, simply fork it.
+
+  *Happy hacking.*
+
+Code
+====
+
+.. _PEP8: https://www.python.org/dev/peps/pep-0008/
+.. _Conventional Commits: https://www.conventionalcommits.org/
+.. _Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages
+.. _Structural split of changes:
+    https://wiki.openstack.org/wiki/GitCommitMessages#Structural_split_of_changes
+.. _gitmoji: https://gitmoji.carloscuesta.me/
+.. _Semantic PR: https://github.com/zeke/semantic-pull-requests
+
+.. sidebar:: Create good commits!
+
+   - `Structural split of changes`_
+   - `Conventional Commits`_
+   - `Git Commit Good Practice`_
+   - some like to use: gitmoji_
+   - not yet active: `Semantic PR`_
+
+In order to submit a patch, please follow the steps below:
+
+- Follow coding conventions.
+
+  - PEP8_ standards apply, except the convention of line length
+  - Maximum line length is 120 characters
+
+- The cardinal rule for creating good commits is to ensure there is only one
+  *logical change* per commit / read `Structural split of changes`_
+
+- Check if your code breaks existing tests.  If so, update the tests or fix your
+  code.
+
+- If your code can be unit-tested, add unit tests.
+
+- Add yourself to the :origin:`AUTHORS.rst` file.
+
+- Choose meaningful commit messages, read `Conventional Commits`_
+
+  .. code::
+
+     <type>[optional scope]: <description>
+
+     [optional body]
+
+     [optional footer(s)]
+
+- Create a pull request.
+
+For more help on getting started with SearXNG development, see :ref:`devquickstart`.
+
+
+Translation
+===========
+
+Translation currently takes place on :ref:`weblate <translation>`.
+
+
+.. _contrib docs:
+
+Documentation
+=============
+
+.. _Sphinx: https://www.sphinx-doc.org
+.. _reST: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+
+.. sidebar:: The reST sources
+
+   has been moved from ``gh-branch`` into ``master`` (:origin:`docs`).
+
+The documentation is built using Sphinx_.  So in order to be able to generate
+the required files, you have to install it on your system.  Much easier, use
+our :ref:`makefile`.
+
+Here is an example which makes a complete rebuild:
+
+.. code:: sh
+
+   $ make docs.clean docs.html
+   ...
+   The HTML pages are in dist/docs.
+
+.. _make docs.live:
+
+live build
+----------
+
+.. _sphinx-autobuild:
+   https://github.com/executablebooks/sphinx-autobuild/blob/master/README.md
+
+.. sidebar:: docs.clean
+
+   It is recommended to assert a complete rebuild before deploying (use
+   ``docs.clean``).
+
+Live build is like WYSIWYG.  If you want to edit the documentation, its
+recommended to use.  The Makefile target ``docs.live`` builds the docs, opens
+URL in your favorite browser and rebuilds every time a reST file has been
+changed (:ref:`make docs.clean`).
+
+.. code:: sh
+
+   $ make docs.live
+   ...
+   The HTML pages are in dist/docs.
+   ... Serving on http://0.0.0.0:8000
+   ... Start watching changes
+
+Live builds are implemented by sphinx-autobuild_.  Use environment
+``$(SPHINXOPTS)`` to pass arguments to the sphinx-autobuild_ command.  Except
+option ``--host`` (which is always set to ``0.0.0.0``) you can pass any
+argument.  E.g to find and use a free port, use:
+
+.. code:: sh
+
+   $ SPHINXOPTS="--port 0" make docs.live
+   ...
+   ... Serving on http://0.0.0.0:50593
+   ...
+
+
+.. _deploy on github.io:
+
+deploy on github.io
+-------------------
+
+To deploy documentation at :docs:`github.io <.>` use Makefile target :ref:`make
+docs.gh-pages`, which builds the documentation and runs all the needed git add,
+commit and push:
+
+.. code:: sh
+
+   $ make docs.clean docs.gh-pages
+
+.. attention::
+
+   If you are working in your own brand, don't forget to adjust your
+   :ref:`settings brand`.

docs/dev/csv_table.txt

@@ -0,0 +1,6 @@
+stub col row 1, column, "loremLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
+eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
+voluptua."
+stub col row 1, "At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
+kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.", column
+stub col row 1, column, column

docs/dev/engines/demo/demo_offline.rst

@@ -0,0 +1,14 @@
+.. _demo offline engine:
+
+===================
+Demo Offline Engine
+===================
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. automodule:: searx.engines.demo_offline
+  :members:
+

docs/dev/engines/demo/demo_online.rst

@@ -0,0 +1,14 @@
+.. _demo online engine:
+
+==================
+Demo Online Engine
+==================
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. automodule:: searx.engines.demo_online
+  :members:
+

docs/dev/engines/engine_overview.rst

@@ -0,0 +1,254 @@
+.. _engines-dev:
+
+===============
+Engine Overview
+===============
+
+.. contents::
+   :depth: 3
+   :local:
+   :backlinks: entry
+
+.. _metasearch-engine: https://en.wikipedia.org/wiki/Metasearch_engine
+
+.. sidebar:: Further reading ..
+
+   - :ref:`configured engines`
+   - :ref:`settings engine`
+
+SearXNG is a metasearch-engine_, so it uses different search engines to provide
+better results.
+
+Because there is no general search API which could be used for every search
+engine, an adapter has to be built between SearXNG and the external search
+engines.  Adapters are stored under the folder :origin:`searx/engines`.
+
+.. _general engine configuration:
+
+General Engine Configuration
+============================
+
+It is required to tell SearXNG the type of results the engine provides. The
+arguments can be set in the engine file or in the settings file (normally
+``settings.yml``). The arguments in the settings file override the ones in the
+engine file.
+
+It does not matter if an option is stored in the engine file or in the settings.
+However, the standard way is the following:
+
+.. _engine file:
+
+Engine File
+-----------
+
+.. table:: Common options in the engine module
+   :width: 100%
+
+   ======================= =========== ========================================================
+   argument                type        information
+   ======================= =========== ========================================================
+   categories              list        categories, in which the engine is working
+   paging                  boolean     support multiple pages
+   time_range_support      boolean     support search time range
+   engine_type             str         - ``online`` :ref:`[ref] <online engines>` by
+                                         default, other possibles values are:
+                                       - ``offline`` :ref:`[ref] <offline engines>`
+                                       - ``online_dictionary`` :ref:`[ref] <online dictionary>`
+                                       - ``online_currency`` :ref:`[ref] <online currency>`
+                                       - ``online_url_search`` :ref:`[ref] <online url search>`
+   ======================= =========== ========================================================
+
+.. _engine settings:
+
+Engine ``settings.yml``
+-----------------------
+
+For a more  detailed description, see :ref:`settings engine` in the :ref:`settings.yml`.
+
+.. table:: Common options in the engine setup (``settings.yml``)
+   :width: 100%
+
+   ======================= =========== ==================================================
+   argument                type        information
+   ======================= =========== ==================================================
+   name                    string      name of search-engine
+   engine                  string      name of searxng-engine (file name without ``.py``)
+   enable_http             bool        enable HTTP (by default only HTTPS is enabled).
+   shortcut                string      shortcut of search-engine
+   timeout                 string      specific timeout for search-engine
+   display_error_messages  boolean     display error messages on the web UI
+   proxies                 dict        set proxies for a specific engine
+                                       (e.g. ``proxies : {http: socks5://proxy:port,
+                                       https: socks5://proxy:port}``)
+   ======================= =========== ==================================================
+
+.. _engine overrides:
+
+Overrides
+---------
+
+A few of the options have default values in the namespace of the engine's python
+module, but are often overwritten by the settings.  If ``None`` is assigned to an
+option in the engine file, it has to be redefined in the settings, otherwise
+SearXNG will not start with that engine (global names with a leading underline can
+be ``None``).
+
+Here is an very simple example of the global names in the namespace of engine's
+module:
+
+.. code:: python
+
+   # engine dependent config
+   categories = ['general']
+   paging = True
+   _non_overwritten_global = 'foo'
+
+
+.. table:: The naming of overrides is arbitrary / recommended overrides are:
+   :width: 100%
+
+   ======================= =========== ===========================================
+   argument                type        information
+   ======================= =========== ===========================================
+   base_url                string      base-url, can be overwritten to use same
+                                       engine on other URL
+   number_of_results       int         maximum number of results per request
+   language                string      ISO code of language and country like en_US
+   api_key                 string      api-key if required by engine
+   ======================= =========== ===========================================
+
+.. _engine request:
+
+Making a Request
+================
+
+To perform a search an URL have to be specified.  In addition to specifying an
+URL, arguments can be passed to the query.
+
+.. _engine request arguments:
+
+Passed Arguments (request)
+--------------------------
+
+These arguments can be used to construct the search query.  Furthermore,
+parameters with default value can be redefined for special purposes.
+
+.. _engine request online:
+
+.. table:: If the ``engine_type`` is :py:obj:`online
+           <searx.search.processors.online.OnlineProcessor.get_params>`
+   :width: 100%
+
+   ====================== ============== ========================================================================
+   argument               type           default-value, information
+   ====================== ============== ========================================================================
+   url                    str            ``''``
+   method                 str            ``'GET'``
+   headers                set            ``{}``
+   data                   set            ``{}``
+   cookies                set            ``{}``
+   verify                 bool           ``True``
+   headers.User-Agent     str            a random User-Agent
+   category               str            current category, like ``'general'``
+   safesearch             int            ``0``, between ``0`` and ``2`` (normal, moderate, strict)
+   time_range             Optional[str]  ``None``, can be ``day``, ``week``, ``month``, ``year``
+   pageno                 int            current pagenumber
+   searxng_locale         str            SearXNG's locale selected by user.  Specific language code like
+                                         ``'en'``, ``'en-US'``, or ``'all'`` if unspecified.
+   ====================== ============== ========================================================================
+
+
+.. _engine request online_dictionary:
+
+.. table:: If the ``engine_type`` is :py:obj:`online_dictionary
+           <searx.search.processors.online_dictionary.OnlineDictionaryProcessor.get_params>`,
+           in addition to the :ref:`online <engine request online>` arguments:
+   :width: 100%
+
+   ====================== ============== ========================================================================
+   argument               type           default-value, information
+   ====================== ============== ========================================================================
+   from_lang              str            specific language code like ``'en_US'``
+   to_lang                str            specific language code like ``'en_US'``
+   query                  str            the text query without the languages
+   ====================== ============== ========================================================================
+
+.. _engine request online_currency:
+
+.. table:: If the ``engine_type`` is :py:obj:`online_currency
+           <searx.search.processors.online_currency.OnlineCurrencyProcessor.get_params>`,
+           in addition to the :ref:`online <engine request online>` arguments:
+   :width: 100%
+
+   ====================== ============== ========================================================================
+   argument               type           default-value, information
+   ====================== ============== ========================================================================
+   amount                 float          the amount to convert
+   from                   str            ISO 4217 code
+   to                     str            ISO 4217 code
+   from_name              str            currency name
+   to_name                str            currency name
+   ====================== ============== ========================================================================
+
+.. _engine request online_url_search:
+
+.. table:: If the ``engine_type`` is :py:obj:`online_url_search
+           <searx.search.processors.online_url_search.OnlineUrlSearchProcessor.get_params>`,
+           in addition to the :ref:`online <engine request online>` arguments:
+   :width: 100%
+
+   ====================== ============== ========================================================================
+   argument               type           default-value, information
+   ====================== ============== ========================================================================
+   search_url             dict           URLs from the search query:
+
+                                         .. code:: python
+
+                                            {
+                                              'http': str,
+                                              'ftp': str,
+                                              'data:image': str
+                                            }
+   ====================== ============== ========================================================================
+
+Specify Request
+---------------
+
+The function :py:func:`def request(query, params):
+<searx.engines.demo_online.request>` always returns the ``params`` variable, the
+following parameters can be used to specify a search request:
+
+.. table::
+   :width: 100%
+
+   =================== =========== ==========================================================================
+   argument            type        information
+   =================== =========== ==========================================================================
+   url                 str         requested url
+   method              str         HTTP request method
+   headers             set         HTTP header information
+   data                set         HTTP data information
+   cookies             set         HTTP cookies
+   verify              bool        Performing SSL-Validity check
+   allow_redirects     bool        Follow redirects
+   max_redirects       int         maximum redirects, hard limit
+   soft_max_redirects  int         maximum redirects, soft limit. Record an error but don't stop the engine
+   raise_for_httperror bool        True by default: raise an exception if the HTTP code of response is >= 300
+   =================== =========== ==========================================================================
+
+
+Making a Response
+=================
+
+In the ``response`` function of the engine, the HTTP response (``resp``) is
+parsed and a list of results is returned.
+
+A engine can append result-items of different media-types and different
+result-types to the result list.  The list of the result items is render to HTML
+by templates.  For more details read section:
+
+- :ref:`simple theme templates`
+- :ref:`result types`
+
+
+

docs/dev/engines/enginelib.rst

@@ -0,0 +1,22 @@
+.. _searx.enginelib:
+
+==============
+Engine Library
+==============
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. automodule:: searx.enginelib
+  :members:
+
+.. _searx.enginelib.traits:
+
+
+Engine traits
+=============
+
+.. automodule:: searx.enginelib.traits
+  :members:

docs/dev/engines/engines.rst

@@ -0,0 +1,9 @@
+.. _searx.engines loader:
+
+========================
+SearXNG's engines loader
+========================
+
+.. automodule:: searx.engines
+  :members:
+

docs/dev/engines/index.rst

@@ -0,0 +1,116 @@
+.. _engine implementations:
+
+======================
+Engine Implementations
+======================
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+
+.. toctree::
+   :caption: Framework Components
+   :maxdepth: 2
+
+   enginelib
+   engines
+   engine_overview
+
+
+ResultList and engines
+======================
+
+.. autoclass:: searx.result_types.ResultList
+
+.. autoclass:: searx.result_types.EngineResults
+
+
+Engine Types
+============
+
+The :py:obj:`engine_type <searx.enginelib.Engine.engine_type>` of an engine
+determines which :ref:`search processor <searx.search.processors>` is used by
+the engine.
+
+In this section a list of the engines that are documented is given, a complete
+list of the engines can be found in the source under: :origin:`searx/engines`.
+
+.. _online engines:
+
+Online Engines
+--------------
+
+.. sidebar:: info
+
+   - :py:obj:`processors.online <searx.search.processors.online>`
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   demo/demo_online
+   xpath
+   mediawiki
+   json_engine
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   online/*
+
+.. _offline engines:
+
+Offline Engines
+---------------
+
+.. sidebar:: info
+
+   - :py:obj:`processors.offline <searx.search.processors.offline>`
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   offline_concept
+   demo/demo_offline
+   offline/*
+
+.. _online url search:
+
+Online URL Search
+-----------------
+
+.. sidebar:: info
+
+   - :py:obj:`processors.online_url_search <searx.search.processors.online_url_search>`
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   online_url_search/*
+
+.. _online currency:
+
+Online Currency
+---------------
+
+.. sidebar:: info
+
+   - :py:obj:`processors.online_currency <searx.search.processors.online_currency>`
+
+*no engine of this type is documented yet / coming soon*
+
+.. _online dictionary:
+
+Online Dictionary
+-----------------
+
+.. sidebar:: info
+
+   - :py:obj:`processors.online_dictionary <searx.search.processors.online_dictionary>`
+
+*no engine of this type is documented yet / coming soon*

docs/dev/engines/json_engine.rst

@@ -0,0 +1,13 @@
+.. _json_engine engine:
+
+============
+JSON Engine
+============
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. automodule:: searx.engines.json_engine
+  :members:

docs/dev/engines/mediawiki.rst

@@ -0,0 +1,13 @@
+.. _mediawiki engine:
+
+================
+MediaWiki Engine
+================
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. automodule:: searx.engines.mediawiki
+  :members:

docs/dev/engines/offline/command-line-engines.rst

@@ -0,0 +1,23 @@
+.. _engine command:
+
+====================
+Command Line Engines
+====================
+
+.. sidebar:: info
+
+   - :origin:`command.py <searx/engines/command.py>`
+   - :ref:`offline engines`
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. sidebar:: info
+
+   Initial sponsored by `Search and Discovery Fund
+   <https://nlnet.nl/discovery>`_ of `NLnet Foundation <https://nlnet.nl/>`_.
+
+.. automodule:: searx.engines.command
+  :members:

docs/dev/engines/offline/nosql-engines.rst

@@ -0,0 +1,97 @@
+.. _nosql engines:
+
+===============
+NoSQL databases
+===============
+
+.. sidebar:: further read
+
+   - `NoSQL databases <https://en.wikipedia.org/wiki/NoSQL>`_
+   - `redis.io <https://redis.io/>`_
+   - `MongoDB <https://www.mongodb.com>`_
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. sidebar:: info
+
+   Initial sponsored by `Search and Discovery Fund
+   <https://nlnet.nl/discovery>`_ of `NLnet Foundation <https://nlnet.nl/>`_.
+
+The following `NoSQL databases`_ are supported:
+
+- :ref:`engine redis_server`
+- :ref:`engine mongodb`
+
+All of the engines above are just commented out in the :origin:`settings.yml
+<searx/settings.yml>`, as you have to set various options and install
+dependencies before using them.
+
+By default, the engines use the ``key-value`` template for displaying results /
+see :origin:`simple <searx/templates/simple/result_templates/key-value.html>`
+theme.  If you are not satisfied with the original result layout, you can use
+your own template, set ``result_template`` attribute to ``{template_name}`` and
+place the templates at::
+
+  searx/templates/{theme_name}/result_templates/{template_name}
+
+Furthermore, if you do not wish to expose these engines on a public instance, you
+can still add them and limit the access by setting ``tokens`` as described in
+section :ref:`private engines`.
+
+
+Extra Dependencies
+==================
+
+For using :ref:`engine redis_server` or :ref:`engine mongodb` you need to
+install additional packages in Python's Virtual Environment of your SearXNG
+instance.  To switch into the environment (:ref:`searxng-src`) you can use
+:ref:`searxng.sh`::
+
+  $ sudo utils/searxng.sh instance cmd bash
+  (searxng-pyenv)$ pip install ...
+
+
+Configure the engines
+=====================
+
+`NoSQL databases`_ are used for storing arbitrary data without first defining
+their structure.
+
+
+.. _engine redis_server:
+
+Redis Server
+------------
+
+.. _redis: https://github.com/andymccurdy/redis-py#installation
+
+.. sidebar:: info
+
+   - ``pip install`` redis_
+   - redis.io_
+   - :origin:`redis_server.py <searx/engines/redis_server.py>`
+
+.. automodule:: searx.engines.redis_server
+  :members:
+
+
+.. _engine mongodb:
+
+MongoDB
+-------
+
+.. _pymongo: https://github.com/mongodb/mongo-python-driver#installation
+
+.. sidebar:: info
+
+   - ``pip install`` pymongo_
+   - MongoDB_
+   - :origin:`mongodb.py <searx/engines/mongodb.py>`
+
+
+.. automodule:: searx.engines.mongodb
+  :members:
+

docs/dev/engines/offline/search-indexer-engines.rst

@@ -0,0 +1,62 @@
+=================
+Local Search APIs
+=================
+
+.. sidebar:: further read
+
+   - `Comparison to alternatives
+     <https://docs.meilisearch.com/learn/what_is_meilisearch/comparison_to_alternatives.html>`_
+
+.. contents::
+   :depth: 1
+   :local:
+   :backlinks: entry
+
+.. sidebar:: info
+
+   Initial sponsored by `Search and Discovery Fund
+   <https://nlnet.nl/discovery>`_ of `NLnet Foundation <https://nlnet.nl/>`_.
+
+Administrators might find themselves wanting to integrate locally running search
+engines.  The following ones are supported for now:
+
+* `Elasticsearch`_
+* `Meilisearch`_
+* `Solr`_
+
+Each search engine is powerful, capable of full-text search.  All of the engines
+above are added to ``settings.yml`` just commented out, as you have to
+``base_url`` for all them.
+
+Please note that if you are not using HTTPS to access these engines, you have to
+enable HTTP requests by setting ``enable_http`` to ``True``.
+
+Furthermore, if you do not want to expose these engines on a public instance,
+you can still add them and limit the access by setting ``tokens`` as described
+in section :ref:`private engines`.
+
+.. _engine meilisearch:
+
+MeiliSearch
+===========
+
+.. automodule:: searx.engines.meilisearch
+  :members:
+
+
+.. _engine elasticsearch:
+
+Elasticsearch
+=============
+
+.. automodule:: searx.engines.elasticsearch
+  :members:
+
+.. _engine solr:
+
+Solr
+====
+
+.. automodule:: searx.engines.solr
+  :members:
+

docs/dev/engines/offline/sql-engines.rst

@@ -0,0 +1,134 @@
+.. _sql engines:
+
+===========
+SQL Engines
+===========
+
+.. sidebar:: further read
+
+   - `SQLite <https://www.sqlite.org/index.html>`_
+   - `PostgreSQL <https://www.postgresql.org>`_
+   - `MySQL <https://www.mysql.com>`_
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. sidebar:: info
+
+   Initial sponsored by `Search and Discovery Fund
+   <https://nlnet.nl/discovery>`_ of `NLnet Foundation <https://nlnet.nl/>`_.
+
+With the *SQL engines* you can bind SQL databases into SearXNG.  The following
+Relational Database Management System (RDBMS) are supported:
+
+- :ref:`engine sqlite`
+- :ref:`engine postgresql`
+- :ref:`engine mysql_server` & :ref:`engine mariadb_server`
+
+All of the engines above are just commented out in the :origin:`settings.yml
+<searx/settings.yml>`, as you have to set the required attributes for the
+engines, e.g. ``database:`` ...
+
+.. code:: yaml
+
+   - name: ...
+     engine: {sqlite|postgresql|mysql_server}
+     database: ...
+     result_template: {template_name}
+     query_str: ...
+
+By default, the engines use the ``key-value`` template for displaying results /
+see :origin:`simple <searx/templates/simple/result_templates/key-value.html>`
+theme.  If you are not satisfied with the original result layout, you can use
+your own template, set ``result_template`` attribute to ``{template_name}`` and
+place the templates at::
+
+  searx/templates/{theme_name}/result_templates/{template_name}
+
+If you do not wish to expose these engines on a public instance, you can still
+add them and limit the access by setting ``tokens`` as described in section
+:ref:`private engines`.
+
+
+Extra Dependencies
+==================
+
+For using :ref:`engine postgresql` or :ref:`engine mysql_server` you need to
+install additional packages in Python's Virtual Environment of your SearXNG
+instance.  To switch into the environment (:ref:`searxng-src`) you can use
+:ref:`searxng.sh`::
+
+  $ sudo utils/searxng.sh instance cmd bash
+  (searxng-pyenv)$ pip install ...
+
+
+Configure the engines
+=====================
+
+The configuration of the new database engines are similar.  You must put a valid
+SQL-SELECT query in ``query_str``.  At the moment you can only bind at most one
+parameter in your query.  By setting the attribute ``limit`` you can define how
+many results you want from the SQL server.  Basically, it is the same as the
+``LIMIT`` keyword in SQL.
+
+Please, do not include ``LIMIT`` or ``OFFSET`` in your SQL query as the engines
+rely on these keywords during paging.  If you want to configure the number of
+returned results use the option ``limit``.
+
+.. _engine sqlite:
+
+SQLite
+------
+
+.. sidebar:: info
+
+   - :origin:`sqlite.py <searx/engines/sqlite.py>`
+
+.. automodule:: searx.engines.sqlite
+  :members:
+
+
+.. _engine postgresql:
+
+PostgreSQL
+----------
+
+.. _psycopg2: https://www.psycopg.org/install
+
+.. sidebar:: info
+
+   - :origin:`postgresql.py <searx/engines/postgresql.py>`
+   - ``pip install`` `psycopg2-binary <psycopg2>`_
+
+.. automodule:: searx.engines.postgresql
+  :members:
+
+.. _engine mysql_server:
+
+MySQL
+-----
+
+.. sidebar:: info
+
+   - :origin:`mysql_server.py <searx/engines/mysql_server.py>`
+   - ``pip install`` :pypi:`mysql-connector-python <mysql-connector-python>`
+
+
+.. automodule:: searx.engines.mysql_server
+  :members:
+
+.. _engine mariadb_server:
+
+MariaDB
+--------
+
+.. sidebar:: info
+
+   - :origin:`mariadb_server.py <searx/engines/mariadb_server.py>`
+   - ``pip install`` :pypi:`mariadb <mariadb>`
+
+
+.. automodule:: searx.engines.mariadb_server
+  :members:

docs/dev/engines/offline_concept.rst

@@ -0,0 +1,69 @@
+===============
+Offline Concept
+===============
+
+.. sidebar:: offline engines
+
+   - :ref:`demo offline engine`
+   - :ref:`engine command`
+   - :ref:`sql engines`
+   - :ref:`nosql engines`
+   - :py:obj:`searx.search.processors.offline`
+
+To extend the functionality of SearXNG, offline engines are going to be
+introduced.  An offline engine is an engine which does not need Internet
+connection to perform a search and does not use HTTP to communicate.
+
+Offline engines can be configured, by adding those to the `engines` list of
+:origin:`settings.yml <searx/settings.yml>`.  An example skeleton for offline
+engines can be found in :ref:`demo offline engine` (:origin:`demo_offline.py
+<searx/engines/demo_offline.py>`).
+
+
+Programming Interface
+=====================
+
+:py:func:`init(engine_settings=None) <searx.engines.demo_offline.init>`
+  All offline engines can have their own init function to setup the engine before
+  accepting requests. The function gets the settings from settings.yml as a
+  parameter. This function can be omitted, if there is no need to setup anything
+  in advance.
+
+:py:func:`search(query, params) <searx.engines.demo_offline.searc>`
+  Each offline engine has a function named ``search``.  This function is
+  responsible to perform a search and return the results in a presentable
+  format. (Where *presentable* means presentable by the selected result
+  template.)
+
+  The return value is a list of results retrieved by the engine.
+
+Engine representation in ``/config``
+  If an engine is offline, the attribute ``offline`` is set to ``True``.
+
+.. _offline requirements:
+
+Extra Dependencies
+==================
+
+If an offline engine depends on an external tool, SearXNG does not install it by
+default.  When an administrator configures such engine and starts the instance,
+the process returns an error with the list of missing dependencies.  Also,
+required dependencies will be added to the comment/description of the engine, so
+admins can install packages in advance.
+
+If there is a need to install additional packages in *Python's Virtual
+Environment* of your SearXNG instance you need to switch into the environment
+(:ref:`searxng-src`) first, for this you can use :ref:`searxng.sh`::
+
+  $ sudo utils/searxng.sh instance cmd bash
+  (searxng-pyenv)$ pip install ...
+
+
+Private engines (Security)
+==========================
+
+To limit the access to offline engines, if an instance is available publicly,
+administrators can set token(s) for each of the :ref:`private engines`.  If a
+query contains a valid token, then SearXNG performs the requested private
+search.  If not, requests from an offline engines return errors.
+

docs/dev/engines/online/adobe_stock.rst

@@ -0,0 +1,13 @@
+.. _adobe stock engine:
+
+===========
+Adobe Stock
+===========
+
+.. contents:: Contents
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. automodule:: searx.engines.adobe_stock
+   :members:

docs/dev/engines/online/alpinelinux.rst

@@ -0,0 +1,13 @@
+.. _alpinelinux engine:
+
+=====================
+Alpine Linux Packages
+=====================
+
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. automodule:: searx.engines.alpinelinux
+   :members: