[doc] slight improvements to the doc of the settings (base_url)

Closes: https://github.com/searxng/searxng/issues/2190

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

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 <make buildenv>`, needs to
-   rebuild instance's environment :ref:`utils/brand.env <make buildenv>`.
-
-``base_url`` : :ref:`buildenv SEARXNG_URL <make buildenv>`
+``base_url`` : ``$SEARXNG_URL`` :ref:`buildenv <make 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 <make buildenv>`)
 
-``port`` & ``bind_address``: :ref:`buildenv SEARXNG_PORT & SEARXNG_BIND_ADDRESS <make buildenv>`
+``port`` & ``bind_address``: ``$SEARXNG_PORT`` & ``$SEARXNG_BIND_ADDRESS`` :ref:`buildenv <make 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 <make buildenv>`)
 
 ``secret_key`` : ``$SEARXNG_SECRET``
   Used for cryptography purpose.

docs/admin/update-searxng.rst

@@ -1,3 +1,5 @@
+.. _searxng maintenance:
+
 ===================
 SearXNG maintenance
 ===================

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 <settings location>`.
 
-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 <make
-install>` or :ref:`make run <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 <searxng 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 <make install>` or
+:ref:`make run <make run>`).
+
+Tasks running outside of an *installed instance*, especially :ref:`installation
+and maintenance <searxng 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 <settings server>`
 - ``SEARXNG_PORT`` from :ref:`server.port <settings server>`
 
+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 <installation>` and
+:ref:`maintenance <searxng 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 <update
+searxng>`.
+
 .. _make node.env:
 
 Node.js environment (``make node.env``)

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
 

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: