[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>

1 files changed, 37 insertions, 7 deletions

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 <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
+  What is the :origin:`utils/brand.env` needed for and why do you need to rebuild
+  it if necessary?
+
+  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>`).
+``./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 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*.
+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``)