Deploying to gh-pages from @ a1e6bc4cee 🚀

_sources/admin/settings.rst.txt

@@ -206,3 +206,80 @@ Engine settings
 
    A few more options are possible, but they are pretty specific to some
    engines, and so won't be described here.
+
+
+.. _settings location:
+
+settings.yml location
+=====================
+
+First, searx will try to load settings.yml from these locations:
+
+1. the full path specified in the ``SEARX_SETTINGS_PATH`` environment variable.
+2. ``/etc/searx/settings.yml``
+
+If these files don't exist (or are empty or can't be read), searx uses the :origin:`searx/settings.yml` file.
+
+.. _ settings use_default_settings:
+
+use_default_settings
+====================
+
+.. note::
+
+   If searx is cloned from a git repository, most probably there is no need to have an user settings.
+
+The user defined settings.yml can relied on the default configuration :origin:`searx/settings.yml` using ``use_default_settings: True``.
+
+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-block:: yaml
+
+  use_default_settings: True
+  server:
+      secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
+      bind_address: "0.0.0.0"
+
+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, searx will load all the engine and the arch linux wiki engine has a :ref:`token<private engines>`:
+
+.. code-block:: yaml
+
+  use_default_settings: True
+  server:
+      secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
+  engines:
+    - name: arch linux wiki
+      tokens: ['$ecretValue']
+
+It is possible to remove some engines from the default settings. The following example is similar to the above one, but searx doesn't load the the google engine:
+
+.. code-block:: yaml
+
+  use_default_settings:
+      engines:
+         remove:
+           - google
+  server:
+      secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
+  engines:
+    - name: arch linux wiki
+      tokens: ['$ecretValue']
+
+As an alternative, it is possible to specify the engines to keep. In the following example, searx has only two engines:
+
+.. code-block:: yaml
+
+  use_default_settings:
+      engines:
+         keep_only:
+           - google
+           - duckduckgo
+  server:
+      secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
+  engines:
+    - name: google
+      tokens: ['$ecretValue']
+    - name: duckduckgo
+      tokens: ['$ecretValue']

_sources/blog/private-engines.rst.txt

@@ -7,6 +7,8 @@ enabled engines on their instances. It might be because they do not want to
 expose some private information through an offline engine. Or they
 would rather share engines only with their trusted friends or colleagues.
 
+.. _private engines:
+
 Private engines
 ===============
 

admin/index.html

@@ -97,6 +97,8 @@
 <li class="toctree-l1"><a class="reference internal" href="settings.html"><code class="docutils literal notranslate"><span class="pre">settings.yml</span></code></a><ul>
 <li class="toctree-l2"><a class="reference internal" href="settings.html#global-settings">Global Settings</a></li>
 <li class="toctree-l2"><a class="reference internal" href="settings.html#engine-settings">Engine settings</a></li>
+<li class="toctree-l2"><a class="reference internal" href="settings.html#settings-yml-location">settings.yml location</a></li>
+<li class="toctree-l2"><a class="reference internal" href="settings.html#use-default-settings">use_default_settings</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">Administration API</a><ul>

admin/settings.html

@@ -66,6 +66,8 @@ file.</p>
 <ul class="simple">
 <li><p><a class="reference internal" href="#global-settings" id="id2">Global Settings</a></p></li>
 <li><p><a class="reference internal" href="#engine-settings" id="id3">Engine settings</a></p></li>
+<li><p><a class="reference internal" href="#settings-yml-location" id="id4">settings.yml location</a></p></li>
+<li><p><a class="reference internal" href="#use-default-settings" id="id5">use_default_settings</a></p></li>
 </ul>
 </div>
 <div class="section" id="global-settings">
@@ -232,6 +234,67 @@ by using the full ISO code of language and country, like <code class="docutils l
 engines, and so won’t be described here.</p>
 </div>
 </div>
+<div class="section" id="settings-yml-location">
+<span id="settings-location"></span><h2><a class="toc-backref" href="#id4">settings.yml location</a><a class="headerlink" href="#settings-yml-location" title="Permalink to this headline">¶</a></h2>
+<p>First, searx will try to load settings.yml from these locations:</p>
+<ol class="arabic simple">
+<li><p>the full path specified in the <code class="docutils literal notranslate"><span class="pre">SEARX_SETTINGS_PATH</span></code> environment variable.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">/etc/searx/settings.yml</span></code></p></li>
+</ol>
+<p>If these files don’t exist (or are empty or can’t be read), searx uses the <a class="reference external" href="https://github.com/searx/searx/blob/master/searx/settings.yml">git://searx/settings.yml</a> file.</p>
+</div>
+<div class="section" id="use-default-settings">
+<h2><a class="toc-backref" href="#id5">use_default_settings</a><a class="headerlink" href="#use-default-settings" title="Permalink to this headline">¶</a></h2>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>If searx is cloned from a git repository, most probably there is no need to have an user settings.</p>
+</div>
+<p>The user defined settings.yml can relied on the default configuration <a class="reference external" href="https://github.com/searx/searx/blob/master/searx/settings.yml">git://searx/settings.yml</a> using <code class="docutils literal notranslate"><span class="pre">use_default_settings:</span> <span class="pre">True</span></code>.</p>
+<p>In the following example, the actual settings are the default settings defined in <a class="reference external" href="https://github.com/searx/searx/blob/master/searx/settings.yml">git://searx/settings.yml</a> with the exception of the <code class="docutils literal notranslate"><span class="pre">secret_key</span></code> and the <code class="docutils literal notranslate"><span class="pre">bind_address</span></code>:</p>
+<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">use_default_settings</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">True</span>
+<span class="l l-Scalar l-Scalar-Plain">server</span><span class="p p-Indicator">:</span>
+    <span class="l l-Scalar l-Scalar-Plain">secret_key</span><span class="p p-Indicator">:</span> <span class="s">&quot;uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA&quot;</span>
+    <span class="l l-Scalar l-Scalar-Plain">bind_address</span><span class="p p-Indicator">:</span> <span class="s">&quot;0.0.0.0&quot;</span>
+</pre></div>
+</div>
+<p>With <code class="docutils literal notranslate"><span class="pre">use_default_settings:</span> <span class="pre">True</span></code>, each settings can be override in a similar way, the <code class="docutils literal notranslate"><span class="pre">engines</span></code> section is merged according to the engine <code class="docutils literal notranslate"><span class="pre">name</span></code>.</p>
+<p>In this example, searx will load all the engine and the arch linux wiki engine has a <a class="reference internal" href="../blog/private-engines.html#private-engines"><span class="std std-ref">token</span></a>:</p>
+<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">use_default_settings</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">True</span>
+<span class="l l-Scalar l-Scalar-Plain">server</span><span class="p p-Indicator">:</span>
+    <span class="l l-Scalar l-Scalar-Plain">secret_key</span><span class="p p-Indicator">:</span> <span class="s">&quot;uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA&quot;</span>
+<span class="l l-Scalar l-Scalar-Plain">engines</span><span class="p p-Indicator">:</span>
+  <span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">arch linux wiki</span>
+    <span class="l l-Scalar l-Scalar-Plain">tokens</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">[</span><span class="s">&#39;$ecretValue&#39;</span><span class="p p-Indicator">]</span>
+</pre></div>
+</div>
+<p>It is possible to remove some engines from the default settings. The following example is similar to the above one, but searx doesn’t load the the google engine:</p>
+<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">use_default_settings</span><span class="p p-Indicator">:</span>
+    <span class="l l-Scalar l-Scalar-Plain">engines</span><span class="p p-Indicator">:</span>
+       <span class="l l-Scalar l-Scalar-Plain">remove</span><span class="p p-Indicator">:</span>
+         <span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">google</span>
+<span class="l l-Scalar l-Scalar-Plain">server</span><span class="p p-Indicator">:</span>
+    <span class="l l-Scalar l-Scalar-Plain">secret_key</span><span class="p p-Indicator">:</span> <span class="s">&quot;uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA&quot;</span>
+<span class="l l-Scalar l-Scalar-Plain">engines</span><span class="p p-Indicator">:</span>
+  <span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">arch linux wiki</span>
+    <span class="l l-Scalar l-Scalar-Plain">tokens</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">[</span><span class="s">&#39;$ecretValue&#39;</span><span class="p p-Indicator">]</span>
+</pre></div>
+</div>
+<p>As an alternative, it is possible to specify the engines to keep. In the following example, searx has only two engines:</p>
+<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">use_default_settings</span><span class="p p-Indicator">:</span>
+    <span class="l l-Scalar l-Scalar-Plain">engines</span><span class="p p-Indicator">:</span>
+       <span class="l l-Scalar l-Scalar-Plain">keep_only</span><span class="p p-Indicator">:</span>
+         <span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">google</span>
+         <span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">duckduckgo</span>
+<span class="l l-Scalar l-Scalar-Plain">server</span><span class="p p-Indicator">:</span>
+    <span class="l l-Scalar l-Scalar-Plain">secret_key</span><span class="p p-Indicator">:</span> <span class="s">&quot;uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA&quot;</span>
+<span class="l l-Scalar l-Scalar-Plain">engines</span><span class="p p-Indicator">:</span>
+  <span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">google</span>
+    <span class="l l-Scalar l-Scalar-Plain">tokens</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">[</span><span class="s">&#39;$ecretValue&#39;</span><span class="p p-Indicator">]</span>
+  <span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">duckduckgo</span>
+    <span class="l l-Scalar l-Scalar-Plain">tokens</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">[</span><span class="s">&#39;$ecretValue&#39;</span><span class="p p-Indicator">]</span>
+</pre></div>
+</div>
+</div>
 </div>
 
 

blog/private-engines.html

@@ -58,7 +58,7 @@ enabled engines on their instances. It might be because they do not want to
 expose some private information through an offline engine. Or they
 would rather share engines only with their trusted friends or colleagues.</p>
 <div class="section" id="private-engines">
-<h2>Private engines<a class="headerlink" href="#private-engines" title="Permalink to this headline">¶</a></h2>
+<span id="id1"></span><h2>Private engines<a class="headerlink" href="#private-engines" title="Permalink to this headline">¶</a></h2>
 <p>To solve this issue private engines were introduced in <a class="reference external" href="https://github.com/searx/searx/pull/1823">PR 1823</a>.
 A new option was added to engines named <cite>tokens</cite>. It expects a list
 of strings. If the user making a request presents one of the tokens