Merge pull request #544 from kvch/gh-pages

install docs update && dev tips

_sources/dev/contribution_guide.txt

@@ -64,6 +64,8 @@ In order to submit a patch, please follow the steps below:
 
 - Create a pull request.
 
+For more help on getting started with searx development, see :ref:`devquickstart`.
+
 
 Translation
 ~~~~~~~~~~~

_sources/dev/install/installation.txt

@@ -179,6 +179,24 @@ Add this configuration in the server config file
             uwsgi_pass unix:/run/uwsgi/app/searx/socket;
     }
 
+
+OR
+
+using reverse proxy
+(Please, note that reverse proxy advised to be used in case of single-user or low-traffic instances.)
+
+.. code:: nginx
+
+    location /searx {
+        proxy_pass http://127.0.0.1:8888;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Scheme $scheme;
+        proxy_set_header X-Script-Name /searx;
+        proxy_buffering off;
+    }
+
+
 Enable base\_url in searx/settings.yml
 
 ::

_sources/dev/quickstart.txt

@@ -1,3 +1,5 @@
+.. _devquickstart:
+
 Development Quickstart
 ----------------------
 
@@ -88,3 +90,19 @@ After installing grunt, the files can be built using the following command:
 .. code:: sh
 
     ./manage.sh build_grunt
+
+
+
+Tips for debugging/development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Turn on debug logging
+    Whether you are working on a new engine or trying to eliminate a bug, it is always a good idea
+    to turn on debug logging. When debug logging is enabled a stack trace appears,
+    instead of the cryptic ``Internal Server Error`` message. It can be turned on by setting
+    ``debug: False`` to ``debug: True`` in settings.yml.
+
+2. Run ``./manage.sh tests`` before creating a PR.
+    Failing build on Travis is common because of PEP8 checks. So a new commit must be created
+    containing these format fixes. This phase can be skipped if ``./manage.sh tests`` is run
+    locally before creating a PR.

dev/contribution_guide.html

@@ -25,7 +25,7 @@
     <script type="text/javascript" src="../_static/doctools.js"></script>
     <link rel="top" title="searx 0.8.0 documentation" href="../index.html" />
     <link rel="next" title="Installation" href="install/installation.html" />
-    <link rel="prev" title="Search syntax" href="../user/search_syntax.html" />
+    <link rel="prev" title="Development Quickstart" href="quickstart.html" />
    
   
   <link media="only screen and (max-device-width: 480px)" href="../_static/small_flask.css" type= "text/css" rel="stylesheet" />
@@ -92,6 +92,7 @@ above privacy concerns do not fancy you, simply fork it.</p>
 <li>Add yourself to the AUTHORS file.</li>
 <li>Create a pull request.</li>
 </ul>
+<p>For more help on getting started with searx development, see <a class="reference internal" href="quickstart.html#devquickstart"><span class="std std-ref">Development Quickstart</span></a>.</p>
 </div>
 <div class="section" id="translation">
 <h2>Translation<a class="headerlink" href="#translation" title="Permalink to this headline">¶</a></h2>

dev/install/installation.html

@@ -68,28 +68,28 @@ certificate</a></p>
 <h2><a class="toc-backref" href="#id3">Basic installation</a><a class="headerlink" href="#basic-installation" title="Permalink to this headline">¶</a></h2>
 <p>For Ubuntu, be sure to have enable universe repository.</p>
 <p>Install packages:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo apt-get install git build-essential libxslt-dev python-dev python-virtualenv python-pybabel zlib1g-dev libffi-dev libssl-dev
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">git</span> <span class="n">build</span><span class="o">-</span><span class="n">essential</span> <span class="n">libxslt</span><span class="o">-</span><span class="n">dev</span> <span class="n">python</span><span class="o">-</span><span class="n">dev</span> <span class="n">python</span><span class="o">-</span><span class="n">virtualenv</span> <span class="n">python</span><span class="o">-</span><span class="n">pybabel</span> <span class="n">zlib1g</span><span class="o">-</span><span class="n">dev</span> <span class="n">libffi</span><span class="o">-</span><span class="n">dev</span> <span class="n">libssl</span><span class="o">-</span><span class="n">dev</span>
 </pre></div>
 </div>
 <p>Install searx:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>cd /usr/local
-sudo git clone https://github.com/asciimoo/searx.git
-sudo useradd searx -d /usr/local/searx
-sudo chown searx:searx -R /usr/local/searx
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">cd</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span>
+<span class="n">sudo</span> <span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">asciimoo</span><span class="o">/</span><span class="n">searx</span><span class="o">.</span><span class="n">git</span>
+<span class="n">sudo</span> <span class="n">useradd</span> <span class="n">searx</span> <span class="o">-</span><span class="n">d</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">searx</span>
+<span class="n">sudo</span> <span class="n">chown</span> <span class="n">searx</span><span class="p">:</span><span class="n">searx</span> <span class="o">-</span><span class="n">R</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">searx</span>
 </pre></div>
 </div>
 <p>Install dependencies in a virtualenv:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo -u searx -i
-cd /usr/local/searx
-virtualenv searx-ve
-. ./searx-ve/bin/activate
-./manage.sh update_packages
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="o">-</span><span class="n">u</span> <span class="n">searx</span> <span class="o">-</span><span class="n">i</span>
+<span class="n">cd</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">searx</span>
+<span class="n">virtualenv</span> <span class="n">searx</span><span class="o">-</span><span class="n">ve</span>
+<span class="o">.</span> <span class="o">./</span><span class="n">searx</span><span class="o">-</span><span class="n">ve</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span>
+<span class="o">./</span><span class="n">manage</span><span class="o">.</span><span class="n">sh</span> <span class="n">update_packages</span>
 </pre></div>
 </div>
 </div>
 <div class="section" id="configuration">
 <h2><a class="toc-backref" href="#id4">Configuration</a><a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h2>
-<div class="code sh highlight-python"><div class="highlight"><pre>sed -i -e &quot;s/ultrasecretkey/`openssl rand -hex 16`/g&quot; searx/settings.yml
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sed</span> <span class="o">-</span><span class="n">i</span> <span class="o">-</span><span class="n">e</span> <span class="s">&quot;s/ultrasecretkey/`openssl rand -hex 16`/g&quot;</span> <span class="n">searx</span><span class="o">/</span><span class="n">settings</span><span class="o">.</span><span class="n">yml</span>
 </pre></div>
 </div>
 <p>Edit searx/settings.yml if necessary.</p>
@@ -97,12 +97,12 @@ virtualenv searx-ve
 <div class="section" id="check">
 <h2><a class="toc-backref" href="#id5">Check</a><a class="headerlink" href="#check" title="Permalink to this headline">¶</a></h2>
 <p>Start searx:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>python searx/webapp.py
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">python</span> <span class="n">searx</span><span class="o">/</span><span class="n">webapp</span><span class="o">.</span><span class="n">py</span>
 </pre></div>
 </div>
 <p>Go to <a class="reference external" href="http://localhost:8888">http://localhost:8888</a></p>
 <p>If everything works fine, disable the debug option in settings.yml:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sed -i -e &quot;s/debug : True/debug : False/g&quot; searx/settings.yml
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sed</span> <span class="o">-</span><span class="n">i</span> <span class="o">-</span><span class="n">e</span> <span class="s">&quot;s/debug : True/debug : False/g&quot;</span> <span class="n">searx</span><span class="o">/</span><span class="n">settings</span><span class="o">.</span><span class="n">yml</span>
 </pre></div>
 </div>
 <p>At this point searx is not demonized ; uwsgi allows this.</p>
@@ -112,43 +112,43 @@ twice).</p>
 <div class="section" id="uwsgi">
 <h2><a class="toc-backref" href="#id6">uwsgi</a><a class="headerlink" href="#uwsgi" title="Permalink to this headline">¶</a></h2>
 <p>Install packages:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo apt-get install uwsgi uwsgi-plugin-python
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">uwsgi</span> <span class="n">uwsgi</span><span class="o">-</span><span class="n">plugin</span><span class="o">-</span><span class="n">python</span>
 </pre></div>
 </div>
 <p>Create the configuration file /etc/uwsgi/apps-available/searx.ini with
 this content:</p>
-<div class="highlight-python"><div class="highlight"><pre>[uwsgi]
-# Who will run the code
-uid = searx
-gid = searx
+<div class="highlight-default"><div class="highlight"><pre><span class="p">[</span><span class="n">uwsgi</span><span class="p">]</span>
+<span class="c"># Who will run the code</span>
+<span class="n">uid</span> <span class="o">=</span> <span class="n">searx</span>
+<span class="n">gid</span> <span class="o">=</span> <span class="n">searx</span>
 
-# disable logging for privacy
-disable-logging = true
+<span class="c"># disable logging for privacy</span>
+<span class="n">disable</span><span class="o">-</span><span class="n">logging</span> <span class="o">=</span> <span class="n">true</span>
 
-# Number of workers (usually CPU count)
-workers = 4
+<span class="c"># Number of workers (usually CPU count)</span>
+<span class="n">workers</span> <span class="o">=</span> <span class="mi">4</span>
 
-# The right granted on the created socket
-chmod-socket = 666
+<span class="c"># The right granted on the created socket</span>
+<span class="n">chmod</span><span class="o">-</span><span class="n">socket</span> <span class="o">=</span> <span class="mi">666</span>
 
-# Plugin to use and interpretor config
-single-interpreter = true
-master = true
-plugin = python
+<span class="c"># Plugin to use and interpretor config</span>
+<span class="n">single</span><span class="o">-</span><span class="n">interpreter</span> <span class="o">=</span> <span class="n">true</span>
+<span class="n">master</span> <span class="o">=</span> <span class="n">true</span>
+<span class="n">plugin</span> <span class="o">=</span> <span class="n">python</span>
 
-# Module to import
-module = searx.webapp
+<span class="c"># Module to import</span>
+<span class="n">module</span> <span class="o">=</span> <span class="n">searx</span><span class="o">.</span><span class="n">webapp</span>
 
-# Virtualenv and python path
-virtualenv = /usr/local/searx/searx-ve/
-pythonpath = /usr/local/searx/
-chdir = /usr/local/searx/searx/
+<span class="c"># Virtualenv and python path</span>
+<span class="n">virtualenv</span> <span class="o">=</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">searx</span><span class="o">/</span><span class="n">searx</span><span class="o">-</span><span class="n">ve</span><span class="o">/</span>
+<span class="n">pythonpath</span> <span class="o">=</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">searx</span><span class="o">/</span>
+<span class="n">chdir</span> <span class="o">=</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">searx</span><span class="o">/</span><span class="n">searx</span><span class="o">/</span>
 </pre></div>
 </div>
 <p>Activate the uwsgi application and restart:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>cd /etc/uwsgi/apps-enabled
-ln -s ../apps-available/searx.ini
-/etc/init.d/uwsgi restart
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">cd</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">uwsgi</span><span class="o">/</span><span class="n">apps</span><span class="o">-</span><span class="n">enabled</span>
+<span class="n">ln</span> <span class="o">-</span><span class="n">s</span> <span class="o">../</span><span class="n">apps</span><span class="o">-</span><span class="n">available</span><span class="o">/</span><span class="n">searx</span><span class="o">.</span><span class="n">ini</span>
+<span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">init</span><span class="o">.</span><span class="n">d</span><span class="o">/</span><span class="n">uwsgi</span> <span class="n">restart</span>
 </pre></div>
 </div>
 </div>
@@ -158,28 +158,28 @@ ln -s ../apps-available/searx.ini
 <h3><a class="toc-backref" href="#id8">with nginx</a><a class="headerlink" href="#with-nginx" title="Permalink to this headline">¶</a></h3>
 <p>If nginx is not installed (uwsgi will not work with the package
 nginx-light):</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo apt-get install nginx
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">nginx</span>
 </pre></div>
 </div>
 <div class="section" id="hosted-at">
 <h4>Hosted at /<a class="headerlink" href="#hosted-at" title="Permalink to this headline">¶</a></h4>
 <p>Create the configuration file /etc/nginx/sites-available/searx with this
 content:</p>
-<div class="code nginx highlight-python"><div class="highlight"><pre>server {
-    listen 80;
-    server_name searx.example.com;
-    root /usr/local/searx;
+<div class="code nginx highlight-default"><div class="highlight"><pre><span class="n">server</span> <span class="p">{</span>
+    <span class="n">listen</span> <span class="mi">80</span><span class="p">;</span>
+    <span class="n">server_name</span> <span class="n">searx</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="p">;</span>
+    <span class="n">root</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">searx</span><span class="p">;</span>
 
-    location / {
-            include uwsgi_params;
-            uwsgi_pass unix:/run/uwsgi/app/searx/socket;
-    }
-}
+    <span class="n">location</span> <span class="o">/</span> <span class="p">{</span>
+            <span class="n">include</span> <span class="n">uwsgi_params</span><span class="p">;</span>
+            <span class="n">uwsgi_pass</span> <span class="n">unix</span><span class="p">:</span><span class="o">/</span><span class="n">run</span><span class="o">/</span><span class="n">uwsgi</span><span class="o">/</span><span class="n">app</span><span class="o">/</span><span class="n">searx</span><span class="o">/</span><span class="n">socket</span><span class="p">;</span>
+    <span class="p">}</span>
+<span class="p">}</span>
 </pre></div>
 </div>
 <p>Restart service:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo service nginx restart
-sudo service uwsgi restart
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="n">service</span> <span class="n">nginx</span> <span class="n">restart</span>
+<span class="n">sudo</span> <span class="n">service</span> <span class="n">uwsgi</span> <span class="n">restart</span>
 </pre></div>
 </div>
 </div>
@@ -187,7 +187,7 @@ sudo service uwsgi restart
 <h4>from subdirectory URL (/searx)<a class="headerlink" href="#from-subdirectory-url-searx" title="Permalink to this headline">¶</a></h4>
 <p>Add this configuration in the server config file
 /etc/nginx/sites-available/default:</p>
-<div class="code nginx highlight-python"><div class="highlight"><pre>location = /searx { rewrite ^ /searx/; }
+<div class="code nginx highlight-default"><div class="highlight"><pre>location = /searx { rewrite ^ /searx/; }
 location /searx {
         try_files $uri @searx;
 }
@@ -199,13 +199,26 @@ location @searx {
 }
 </pre></div>
 </div>
+<p>OR</p>
+<p>using reverse proxy
+(Please, note that reverse proxy advised to be used in case of single-user or low-traffic instances.)</p>
+<div class="code nginx highlight-default"><div class="highlight"><pre>location /searx {
+    proxy_pass http://127.0.0.1:8888;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Scheme $scheme;
+    proxy_set_header X-Script-Name /searx;
+    proxy_buffering off;
+}
+</pre></div>
+</div>
 <p>Enable base_url in searx/settings.yml</p>
-<div class="highlight-python"><div class="highlight"><pre>base_url : http://your.domain.tld/searx/
+<div class="highlight-default"><div class="highlight"><pre><span class="n">base_url</span> <span class="p">:</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">your</span><span class="o">.</span><span class="n">domain</span><span class="o">.</span><span class="n">tld</span><span class="o">/</span><span class="n">searx</span><span class="o">/</span>
 </pre></div>
 </div>
 <p>Restart service:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo service nginx restart
-sudo service uwsgi restart
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="n">service</span> <span class="n">nginx</span> <span class="n">restart</span>
+<span class="n">sudo</span> <span class="n">service</span> <span class="n">uwsgi</span> <span class="n">restart</span>
 </pre></div>
 </div>
 <div class="section" id="disable-logs">
@@ -213,12 +226,12 @@ sudo service uwsgi restart
 <p>for better privacy you can disable nginx logs about searx.</p>
 <p>how to proceed: below <code class="docutils literal"><span class="pre">uwsgi_pass</span></code> in
 /etc/nginx/sites-available/default add</p>
-<div class="highlight-python"><div class="highlight"><pre><span class="n">access_log</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">null</span><span class="p">;</span>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">access_log</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">null</span><span class="p">;</span>
 <span class="n">error_log</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">null</span><span class="p">;</span>
 </pre></div>
 </div>
 <p>Restart service:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo service nginx restart
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="n">service</span> <span class="n">nginx</span> <span class="n">restart</span>
 </pre></div>
 </div>
 </div>
@@ -227,23 +240,23 @@ sudo service uwsgi restart
 <div class="section" id="with-apache">
 <h3><a class="toc-backref" href="#id9">with apache</a><a class="headerlink" href="#with-apache" title="Permalink to this headline">¶</a></h3>
 <p>Add wsgi mod:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo apt-get install libapache2-mod-uwsgi
-sudo a2enmod uwsgi
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">libapache2</span><span class="o">-</span><span class="n">mod</span><span class="o">-</span><span class="n">uwsgi</span>
+<span class="n">sudo</span> <span class="n">a2enmod</span> <span class="n">uwsgi</span>
 </pre></div>
 </div>
 <p>Add this configuration in the file /etc/apache2/apache2.conf:</p>
-<div class="code apache highlight-python"><div class="highlight"><pre>&lt;Location /&gt;
-    Options FollowSymLinks Indexes
-    SetHandler uwsgi-handler
-    uWSGISocket /run/uwsgi/app/searx/socket
-&lt;/Location&gt;
+<div class="code apache highlight-default"><div class="highlight"><pre><span class="o">&lt;</span><span class="n">Location</span> <span class="o">/&gt;</span>
+    <span class="n">Options</span> <span class="n">FollowSymLinks</span> <span class="n">Indexes</span>
+    <span class="n">SetHandler</span> <span class="n">uwsgi</span><span class="o">-</span><span class="n">handler</span>
+    <span class="n">uWSGISocket</span> <span class="o">/</span><span class="n">run</span><span class="o">/</span><span class="n">uwsgi</span><span class="o">/</span><span class="n">app</span><span class="o">/</span><span class="n">searx</span><span class="o">/</span><span class="n">socket</span>
+<span class="o">&lt;/</span><span class="n">Location</span><span class="o">&gt;</span>
 </pre></div>
 </div>
 <p>Note that if your instance of searx is not at the root, you should
 change <code class="docutils literal"><span class="pre">&lt;Location</span> <span class="pre">/&gt;</span></code> by the location of your instance, like
 <code class="docutils literal"><span class="pre">&lt;Location</span> <span class="pre">/searx&gt;</span></code>.</p>
 <p>Restart Apache:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo /etc/init.d/apache2 restart
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">init</span><span class="o">.</span><span class="n">d</span><span class="o">/</span><span class="n">apache2</span> <span class="n">restart</span>
 </pre></div>
 </div>
 <div class="section" id="id1">
@@ -253,11 +266,11 @@ change <code class="docutils literal"><span class="pre">&lt;Location</span> <spa
 <p>WARNING: you can only disable logs for the whole (virtual) server not
 for a specific path.</p>
 <p>Go back to /etc/apache2/apache2.conf and above <code class="docutils literal"><span class="pre">&lt;Location</span> <span class="pre">/&gt;</span></code> add:</p>
-<div class="code apache highlight-python"><div class="highlight"><pre>CustomLog /dev/null combined
+<div class="code apache highlight-default"><div class="highlight"><pre><span class="n">CustomLog</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">null</span> <span class="n">combined</span>
 </pre></div>
 </div>
 <p>Restart Apache:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo /etc/init.d/apache2 restart
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">init</span><span class="o">.</span><span class="n">d</span><span class="o">/</span><span class="n">apache2</span> <span class="n">restart</span>
 </pre></div>
 </div>
 </div>
@@ -265,30 +278,30 @@ for a specific path.</p>
 </div>
 <div class="section" id="how-to-update">
 <h2><a class="toc-backref" href="#id10">How to update</a><a class="headerlink" href="#how-to-update" title="Permalink to this headline">¶</a></h2>
-<div class="code sh highlight-python"><div class="highlight"><pre>cd /usr/local/searx
-sudo -u searx -i
-. ./searx-ve/bin/activate
-git stash
-git pull origin master
-git stash apply
-./manage.sh update_packages
-sudo service uwsgi restart
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">cd</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">searx</span>
+<span class="n">sudo</span> <span class="o">-</span><span class="n">u</span> <span class="n">searx</span> <span class="o">-</span><span class="n">i</span>
+<span class="o">.</span> <span class="o">./</span><span class="n">searx</span><span class="o">-</span><span class="n">ve</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span>
+<span class="n">git</span> <span class="n">stash</span>
+<span class="n">git</span> <span class="n">pull</span> <span class="n">origin</span> <span class="n">master</span>
+<span class="n">git</span> <span class="n">stash</span> <span class="n">apply</span>
+<span class="o">./</span><span class="n">manage</span><span class="o">.</span><span class="n">sh</span> <span class="n">update_packages</span>
+<span class="n">sudo</span> <span class="n">service</span> <span class="n">uwsgi</span> <span class="n">restart</span>
 </pre></div>
 </div>
 </div>
 <div class="section" id="docker">
 <h2><a class="toc-backref" href="#id11">Docker</a><a class="headerlink" href="#docker" title="Permalink to this headline">¶</a></h2>
 <p>Make sure you have installed Docker. For instance, you can deploy searx like this:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>docker pull wonderfall/searx
+<div class="code sh highlight-default"><div class="highlight"><pre>docker pull wonderfall/searx
 docker run -d --name searx -p $PORT:8888 wonderfall/searx
 </pre></div>
 </div>
 <p>Go to <a class="reference external" href="http://localhost:$PORT">http://localhost:$PORT</a>.</p>
 <p>See <a class="reference external" href="https://hub.docker.com/r/wonderfall/searx/">https://hub.docker.com/r/wonderfall/searx/</a> for more informations.</p>
 <p>It&#8217;s also possible to build searx from the embedded Dockerfile.</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>git clone https://github.com/asciimoo/searx.git
-cd searx
-docker build -t whatever/searx .
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">asciimoo</span><span class="o">/</span><span class="n">searx</span><span class="o">.</span><span class="n">git</span>
+<span class="n">cd</span> <span class="n">searx</span>
+<span class="n">docker</span> <span class="n">build</span> <span class="o">-</span><span class="n">t</span> <span class="n">whatever</span><span class="o">/</span><span class="n">searx</span> <span class="o">.</span>
 </pre></div>
 </div>
 </div>

dev/quickstart.html

@@ -24,6 +24,8 @@
     <script type="text/javascript" src="../_static/underscore.js"></script>
     <script type="text/javascript" src="../_static/doctools.js"></script>
     <link rel="top" title="searx 0.8.0 documentation" href="../index.html" />
+    <link rel="next" title="How to contribute" href="contribution_guide.html" />
+    <link rel="prev" title="Search syntax" href="../user/search_syntax.html" />
    
   
   <link media="only screen and (max-device-width: 480px)" href="../_static/small_flask.css" type= "text/css" rel="stylesheet" />
@@ -38,7 +40,7 @@
           <div class="body" role="main">
             
   <div class="section" id="development-quickstart">
-<h1>Development Quickstart<a class="headerlink" href="#development-quickstart" title="Permalink to this headline">¶</a></h1>
+<span id="devquickstart"></span><h1>Development Quickstart<a class="headerlink" href="#development-quickstart" title="Permalink to this headline">¶</a></h1>
 <p>This quickstart guide gets your environment set up with searx. Furthermore, it gives a
 short introduction to the new manage.sh script.</p>
 <div class="section" id="how-to-setup-your-development-environment">
@@ -46,12 +48,12 @@ short introduction to the new manage.sh script.</p>
 <p>First, clone the source code of searx to the desired folder. In this case the source
 is cloned to ~/myprojects/searx. Then create and activate the searx-ve
 virtualenv and install the required packages using manage.sh.</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>cd ~/myprojects
-git clone https://github.com/asciimoo/searx.git
-cd searx
-virtualenv searx-ve
-. ./searx-ve/bin/activate
-./manage.sh update_dev_packages
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">cd</span> <span class="o">~/</span><span class="n">myprojects</span>
+<span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">asciimoo</span><span class="o">/</span><span class="n">searx</span><span class="o">.</span><span class="n">git</span>
+<span class="n">cd</span> <span class="n">searx</span>
+<span class="n">virtualenv</span> <span class="n">searx</span><span class="o">-</span><span class="n">ve</span>
+<span class="o">.</span> <span class="o">./</span><span class="n">searx</span><span class="o">-</span><span class="n">ve</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span>
+<span class="o">./</span><span class="n">manage</span><span class="o">.</span><span class="n">sh</span> <span class="n">update_dev_packages</span>
 </pre></div>
 </div>
 </div>
@@ -66,7 +68,7 @@ virtualenv searx-ve
 <li>Unit test coverage check</li>
 </ul>
 <p>For example unit tests are run with the command below:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>./manage.sh unit_tests
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="o">./</span><span class="n">manage</span><span class="o">.</span><span class="n">sh</span> <span class="n">unit_tests</span>
 </pre></div>
 </div>
 <p>For further test options, please consult the help of the manage.sh script.</p>
@@ -76,16 +78,16 @@ virtualenv searx-ve
 <div class="section" id="how-to-build-styles">
 <h3>How to build styles<a class="headerlink" href="#how-to-build-styles" title="Permalink to this headline">¶</a></h3>
 <p>Less is required to build the styles of searx. Less can be installed using either NodeJS or Apt.</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo apt-get install nodejs
-sudo npm install -g less
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">nodejs</span>
+<span class="n">sudo</span> <span class="n">npm</span> <span class="n">install</span> <span class="o">-</span><span class="n">g</span> <span class="n">less</span>
 </pre></div>
 </div>
 <p>OR</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo apt-get install node-less
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">node</span><span class="o">-</span><span class="n">less</span>
 </pre></div>
 </div>
 <p>After satisfying the requirements styles can be build using manage.sh</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>./manage.sh styles
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="o">./</span><span class="n">manage</span><span class="o">.</span><span class="n">sh</span> <span class="n">styles</span>
 </pre></div>
 </div>
 </div>
@@ -93,16 +95,38 @@ sudo npm install -g less
 <h3>How to build the source of the oscar theme<a class="headerlink" href="#how-to-build-the-source-of-the-oscar-theme" title="Permalink to this headline">¶</a></h3>
 <p>Grunt must be installed in order to build the javascript sources. It depends on NodeJS, so first
 Node has to be installed.</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>sudo apt-get install nodejs
-sudo npm install -g grunt-cli
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">nodejs</span>
+<span class="n">sudo</span> <span class="n">npm</span> <span class="n">install</span> <span class="o">-</span><span class="n">g</span> <span class="n">grunt</span><span class="o">-</span><span class="n">cli</span>
 </pre></div>
 </div>
 <p>After installing grunt, the files can be built using the following command:</p>
-<div class="code sh highlight-python"><div class="highlight"><pre>./manage.sh build_grunt
+<div class="code sh highlight-default"><div class="highlight"><pre><span class="o">./</span><span class="n">manage</span><span class="o">.</span><span class="n">sh</span> <span class="n">build_grunt</span>
 </pre></div>
 </div>
 </div>
 </div>
+<div class="section" id="tips-for-debugging-development">
+<h2>Tips for debugging/development<a class="headerlink" href="#tips-for-debugging-development" title="Permalink to this headline">¶</a></h2>
+<ol class="arabic">
+<li><dl class="first docutils">
+<dt>Turn on debug logging</dt>
+<dd><p class="first last">Whether you are working on a new engine or trying to eliminate a bug, it is always a good idea
+to turn on debug logging. When debug logging is enabled a stack trace appears,
+instead of the cryptic <code class="docutils literal"><span class="pre">Internal</span> <span class="pre">Server</span> <span class="pre">Error</span></code> message. It can be turned on by setting
+<code class="docutils literal"><span class="pre">debug:</span> <span class="pre">False</span></code> to <code class="docutils literal"><span class="pre">debug:</span> <span class="pre">True</span></code> in settings.yml.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt>Run <code class="docutils literal"><span class="pre">./manage.sh</span> <span class="pre">tests</span></code> before creating a PR.</dt>
+<dd><p class="first last">Failing build on Travis is common because of PEP8 checks. So a new commit must be created
+containing these format fixes. This phase can be skipped if <code class="docutils literal"><span class="pre">./manage.sh</span> <span class="pre">tests</span></code> is run
+locally before creating a PR.</p>
+</dd>
+</dl>
+</li>
+</ol>
+</div>
 </div>
 
 

docs/dev/contribution_guide.rst

@@ -64,6 +64,8 @@ In order to submit a patch, please follow the steps below:
 
 - Create a pull request.
 
+For more help on getting started with searx development, see :ref:`devquickstart`.
+
 
 Translation
 ~~~~~~~~~~~

docs/dev/install/installation.rst

@@ -179,6 +179,24 @@ Add this configuration in the server config file
             uwsgi_pass unix:/run/uwsgi/app/searx/socket;
     }
 
+
+OR
+
+using reverse proxy
+(Please, note that reverse proxy advised to be used in case of single-user or low-traffic instances.)
+
+.. code:: nginx
+
+    location /searx {
+        proxy_pass http://127.0.0.1:8888;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Scheme $scheme;
+        proxy_set_header X-Script-Name /searx;
+        proxy_buffering off;
+    }
+
+
 Enable base\_url in searx/settings.yml
 
 ::

docs/dev/quickstart.rst

@@ -1,3 +1,5 @@
+.. _devquickstart:
+
 Development Quickstart
 ----------------------
 
@@ -88,3 +90,19 @@ After installing grunt, the files can be built using the following command:
 .. code:: sh
 
     ./manage.sh build_grunt
+
+
+
+Tips for debugging/development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Turn on debug logging
+    Whether you are working on a new engine or trying to eliminate a bug, it is always a good idea
+    to turn on debug logging. When debug logging is enabled a stack trace appears,
+    instead of the cryptic ``Internal Server Error`` message. It can be turned on by setting
+    ``debug: False`` to ``debug: True`` in settings.yml.
+
+2. Run ``./manage.sh tests`` before creating a PR.
+    Failing build on Travis is common because of PEP8 checks. So a new commit must be created
+    containing these format fixes. This phase can be skipped if ``./manage.sh tests`` is run
+    locally before creating a PR.