From 5820dc78ce3b60aaf686959e5328542ff9bd628e Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Fri, 17 Feb 2023 12:08:58 +0100 Subject: [PATCH] [doc] slight improvements to the doc of the settings (base_url) Closes: https://github.com/searxng/searxng/issues/2190 Signed-off-by: Markus Heiser --- docs/admin/engines/settings.rst | 22 ++++++------ docs/admin/update-searxng.rst | 2 ++ docs/dev/makefile.rst | 46 +++++++++++++++++++----- searx/settings.yml | 12 ++++--- utils/templates/etc/searxng/settings.yml | 5 +++ 5 files changed, 63 insertions(+), 24 deletions(-) diff --git a/docs/admin/engines/settings.rst b/docs/admin/engines/settings.rst index e8d00ec1f..099e449e0 100644 --- a/docs/admin/engines/settings.rst +++ b/docs/admin/engines/settings.rst @@ -203,12 +203,12 @@ Global Settings .. code:: yaml server: - base_url: false # set custom base_url (or false) + base_url: http://example.org/location # change this! port: 8888 - bind_address: "127.0.0.1" # address to listen on - secret_key: "ultrasecretkey" # change this! + bind_address: "127.0.0.1" + secret_key: "ultrasecretkey" # change this! limiter: false - image_proxy: false # proxying image results through SearXNG + image_proxy: false default_http_headers: X-Content-Type-Options : nosniff X-XSS-Protection : 1; mode=block @@ -216,20 +216,18 @@ Global Settings X-Robots-Tag : noindex, nofollow Referrer-Policy : no-referrer -.. sidebar:: buildenv - Changing a value tagged by :ref:`buildenv `, needs to - rebuild instance's environment :ref:`utils/brand.env `. - -``base_url`` : :ref:`buildenv SEARXNG_URL ` +``base_url`` : ``$SEARXNG_URL`` :ref:`buildenv ` The base URL where SearXNG is deployed. Used to create correct inbound links. If you change the value, don't forget to rebuild instance's environment (:ref:`utils/brand.env `) -``port`` & ``bind_address``: :ref:`buildenv SEARXNG_PORT & SEARXNG_BIND_ADDRESS ` +``port`` & ``bind_address``: ``$SEARXNG_PORT`` & ``$SEARXNG_BIND_ADDRESS`` :ref:`buildenv ` Port number and *bind address* of the SearXNG web application if you run it - directly using ``python searx/webapp.py``. Doesn't apply to SearXNG running on - Apache or Nginx. + directly using ``python searx/webapp.py``. Doesn't apply to a SearXNG + services running behind a proxy and using socket communications. If you + change the value, don't forget to rebuild instance's environment + (:ref:`utils/brand.env `) ``secret_key`` : ``$SEARXNG_SECRET`` Used for cryptography purpose. diff --git a/docs/admin/update-searxng.rst b/docs/admin/update-searxng.rst index 3ddb41b59..627ed03e8 100644 --- a/docs/admin/update-searxng.rst +++ b/docs/admin/update-searxng.rst @@ -1,3 +1,5 @@ +.. _searxng maintenance: + =================== SearXNG maintenance =================== diff --git a/docs/dev/makefile.rst b/docs/dev/makefile.rst index 68c708a85..bdf7f0f49 100644 --- a/docs/dev/makefile.rst +++ b/docs/dev/makefile.rst @@ -90,15 +90,23 @@ Rebuild instance's environment with the modified settings from the :ref:`settings brand` and :ref:`settings server` section of your :ref:`settings.yml `. -We have all SearXNG setups are centralized in the :ref:`settings.yml` file. -This setup is available as long we are in a *installed instance*. E.g. the -*installed instance* on the server or the *installed developer instance* at -``./local`` (the later one is created by a :ref:`make install ` or :ref:`make run `). + What is the :origin:`utils/brand.env` needed for and why do you need to rebuild + it if necessary? -Tasks running outside of an *installed instance*, especially those tasks and -scripts running at (pre-) installation time do not have access to the SearXNG -setup (from a *installed instance*). Those tasks need a *build environment*. + Short answer: :ref:`installation and maintenance ` + scripts are running outside of instance's runtime environment and need some + values defined in the runtime environment. + +All the SearXNG setups are centralized in the :ref:`settings.yml` file. This +setup is available as long we are in a *installed instance*. E.g. the +*installed instance* on the server or the *installed developer instance* at +``./local`` (the later one is created by a :ref:`make install ` or +:ref:`make run `). + +Tasks running outside of an *installed instance*, especially :ref:`installation +and maintenance ` tasks running at (pre-) installation time +do not have access to the SearXNG setup (from a *installed instance*). Those +tasks need a *build environment*. The ``make buildenv`` target will update the *build environment* in: @@ -112,6 +120,28 @@ from the YAML configuration: - ``SEARXNG_BIND_ADDRESS`` from :ref:`server.bind_address ` - ``SEARXNG_PORT`` from :ref:`server.port ` +The ``GIT_URL`` and ``GIT_BRANCH`` in the origin:`utils/brand.env` file, are +readed from the git VCS and the branch that is checked out when ``make +buildenv`` command runs. + +.. _brand: + +**I would like to create my own brand, how should I proceed?** + +Create a remote branch (``example.org``), checkout the remote branch (on your +local developer desktop) and in the :origin:`searx/settings.yml` file in the +:ref:`settings server` section set ``base_url``. Run ``make buildenv`` and +create a commit for your brand. + +On your server you clone the branch (``example.org``) into your HOME folder +``~`` from where you run the :ref:`installation ` and +:ref:`maintenance ` task. + +To upgrade you brand, rebase on SearXNG's master branch (on your local +developer desktop), force push it to your remote branch. Go to your server, do +a force pull and run :ref:`sudo -H ./utils/searxng.sh instance update `. + .. _make node.env: Node.js environment (``make node.env``) diff --git a/searx/settings.yml b/searx/settings.yml index b4d7f03a5..14a87b769 100644 --- a/searx/settings.yml +++ b/searx/settings.yml @@ -1,5 +1,5 @@ general: - # Debug mode, only for development + # Debug mode, only for development. Is overwritten by ${SEARXNG_DEBUG} debug: false # displayed name instance_name: "SearXNG" @@ -66,16 +66,19 @@ search: server: # If you change port, bind_address or base_url don't forget to rebuild - # instance's environment (make buildenv) + # instance's environment (make buildenv). Is overwritten by ${SEARXNG_PORT} + # and ${SEARXNG_BIND_ADDRESS} port: 8888 bind_address: "127.0.0.1" - base_url: false # Possible values: false or "https://example.org/location". + # public URL of the instance, to ensure correct inbound links. Is overwritten + # by ${SEARXNG_URL}. + base_url: false # "http://example.com/location" limiter: false # rate limit the number of request on the instance, block some bots # If your instance owns a /etc/searxng/settings.yml file, then set the following # values there. - secret_key: "ultrasecretkey" # change this! + secret_key: "ultrasecretkey" # Is overwritten by ${SEARXNG_SECRET} # Proxying image results through searx image_proxy: false # 1.0 and 1.1 are supported @@ -91,6 +94,7 @@ server: Referrer-Policy: no-referrer redis: + # URL to connect redis database. Is overwritten by ${SEARXNG_REDIS_URL}. # https://redis-py.readthedocs.io/en/stable/connections.html#redis.client.Redis.from_url url: false diff --git a/utils/templates/etc/searxng/settings.yml b/utils/templates/etc/searxng/settings.yml index aee21474d..d8b659b1a 100644 --- a/utils/templates/etc/searxng/settings.yml +++ b/utils/templates/etc/searxng/settings.yml @@ -11,11 +11,16 @@ search: autocomplete: 'duckduckgo' server: + # Is overwritten by ${SEARXNG_SECRET} secret_key: "ultrasecretkey" limiter: true image_proxy: true + # public URL of the instance, to ensure correct inbound links. Is overwritten + # by ${SEARXNG_URL}. + # base_url: http://example.com/location redis: + # URL to connect redis database. Is overwritten by ${SEARXNG_REDIS_URL}. url: unix:///usr/local/searxng-redis/run/redis.sock?db=0 ui: