searx-qt
Lightweight desktop application for searx
This is documentation for searx-qt version 0.2
Index
About
Summary
searx-qt is a lightweight desktop application that lets you search on public searx instances listed on https://searx.space.
Technically searx-qt is a client application that does magic with the searx API and searx-stats2 it's instances.json.
Since version 0.2 it is also possible to manage your own (private?) instances.
searx
Actual search requests will be made to a server running searx software, there are many public available. We call such servers 'searx instances' or in this document we may refer to just 'instance(s)'.
If you are not familiar with the searx project; you can checkout their page here: https://asciimoo.github.io/searx/ or https://searx.me/
- API Docs: https://asciimoo.github.io/searx/dev/search_api.html
- Source: https://github.com/asciimoo/searx
- License: GPLv3
searx-stats2
The searx-stats2 project lists public searx instances with statistics. The original searx-stats2 instance is running at https://searx.space/. This is where searx-qt will request a list with instances when the update button is pressed.
- Source: https://github.com/dalf/searx-stats2
- License: GPLv3
License
Dependencies
| name | version | license | URL |
|---|---|---|---|
| python | 3 | PSFL | https://docs.python.org/3/license.html |
| requests | Apache 2 | http://docs.python-requests.org/en/master/ | |
| PyQt5 | GPLv3 | https://www.riverbankcomputing.com/software/pyqt/intro | |
| urllib3 | MIT | https://urllib3.readthedocs.io/ |
Optional for socks proxy support:
| name | version | license | URL |
|---|---|---|---|
| pysocks | BSD | https://github.com/Anorov/PySocks |
Translations
Since version 0.2 searx-qt is able (application-wise, not search results) to be fully translated with the use of gettext and .po .pot files. However there are no translations yet. If you like to translate searx-qt in your language please let me know.
Contact
One option is to open a issue on https://notabug.org/cyberdevil/searx-qt. Another is to see if I'm (CYBERDEViL) am online at #searx-qt on irc.freenode.net.
Getting started
Install dependencies
Note: python-requests is also dependent on python-urllib3 ; so python-urllib3 will be installed with python-requests (No need to do a explicit install).
Debian / Ubuntu based
Install required dependencies:
# apt update # apt upgrade # apt install python3 python3-requests python3-pyqt5
Optional for socks proxy support:
# apt install python3-socks
Arch based
Install required dependencies:
# pacman -Syu python python-requests python-pyqt5
Optional for socks proxy support:
# pacman -S python-pysocks
Installation
It is always recommended to let the package-manager of your system do the installing of software, so your package-manager will keep track of files installed. Only use setup.py directly if you know what you are doing.
Since searx-qt isn't available in any GNU/Linux distribution (yet?); the best option is to create a package for your distribution yourself from the latest release. This will also mean that you have to manually update searx-qt if there is a new version available.
Note: https://notabug.org/CYBERDEViL/searx-qt/releases
Note: noticed the # or $ before every command? When there is a $ before the command, it should be run as a regular user. # as root.
Debian based
The steps below describe how to get a specific version of searx-qt; then package and install it. This method is available from version 0.1-beta2 and up.
Make sure you have python3-stdeb and git installed:
# apt install python3-stdeb git
Creating a working directory and cd in to it, you may change this to your own preference:
$ mkdir ~/git $ cd ~/git
Cloning the repository and cd in to it:
$ git clone "https://notabug.org/CYBERDEViL/searx-qt.git" "searx-qt" $ cd searx-qt
Checkout a specific version:
Note: get a list with available tags (versions) with the git tag command.
Below is a example to checkout version 0.1-beta2:
$ git checkout 0.1-beta2
Create .deb:
$ ./utils/gen_deb.sh
Install the created package:
# dpkg -i ./deb_dist/python3-searx-qt_0.1-beta2-1_all.deb
Arch based
For Arch based distributions there is a package available in the AUR; https://aur.archlinux.org/packages/searx-qt/
Make sure you have git installed:
# pacman -S git
Creating a working directory and cd in to it, you may change this to your own preference:
$ mkdir ~/pkg $ cd ~/pkg
Getting the PKGBUILD from Arch AUR:
$ git clone https://aur.archlinux.org/searx-qt.git $ cd searx-qt
Build and install searx-qt package:
$ makepkg -si
Usage
Profiles
Profiles are useful when you want to have different settings and/or data without to having to set it manually every-time. For example you can create a profile named Tor which has different proxy and stats2 settings then you normal profile.
- There are two types of profiles:
- Stats2 profile
- User profile
The profile type names maybe changed to something better, suggestions are welcome.
Create a Stats2 profile if you wish to get/update a list of searx-instances from a searx-stats2 instance. For example the default https://searx.space.
Create a User profile if you wish to add/remove/update your own list with searx-instances.
NOTE: Profile types cannot be changed after the creation of the profile,but you can add multiple profiles of both types.
Creating new profile
On first usage of searx-qt you will need to create a new profile. The Add button (of the "Profile select" window) will open a dialog to do so.
Deleting a profile
I hope that it is self explanatory that the Delete button of the "Profile select" window deletes the currently selected profile, it will ask for confirmation before doing so.
It is not possible to delete a active profile (at-least it shouldn't ;-)).
Settings
Connection
Verify (SSL)
Request will fail on a invalid SSL/TLS certificate.
Leave checked if unsure.
See https://requests.readthedocs.io/en/master/user/advanced/#ssl-cert-verification for a more technical description.
Timeout
Timeout in seconds for a single request.
Leave it at the default value of 10 seconds if unsure.
See https://requests.readthedocs.io/en/master/user/advanced/#timeouts for a more technical description.
Proxy
Here you can set a proxy that will be used for every connection searx-qt makes. Leave the input field blank to use no proxy.
The 'Http' section can be used to proxy plain http:// requests to for example instances without a certificate. The 'Https' section can be used to proxy all https:// requests to instances (including fetching the instances list data from https://searx.space) with a certificate. So you can use a separate proxy for both protocols.
If you use a socks4 or socks5 proxy you probably want to make sure the 'Proxy DNS' checkbox is checked so DNS requests will also go through the proxy. DNS proxy is not available for a http proxy type.
User-agents
What user-agent string should searx-qt send?
After pressing the Edit button it will change to a Save button, you will be able to edit the user-agent ?string(s) searx-qt will send. Some notes:
- One user-agent string per line.
- Set total blank to not send any user-agent string.
When the Random checkbox is checked and there are multiple user-agent strings set then searx-qt will pick a random user-agent string from the list for every request.
searx-stats2
Here you can change the URL of the searx-stats2 instance you like to use for fetching the instances data.
NOTE: This is only available for a Stats2 profile type.
Instances
A searx instance is a server running the searx project. Since we want to preform searches to searx instance(s) we need addresses of those instance(s).
The interface to manage instances is on the right.
With Stats2 profile type
If your profile is a Stats2 type, the searx-instances will be fetched from https://searx.space/data/instances.json. The instances.json from search.space also contains a lot of other data about the instances it lists (which we can use to filter instances based on our preferences).
If searx-qt is used for the first time you will need to update the instances table. There is a 'Update' button between the Filter and the Table that can be used for this. searx-qt will not update this automatically!
It maybe useful to update the instances data so now and then since public instances appear, disappear and their stats change over time.
With User profile type
If your profile is a User type you will have to add addresses of instances manually.
This can be done by pressing the Add instance button right above the instances table, a dialog will pop-up asking for the address to add (without scheme).
The scheme (http:// or https://) can be selected from the combobox.
There is also a "Update data on add" checkbox, when this is checked and Add is pressed it will automatically download data from http(s)://your-address/config. Downloading/updating this data may also be done later by right clicking on a (or multiple) searx-instances in the table and pressing Update selected.
Instances table
The instances table can be used to browse instances with their data that remain after all filters. The table is also used to set the current instance by left-clicking on one.
The currently used instance should also be visible bottom right in the application it's status-bar.
Right-clicking in the table opens a context-menu from where you can do the following:
- Whitelist/blacklist selected instance(s).
- Copy selected instance(s) it's/their URL(s).
- Select All instances (CTRL+A should do the same).
- Hide or show columns.
If your profile is a User profile the context-menu will have the following extra actions:
- Remove selected instance(s).
- Update selected instance(s).
Filter instances
When a filter is enabled and the instance it's value that is being matched is unknown then it is excluded by default!
Network
Filter instances on network type. Only instances that match one of the checked network types remain.
Require ASN privacy
Excludes instances that run their server at a known malicious network. Like for example CloudFlare, Google, Akamai etc..
This does not give any guarantee, it only filters known privacy violators!
For a full list of known malicious networks (technical): https://github.com/dalf/searx-stats2/blob/master/searxstats/data/asn.py
Require IPv6
Exclude instances that don't have at least one IPv6 address.
Version
Include only instances that have a searx version that has been added to this widget. Leave empty to allow all searx versions.
Blacklist
Here are the URLs of the instances that have been manually blacklisted. There is a button right to each blacklist item to remove it from the blacklist.
You can manually blacklist a instance by right clicking on a instance in the instances table and click 'Add to blacklist'; multiple instances can be blacklisted at once.
Blacklisted instances will be excluded from the table by default.
Whitelist
Here are the URLs of the instances that have been manually whitelisted. There is a button right to each whitelist item to remove it from the whitelist.
You can manually whitelist a instance by right clicking on a instance in the instances table and click 'Add to whitelist'; multiple instances can be whitelisted at once.
Whitelisted instances will be in the table by default.
Search
Search bar
Fallback
If checked it will pick a random instance from the instances table if a search request fails one way or another and re-try the same request with the freshly picked instance. There is a maximum amount of 10 tries (10 different instances to try the same request on).
What is fail?
- Connection errors including timeout.
- Wrong status code (not 200).
- No or malformed results returned.
Random every
If checked it will automatically pick a random instance on a search request, it will also hide the 'Random search button' because it makes it obsolete.
If not checked it will do search requests on the same instance unless the request fails somehow and 'Fallback' is checked. Exception is when the 'Random search button' is used for the search request.
Random search button
When pressed it will pick a random instance from the list and preform the search request.
Reload button
When pressed it basically preforms a search request without 'Fallback' whenever it is enabled or not, it also doesn't reset the page number. So it can act as a reload button thus it's name, but it does more.
Note: When a search argument like the search query, instance URL, categories/engines etc. has changed by user interaction it will do the request with those changes, that isn't a real reload of the previous request.
Dev-note: Probably this behavior should change or the name/icon should change to something more fitting.
Search button
Preform a search request on the currently selected instance.
Page number is reset, 'Fallback' and 'Random Every' options are honored.
Search query input
The query you like to search for.
See https://asciimoo.github.io/searx/user/search_syntax.html for what is possible.
It will do a search request on enter key pressed, same behavior as when the 'Search button' has been pressed.
Search options
Right clicking in (on the picture above) the dark area opens a context-menu where you can manage what options you want to be visible or not as shown in the image below.
Categories
A category is basically a collection of engines. When a category gets checked then all the engines it represents will also be checked which in turn will filter out all searx-instances that don't have at least one of the checked engines enabled.
Multiple categories may be selected.
The default (non-editable) categories will be compiled from categories listed in engines. Besides default categories there is also a option to create custom categories.
Engines
Here you can toggle what search engines should be enabled. It will automatically filter out all instances from the instances table that doesn't have at least one of the checked engines enabled. The checked engines will be send with a search request to a searx instance with the enabled_engines param. You should only get results from engines that are checked.
If no engine is checked it means that it may return results of any engine in the list.
The list with engines is created with data from the instances table, so only engines are listed that are available from the instances table.
Period
Search period you like results from. Options are Last day, Last week, Last month or Last year.
Language
If you want results in a specific language than you can select one here.