From 04eeeb53a1215315d8027ac99978b560f45d5521 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 12 Dec 2019 19:48:42 +0100 Subject: doc: moved reST sources in the right folder (much clearer) Signed-off-by: Markus Heiser --- docs/admin/index.rst | 11 ++ docs/admin/installation.rst | 341 ++++++++++++++++++++++++++++++++++++++ docs/blog/blog.rst | 10 -- docs/blog/index.rst | 10 ++ docs/dev/index.rst | 13 ++ docs/dev/install/installation.rst | 341 -------------------------------------- docs/index.rst | 38 +---- docs/user/index.rst | 9 + 8 files changed, 390 insertions(+), 383 deletions(-) create mode 100644 docs/admin/index.rst create mode 100644 docs/admin/installation.rst delete mode 100644 docs/blog/blog.rst create mode 100644 docs/blog/index.rst create mode 100644 docs/dev/index.rst delete mode 100644 docs/dev/install/installation.rst create mode 100644 docs/user/index.rst (limited to 'docs') diff --git a/docs/admin/index.rst b/docs/admin/index.rst new file mode 100644 index 000000000..f3a995769 --- /dev/null +++ b/docs/admin/index.rst @@ -0,0 +1,11 @@ +=========================== +Administrator documentation +=========================== + +.. toctree:: + :maxdepth: 1 + + installation + api + filtron + morty diff --git a/docs/admin/installation.rst b/docs/admin/installation.rst new file mode 100644 index 000000000..239ce0704 --- /dev/null +++ b/docs/admin/installation.rst @@ -0,0 +1,341 @@ +.. _installation: + +============ +Installation +============ + +.. contents:: + :depth: 3 + +Basic installation +================== + +Step by step installation for Debian/Ubuntu with virtualenv. For Ubuntu, be sure +to have enable universe repository. + +Install packages: + +.. code:: sh + + $ sudo -H apt-get install \ + git build-essential libxslt-dev \ + python-dev python-virtualenv python-babel \ + zlib1g-dev libffi-dev libssl-dev + +Install searx: + +.. code:: sh + + cd /usr/local + sudo -H git clone https://github.com/asciimoo/searx.git + sudo -H useradd searx -d /usr/local/searx + sudo -H chown searx:searx -R /usr/local/searx + +Install dependencies in a virtualenv: + +.. code:: sh + + cd /usr/local/searx + sudo -H -u searx -i + +.. code:: sh + + (searx)$ virtualenv searx-ve + (searx)$ . ./searx-ve/bin/activate + (searx)$ ./manage.sh update_packages + +Configuration +============== + +.. code:: sh + + sed -i -e "s/ultrasecretkey/`openssl rand -hex 16`/g" searx/settings.yml + +Edit searx/settings.yml if necessary. + +Check +===== + +Start searx: + +.. code:: sh + + python searx/webapp.py + +Go to http://localhost:8888 + +If everything works fine, disable the debug option in settings.yml: + +.. code:: sh + + sed -i -e "s/debug : True/debug : False/g" searx/settings.yml + +At this point searx is not demonized ; uwsgi allows this. + +You can exit the virtualenv and the searx user bash (enter exit command +twice). + +uwsgi +===== + +Install packages: + +.. code:: sh + + sudo -H apt-get install \ + uwsgi uwsgi-plugin-python + +Create the configuration file ``/etc/uwsgi/apps-available/searx.ini`` with this +content: + +.. code:: ini + + [uwsgi] + # Who will run the code + uid = searx + gid = searx + + # disable logging for privacy + disable-logging = true + + # Number of workers (usually CPU count) + workers = 4 + + # The right granted on the created socket + chmod-socket = 666 + + # Plugin to use and interpretor config + single-interpreter = true + master = true + plugin = python + lazy-apps = true + enable-threads = true + + # Module to import + module = searx.webapp + + # Virtualenv and python path + virtualenv = /usr/local/searx/searx-ve/ + pythonpath = /usr/local/searx/ + chdir = /usr/local/searx/searx/ + +Activate the uwsgi application and restart: + +.. code:: sh + + cd /etc/uwsgi/apps-enabled + ln -s ../apps-available/searx.ini + /etc/init.d/uwsgi restart + +Web server +========== + +with nginx +---------- + +If nginx is not installed (uwsgi will not work with the package +nginx-light): + +.. code:: sh + + sudo -H apt-get install nginx + +Hosted at / +~~~~~~~~~~~ + +Create the configuration file ``/etc/nginx/sites-available/searx`` with this +content: + +.. code:: nginx + + server { + listen 80; + server_name searx.example.com; + root /usr/local/searx; + + location / { + include uwsgi_params; + uwsgi_pass unix:/run/uwsgi/app/searx/socket; + } + } + +Create a symlink to sites-enabled: + +.. code:: sh + + sudo -H ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx + +Restart service: + +.. code:: sh + + sudo -H service nginx restart + sudo -H service uwsgi restart + +from subdirectory URL (/searx) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add this configuration in the server config file +``/etc/nginx/sites-enabled/default``: + +.. code:: nginx + + location = /searx { rewrite ^ /searx/; } + location /searx { + try_files $uri @searx; + } + location @searx { + uwsgi_param SCRIPT_NAME /searx; + include uwsgi_params; + uwsgi_modifier1 30; + 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`` + +.. code:: yaml + + base_url : http://your.domain.tld/searx/ + +Restart service: + +.. code:: sh + + sudo -H service nginx restart + sudo -H service uwsgi restart + +disable logs +^^^^^^^^^^^^ + +for better privacy you can disable nginx logs about searx. + +how to proceed: below ``uwsgi_pass`` in ``/etc/nginx/sites-available/default`` +add: + +.. code:: nginx + + access_log /dev/null; + error_log /dev/null; + +Restart service: + +.. code:: sh + + sudo -H service nginx restart + +with apache +----------- + +Add wsgi mod: + +.. code:: sh + + sudo -H apt-get install libapache2-mod-uwsgi + sudo -H a2enmod uwsgi + +Add this configuration in the file ``/etc/apache2/apache2.conf``: + +.. code:: apache + + + Options FollowSymLinks Indexes + SetHandler uwsgi-handler + uWSGISocket /run/uwsgi/app/searx/socket + + +Note that if your instance of searx is not at the root, you should change +```` by the location of your instance, like ````. + +Restart Apache: + +.. code:: sh + + sudo -H /etc/init.d/apache2 restart + +disable logs +~~~~~~~~~~~~ + +For better privacy you can disable Apache logs. + +.. warning:: + + You can only disable logs for the whole (virtual) server not for a specific + path. + +Go back to ``/etc/apache2/apache2.conf`` and above ```` add: + +.. code:: apache + + CustomLog /dev/null combined + +Restart Apache: + +.. code:: sh + + sudo -H /etc/init.d/apache2 restart + +How to update +============= + +.. code:: sh + + cd /usr/local/searx + sudo -H -u searx -i + +.. code:: sh + + (searx)$ . ./searx-ve/bin/activate + (searx)$ git stash + (searx)$ git pull origin master + (searx)$ git stash apply + (searx)$ ./manage.sh update_packages + +.. code:: sh + + sudo -H service uwsgi restart + +Docker +====== + +Make sure you have installed Docker. For instance, you can deploy searx like this: + +.. code:: sh + + docker pull wonderfall/searx + docker run -d --name searx -p $PORT:8888 wonderfall/searx + +Go to ``http://localhost:$PORT``. + +See https://hub.docker.com/r/wonderfall/searx/ for more informations. It's also +possible to build searx from the embedded Dockerfile. + +.. code:: sh + + git clone https://github.com/asciimoo/searx.git + cd searx + docker build -t whatever/searx . + +References +========== + +* https://about.okhin.fr/posts/Searx/ with some additions + +* How to: `Setup searx in a couple of hours with a free SSL certificate + `__ + diff --git a/docs/blog/blog.rst b/docs/blog/blog.rst deleted file mode 100644 index 52fa3f126..000000000 --- a/docs/blog/blog.rst +++ /dev/null @@ -1,10 +0,0 @@ -==== -Blog -==== - -.. toctree:: - :maxdepth: 1 - - python3 - admin - intro-offline diff --git a/docs/blog/index.rst b/docs/blog/index.rst new file mode 100644 index 000000000..52fa3f126 --- /dev/null +++ b/docs/blog/index.rst @@ -0,0 +1,10 @@ +==== +Blog +==== + +.. toctree:: + :maxdepth: 1 + + python3 + admin + intro-offline diff --git a/docs/dev/index.rst b/docs/dev/index.rst new file mode 100644 index 000000000..8e18066ca --- /dev/null +++ b/docs/dev/index.rst @@ -0,0 +1,13 @@ +======================= +Developer documentation +======================= + +.. toctree:: + :maxdepth: 1 + + quickstart + contribution_guide + engine_overview + search_api + plugins + translation diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst deleted file mode 100644 index 239ce0704..000000000 --- a/docs/dev/install/installation.rst +++ /dev/null @@ -1,341 +0,0 @@ -.. _installation: - -============ -Installation -============ - -.. contents:: - :depth: 3 - -Basic installation -================== - -Step by step installation for Debian/Ubuntu with virtualenv. For Ubuntu, be sure -to have enable universe repository. - -Install packages: - -.. code:: sh - - $ sudo -H apt-get install \ - git build-essential libxslt-dev \ - python-dev python-virtualenv python-babel \ - zlib1g-dev libffi-dev libssl-dev - -Install searx: - -.. code:: sh - - cd /usr/local - sudo -H git clone https://github.com/asciimoo/searx.git - sudo -H useradd searx -d /usr/local/searx - sudo -H chown searx:searx -R /usr/local/searx - -Install dependencies in a virtualenv: - -.. code:: sh - - cd /usr/local/searx - sudo -H -u searx -i - -.. code:: sh - - (searx)$ virtualenv searx-ve - (searx)$ . ./searx-ve/bin/activate - (searx)$ ./manage.sh update_packages - -Configuration -============== - -.. code:: sh - - sed -i -e "s/ultrasecretkey/`openssl rand -hex 16`/g" searx/settings.yml - -Edit searx/settings.yml if necessary. - -Check -===== - -Start searx: - -.. code:: sh - - python searx/webapp.py - -Go to http://localhost:8888 - -If everything works fine, disable the debug option in settings.yml: - -.. code:: sh - - sed -i -e "s/debug : True/debug : False/g" searx/settings.yml - -At this point searx is not demonized ; uwsgi allows this. - -You can exit the virtualenv and the searx user bash (enter exit command -twice). - -uwsgi -===== - -Install packages: - -.. code:: sh - - sudo -H apt-get install \ - uwsgi uwsgi-plugin-python - -Create the configuration file ``/etc/uwsgi/apps-available/searx.ini`` with this -content: - -.. code:: ini - - [uwsgi] - # Who will run the code - uid = searx - gid = searx - - # disable logging for privacy - disable-logging = true - - # Number of workers (usually CPU count) - workers = 4 - - # The right granted on the created socket - chmod-socket = 666 - - # Plugin to use and interpretor config - single-interpreter = true - master = true - plugin = python - lazy-apps = true - enable-threads = true - - # Module to import - module = searx.webapp - - # Virtualenv and python path - virtualenv = /usr/local/searx/searx-ve/ - pythonpath = /usr/local/searx/ - chdir = /usr/local/searx/searx/ - -Activate the uwsgi application and restart: - -.. code:: sh - - cd /etc/uwsgi/apps-enabled - ln -s ../apps-available/searx.ini - /etc/init.d/uwsgi restart - -Web server -========== - -with nginx ----------- - -If nginx is not installed (uwsgi will not work with the package -nginx-light): - -.. code:: sh - - sudo -H apt-get install nginx - -Hosted at / -~~~~~~~~~~~ - -Create the configuration file ``/etc/nginx/sites-available/searx`` with this -content: - -.. code:: nginx - - server { - listen 80; - server_name searx.example.com; - root /usr/local/searx; - - location / { - include uwsgi_params; - uwsgi_pass unix:/run/uwsgi/app/searx/socket; - } - } - -Create a symlink to sites-enabled: - -.. code:: sh - - sudo -H ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx - -Restart service: - -.. code:: sh - - sudo -H service nginx restart - sudo -H service uwsgi restart - -from subdirectory URL (/searx) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add this configuration in the server config file -``/etc/nginx/sites-enabled/default``: - -.. code:: nginx - - location = /searx { rewrite ^ /searx/; } - location /searx { - try_files $uri @searx; - } - location @searx { - uwsgi_param SCRIPT_NAME /searx; - include uwsgi_params; - uwsgi_modifier1 30; - 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`` - -.. code:: yaml - - base_url : http://your.domain.tld/searx/ - -Restart service: - -.. code:: sh - - sudo -H service nginx restart - sudo -H service uwsgi restart - -disable logs -^^^^^^^^^^^^ - -for better privacy you can disable nginx logs about searx. - -how to proceed: below ``uwsgi_pass`` in ``/etc/nginx/sites-available/default`` -add: - -.. code:: nginx - - access_log /dev/null; - error_log /dev/null; - -Restart service: - -.. code:: sh - - sudo -H service nginx restart - -with apache ------------ - -Add wsgi mod: - -.. code:: sh - - sudo -H apt-get install libapache2-mod-uwsgi - sudo -H a2enmod uwsgi - -Add this configuration in the file ``/etc/apache2/apache2.conf``: - -.. code:: apache - - - Options FollowSymLinks Indexes - SetHandler uwsgi-handler - uWSGISocket /run/uwsgi/app/searx/socket - - -Note that if your instance of searx is not at the root, you should change -```` by the location of your instance, like ````. - -Restart Apache: - -.. code:: sh - - sudo -H /etc/init.d/apache2 restart - -disable logs -~~~~~~~~~~~~ - -For better privacy you can disable Apache logs. - -.. warning:: - - You can only disable logs for the whole (virtual) server not for a specific - path. - -Go back to ``/etc/apache2/apache2.conf`` and above ```` add: - -.. code:: apache - - CustomLog /dev/null combined - -Restart Apache: - -.. code:: sh - - sudo -H /etc/init.d/apache2 restart - -How to update -============= - -.. code:: sh - - cd /usr/local/searx - sudo -H -u searx -i - -.. code:: sh - - (searx)$ . ./searx-ve/bin/activate - (searx)$ git stash - (searx)$ git pull origin master - (searx)$ git stash apply - (searx)$ ./manage.sh update_packages - -.. code:: sh - - sudo -H service uwsgi restart - -Docker -====== - -Make sure you have installed Docker. For instance, you can deploy searx like this: - -.. code:: sh - - docker pull wonderfall/searx - docker run -d --name searx -p $PORT:8888 wonderfall/searx - -Go to ``http://localhost:$PORT``. - -See https://hub.docker.com/r/wonderfall/searx/ for more informations. It's also -possible to build searx from the embedded Dockerfile. - -.. code:: sh - - git clone https://github.com/asciimoo/searx.git - cd searx - docker build -t whatever/searx . - -References -========== - -* https://about.okhin.fr/posts/Searx/ with some additions - -* How to: `Setup searx in a couple of hours with a free SSL certificate - `__ - diff --git a/docs/index.rst b/docs/index.rst index 8fd37cbdc..d9503fef6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,3 +1,4 @@ +================ Welcome to searx ================ @@ -22,37 +23,10 @@ searx can be used over Tor for online anonymity. Get started with searx by using one of the :wiki:`Searx-instances`. If you don't trust anyone, you can set up your own, see :ref:`installation`. - -User documentation ------------------- - -.. toctree:: - :maxdepth: 1 - - user/search_syntax - user/own-instance - -Administrator documentation ---------------------------- - -.. toctree:: - :maxdepth: 1 - - dev/install/installation - admin/api - admin/filtron - admin/morty - blog/blog - -Developer documentation ------------------------ - .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - dev/quickstart - dev/contribution_guide - dev/engine_overview - dev/search_api - dev/plugins - dev/translation + user/index + admin/index + dev/index + blog/index diff --git a/docs/user/index.rst b/docs/user/index.rst new file mode 100644 index 000000000..b13aca216 --- /dev/null +++ b/docs/user/index.rst @@ -0,0 +1,9 @@ +================== +User documentation +================== + +.. toctree:: + :maxdepth: 1 + + search_syntax + own-instance -- cgit v1.2.3