Improve readme
[stapibas.git] / README.rst
1 ********
2 stapibas
3 ********
4 The standalone Linkback server, written in PHP.
5
6 - Receives linkbacks (`webmention`__ and `pingbacks`__)
7 - Watches your website's Feed to send out linkbacks to all linked URLs
8
9 Alternative to `Trackback ‘em All`__ and `Telegraph`__
10
11 __ https://www.w3.org/TR/webmention/
12 __ http://www.hixie.ch/specs/pingback/pingback
13 __ http://scott.yang.id.au/code/trackback-em-all/
14 __ https://telegraph.p3k.io/
15
16
17 =================
18 Linkback receiver
19 =================
20 stapibas receives linkbacks (webmentions + pingbacks) for your website
21 and puts them into a database.
22
23 It also sends them as email to a configured address.
24
25
26 Setup
27 =====
28 Let your website send out the following HTTP headers::
29
30   X-Pingback: http://stapibas.example.org/xmlrpc.php
31   Link: '<http://stapibas.example.org/xmlrpc.php>; rel="webmention"'
32
33 In Apache you can do this with the following configuration::
34
35   Header set X-Pingback "http://stapibas.example.org/xmlrpc.php"
36   Header append Link '<http://stapibas.example.org/xmlrpc.php>; rel="webmention"'
37     
38
39 Now, whitelist your domain in the database:
40 Add an ``lt_url`` of ``https://example.org/%`` in the ``linkbacktargets`` table.
41
42 That's all.
43
44 .. note::
45    stapibas does not display the linkbacks in any way - you have to do this yourself.
46
47    If you're looking for a ready-made solution, look at the tools listed
48    on https://indieweb.org/Webmention
49
50
51
52 ===============
53 Linkback sender
54 ===============
55 stapibas is able to send linkbacks out to other websites at behalf of
56 your website.
57
58 It does this by watching your website's Atom (or RSS) feed.
59 Whenever it changes, it fetches the articles that are new or got updated and
60 sends out pingbacks to the remote websites.
61
62 It only works on links that are inside an ``e-content`` section
63 that itself has to be inside a `h-entry`__.
64
65 __ http://microformats.org/wiki/h-entry
66
67
68 Setup
69 =====
70 Add your feed URL::
71
72   $ ./bin/stapibas feed add http://example.org/feed.atom
73
74 Whenever you update your website, tell stapibas about it via a
75 HTTP POST request, sending the feed URL::
76
77   $ curl -d url=http://example.org/feed.atom http://stapibas.example.org/request-feed-update.php
78
79 This tells stapibas to check this feed the next time the pinger runs.
80
81 .. note::
82    stapibas does not check itself if the feed changed!
83
84    You need to notify it manually.
85
86
87 Run the pinger
88 ==============
89 Run stapibas every 5 minutes or every hour to check for feed updates,
90 extract new URLs from the feed and send pingbacks to them.
91
92 ::
93
94    $ php bin/stapibas
95
96  
97 ============
98 Dependencies
99 ============
100 - PHP 5.3+
101 - PDO
102 - `Console_CommandLine`__
103 - `Net_URL2`__
104 - `HTTP_Request2`__
105 - `PEAR2 Services_Linkback`__
106 - `SimplePie`__
107
108 __ http://pear.php.net/package/Console_CommandLine
109 __ http://pear.php.net/package/Net_URL2
110 __ http://pear.php.net/package/HTTP_Request2
111 __ https://github.com/pear2/Services_Linkback
112 __ http://simplepie.org/
113