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 8.x
  40 - Elasticsearch 2.0
  41 - MySQL or MariaDB for WebSub subscriptions
  42 - Gearman (Debian 9: ``gearman-job-server``, not ``gearman-server``)
  43 - ``gearadmin`` command line tool (``gearman-tools`` package)
  44 - PHP Gearman extension
  45 - Some PHP libraries that get installed with composer
  46
  47
  48 =====
  49 Setup
  50 =====
  51 #. Install and run Elasticsearch and Gearman
  52 #. Install ``php-gearman`` and ``gearman-tools``
  53 #. Get a local copy of the code::
  54
  55      $ git clone https://git.cweiske.de/phinde.git phinde
  56
  57 #. Install dependencies via composer::
  58
  59      $ composer install --no-dev
  60
  61 #. Point your webserver's document root to phinde's ``www`` directory
  62 #. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it.
  63    Make sure your add your domain to the crawl whitelist.
  64 #. Create a MySQL database and import the schema from ``data/schema.sql``
  65 #. Run ``bin/setup.php`` which sets up the Elasticsearch schema
  66 #. Put your homepage into the queue::
  67
  68      $ ./bin/process.php http://example.org/
  69
  70 #. Start at least one worker to process the crawl+index queue::
  71
  72      $ ./bin/phinde-worker.php
  73
  74 #. Check phinde's status page in your browser.
  75    The number of open tasks should be > 0, the number of workers also.
  76
  77
  78 Re-index when your site changes
  79 ===============================
  80 When your site changed, the search engine needs to re-crawl and re-index
  81 the pages.
  82
  83 Simply tell phinde that something changed by running::
  84
  85     $ ./bin/process.php http://example.org/foo.htm
  86
  87 phinde supports HTML pages and Atom feeds, so if your blog has a feed
  88 it's enough to let phinde reindex that one.
  89 It will find all linked pages automatically.
  90
  91
  92 Website integration
  93 ===================
  94 Adding a simple search form to your website is easy.
  95 It needs two things:
  96
  97 - ``<form>`` tag with an action that points to the phinde instance
  98 - Search text field with name of ``q``.
  99
 100 Example::
 101
 102   <form method="get" action="http://phinde.example.org">
 103     <input type="text" name="q" placeholder="Search text"/>
 104     <button type="submit">Search</button>
 105   </form>
 106
 107
 108 System service
 109 ==============
 110 When using systemd, you can let it run multiple worker instances when
 111 the system boots up:
 112
 113 #. Copy files ``data/systemd/phinde*.service`` into ``/etc/systemd/system/``
 114 #. Adjust user and group names, and the work directories
 115 #. Enable three worker processes::
 116
 117      $ systemctl daemon-reload
 118      $ systemctl enable phinde@1
 119      $ systemctl enable phinde@2
 120      $ systemctl enable phinde@3
 121      $ systemctl enable phinde
 122      $ systemctl start phinde
 123 #. Now three workers are running. Restarting the ``phinde`` service also
 124    restarts the workers.
 125
 126
 127
 128 Cron job
 129 ========
 130 Run ``bin/renew-subscriptions.php`` once a day with cron.
 131 It will renew the WebSub subscriptions.
 132
 133
 134 =====
 135 Howto
 136 =====
 137
 138 Delete index data from one domain::
 139
 140     $ curl -iv -XDELETE -H 'Content-Type: application/json' -d '{"query":{"term":{"domain":"example.org"}}}' http://127.0.0.1:9200/phinde/_query
 141
 142 That's delete-by-query 2.0, see
 143 https://www.elastic.co/guide/en/elasticsearch/plugins/2.0/delete-by-query-usage.html
 144
 145
 146 Subscribe to a website/feed
 147 ===========================
 148 Phinde supports WebSub__ to get subscribe to changes of a website.
 149 When phinde gets notified by the website's hub about changes,
 150 it will immediately crawl and index the changed pages.
 151
 152 Subscribe to a website's feed::
 153
 154     $ php bin/subscribe.php http://example.org/feed.atom
 155
 156 Phinde will determine the website's hub and send a registration request to it.
 157
 158 The status page will show the number of working, and the number of open
 159 subscriptions.
 160
 161 Unsubscribing also happens on command line::
 162
 163     $ php bin/unsubscribe.php http://example.org/feed.atom
 164
 165 __ https://www.w3.org/TR/websub/
 166
 167 ============
 168 About phinde
 169 ============
 170
 171 Source code
 172 ===========
 173 phinde's source code is available from http://git.cweiske.de/phinde.git
 174 or the `mirror on github`__.
 175
 176 __ https://github.com/cweiske/phinde
 177
 178
 179 License
 180 =======
 181 phinde is licensed under the `AGPL v3 or later`__.
 182
 183 __ http://www.gnu.org/licenses/agpl.html
 184
 185
 186 Author
 187 ======
 188 phinde was written by `Christian Weiske`__.
 189
 190 __ http://cweiske.de/