Talk about WebSub
[phinde.git] / README.rst
1 **********************************
2 phinde - generic web search engine
3 **********************************
4 Self-hosted search engine you can use for your static blog or about
5 any other website you want search functionality for.
6
7 My live instance is at http://search.cweiske.de/ and indexes my
8 website, blog and all linked URLs.
9
10
11 ========
12 Features
13 ========
14 - Crawler and indexer with the ability to run many in parallel
15 - Shows and highlights text that contains search words
16 - Boolean search queries:
17
18   - ``foo bar`` searches for ``foo AND bar``
19   - ``foo OR bar``
20   - ``title:foo`` searches for ``foo`` only in the page title
21 - Facets for tag, domain, language and type
22 - Date search:
23
24   - ``before:2016-08-30`` - modification date before that day
25   - ``after:2016-08-30`` - modified after that day
26   - ``date::2016-08-30`` - exact modification day match
27 - Site search
28
29   - Query: ``foo bar site:example.org/dir/``
30   - or use the ``site`` GET parameter:
31     ``/?q=foo&site=example.org/dir``
32 - OpenSearch support with HTML and Atom result lists
33 - Instant indexing with WebSub (formerly PubSubHubbub)
34
35
36 ============
37 Dependencies
38 ============
39 - PHP 5.5+
40 - Elasticsearch 2.0
41 - MySQL or MariaDB for WebSub subscriptions
42 - Gearman (Debian 9: ``gearman-job-server``, not ``gearman-server``)
43 - PHP Gearman extension
44 - Console_CommandLine
45 - Net_URL2
46 - Twig 1.x
47
48
49 =====
50 Setup
51 =====
52 #. Install and run Elasticsearch and Gearman
53 #. Install ``php-gearman``
54 #. Get a local copy of the code::
55
56      $ git clone https://git.cweiske.de/phinde.git phinde
57
58 #. Install dependencies via composer::
59
60      $ composer install
61
62 #. Point your webserver's document root to phinde's ``www`` directory
63 #. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it.
64    Make sure your add your domain to the crawl whitelist.
65 #. Create a MySQL database and import the schema from ``data/schema.sql``
66 #. Run ``bin/setup.php`` which sets up the Elasticsearch schema
67 #. Put your homepage into the queue::
68
69      $ ./bin/process.php http://example.org/
70
71 #. Start at least one worker to process the crawl+index queue::
72
73      $ ./bin/phinde-worker.php
74
75 #. Check phinde's status page in your browser.
76    The number of open tasks should be > 0, the number of workers also.
77
78
79 Re-index when your site changes
80 ===============================
81 When your site changed, the search engine needs to re-crawl and re-index
82 the pages.
83
84 Simply tell phinde that something changed by running::
85
86     $ ./bin/process.php http://example.org/foo.htm
87
88 phinde supports HTML pages and Atom feeds, so if your blog has a feed
89 it's enough to let phinde reindex that one.
90 It will find all linked pages automatically.
91
92
93 Website integration
94 ===================
95 Adding a simple search form to your website is easy.
96 It needs two things:
97
98 - ``<form>`` tag with an action that points to the phinde instance
99 - Search text field with name of ``q``.
100
101 Example::
102
103   <form method="get" action="http://phinde.example.org">
104     <input type="text" name="q" placeholder="Search text"/>
105     <button type="submit">Search</button>
106   </form>
107
108
109 System service
110 ==============
111 When using systemd, you can let it run multiple worker instances when
112 the system boots up:
113
114 #. Copy files ``data/systemd/phinde*.service`` into ``/etc/systemd/system/``
115 #. Adjust user and group names, and the work directories
116 #. Enable three worker processes::
117
118      $ systemctl daemon-reload
119      $ systemctl enable phinde@1
120      $ systemctl enable phinde@2
121      $ systemctl enable phinde@3
122      $ systemctl enable phinde
123      $ systemctl start phinde
124 #. Now three workers are running. Restarting the ``phinde`` service also
125    restarts the workers.
126
127
128
129 Cron job
130 ========
131 Run ``bin/renew-subscriptions.php`` once a day with cron.
132 It will renew the WebSub subscriptions.
133
134
135 =====
136 Howto
137 =====
138
139 Delete index data from one domain::
140
141     $ curl -iv -XDELETE -H 'Content-Type: application/json' -d '{"query":{"term":{"domain":"example.org"}}}' http://127.0.0.1:9200/phinde/_query
142
143 That's delete-by-query 2.0, see
144 https://www.elastic.co/guide/en/elasticsearch/plugins/2.0/delete-by-query-usage.html
145
146
147 Subscribe to a website/feed
148 ===========================
149 Phinde supports WebSub__ to get subscribe to changes of a website.
150 When phinde gets notified by the website's hub about changes,
151 it will immediately crawl and index the changed pages.
152
153 Subscribe to a website's feed::
154
155     $ php bin/subscribe.php http://example.org/feed.atom
156
157 Phinde will determine the website's hub and send a registration request to it.
158
159 The status page will show the number of working, and the number of open
160 subscriptions.
161
162 Unsubscribing also happens on command line::
163
164     $ php bin/unsubscribe.php http://example.org/feed.atom
165
166 __ https://www.w3.org/TR/websub/
167
168 ============
169 About phinde
170 ============
171
172 Source code
173 ===========
174 phinde's source code is available from http://git.cweiske.de/phinde.git
175 or the `mirror on github`__.
176
177 __ https://github.com/cweiske/phinde
178
179
180 License
181 =======
182 phinde is licensed under the `AGPL v3 or later`__.
183
184 __ http://www.gnu.org/licenses/agpl.html
185
186
187 Author
188 ======
189 phinde was written by `Christian Weiske`__.
190
191 __ http://cweiske.de/