[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>
This commit is contained in:
Markus Heiser 2023-02-17 12:08:58 +01:00
parent b22355503f
commit 5820dc78ce
5 changed files with 63 additions and 24 deletions

View File

@ -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.

View File

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

View File

@ -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``)

View File

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

View File

@ -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: