README.md (4491B)
1 # serĉi
2
3 Search the web with `!keywords`.
4
5 Please send patches or remarks to
6 [jayvii+serci[AT]posteo[DOT]de](mailto:jayvii+serci[AT]posteo[DOT]de).
7
8 ## FAQs
9
10 ### What does serĉi mean?
11
12 It is the Esperanto term for
13 ["to search"](https://m.dict.cc/esperanto-english/ser%C4%89i.html).
14
15 ### What are `!keywords`?
16
17 An idea lent from the search Engine [DuckDuckGo](https://duckduckgo.com/bangs),
18 which has been utilized by many others since. They call their keywords *bangs*,
19 but it is the same concept and usability:
20
21 > bangs are shortcuts that quickly take you to search results on other sites.
22 > For example, when you know you want to search on another site like Wikipedia
23 > or Amazon, our bangs get you there fastest. A search for !w filter bubble will
24 > take you directly to Wikipedia.
25 >
26 > Remember, though, because your search is actually taking place on that other
27 > site, you are subject to that site’s policies, including its data collection
28 > practices.
29 >
30 > We’ve had bangs since 2008 as part of our geek roots. Now we have thousands of
31 > !bangs and you can even submit your own.
32
33 serĉi implements keywords for all kinds of search engine and transparently
34 redirects you right to them. The default set of search engine and fall-backs
35 is geared towards privacy and data minimalism. However, you can simply host
36 serĉi yourself any time and configure your own favorite search engines and
37 `!keywords`.
38
39 If you think there are `!keywords` that other people would benefit from, feel free
40 to contribute!
41
42 ### How can I use serĉi?
43
44 - You can try serĉi on [search.jayvii.de](https://search.jayvii.de). Or
45 host it yourself! It barely needs any server resources, no database or lots
46 of RAM. serĉi has minimal footprint (also on user data: there are NONE).
47 - Either type your search directly into the search bar of the serĉi
48 webfrontend or add the search to your browser by rightclicking in the
49 URL-bar and choosing `add serĉi - Search with !keywords`.
50 - Some browsers (for example Firefox on Android / Fennec) allow to configure
51 custom search engines via search URL. Simply list
52 `https://search.jayvii.de/?query=%s` (or whatever serĉi host you want to
53 use).
54 - Please do not abuse my open search site search.jayvii.de and try to host
55 serĉi yourself, if you can. There is no guarantee, my site is always
56 online or will be continued indefinitely.
57
58 ## Hosting
59
60 Simply upload the entire content of this repository to your webhost. Edit
61 `opensearch.xml` accordingly. If the domain you want to run serĉi under is
62 `search.example.com`, you can simply run:
63
64 ```bash
65 sed -e 's/%%URL%%/http:\/\/search.example.com/g' -i opensearch.xml
66 ```
67
68 Search-Engines and `!keywords` are configured in `config/config.php`. For fast
69 access to `!keywords` and categories, seriĉi uses mappings written to `json`
70 files. Before first run, you need to generate them from your config via
71 `lib/generate_mappings.php`. This needs to be re-run everytime you adjust your
72 `config/config.php`.
73
74 ```bash
75 php lib/generate_mappings.php
76 ```
77
78 Speed-Deployment:
79 ```bash
80 DOMAIN="search.example.com"
81 mkdir -p /var/www/serci && \
82 cd /var/www/serci && \
83 wget https://src.jayvii.de/pub/serci/exports/main.tar.gz -O - | \
84 tar xfvz - && \
85 sed -e "s/%%URL%%/https:\/\/${DOMAIN}/g" -i opensearch.xml && \
86 php lib/generate_mappings.php
87 ```
88
89 Example-configuration for Apache2:
90
91 ```apache
92 <VirtualHost *:80>
93 # server name and directory
94 ServerAdmin webmaster[AT]example[DOT]com
95 ServerName search.example.com
96 DocumentRoot /var/www/serci
97
98 # log- and error files
99 ErrorLog ${APACHE_LOG_DIR}/search.example.com_error.log
100 LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" custom
101 CustomLog ${APACHE_LOG_DIR}/search.example.com.log custom
102
103 # do not allow file browsing
104 Options -Indexes
105
106 </VirtualHost>
107 ```
108
109 ## Testing
110
111 There are test scripts in place to test the validity of your configuration.
112 Tests may be conducted to check:
113
114 1. Whether all categories assigned to search engines are defined themselves
115 2. Whether all defined categories have at least one search engine assigned to
116 them
117 3. Whether all keywords are unique, i.e. no keyword is assigned to multiple
118 search engines
119
120 ```bash
121 php tests/categories.php
122 php tests/keywords.php
123 ```
124
125 ## License
126
127 serĉi is under the AGPL-3.0 license. It is [REUSE](https://reuse.software)
128 compliant!
129
130 Icons are licensed under CC-BY-SA-4.0.
131
132 Other bundled assets are:
133
134 - [simple.css](https://simplecss.org/): MIT License (c) Kev Quirk
