add support for OpenID, prepare 0.2.0
[surrogator.git] / README.rst
1 **********
2 Surrogator
3 **********
4
5 Simple open source Libravatar__ compatible avatar image server written in PHP.
6
7 Features:
8
9 - Delivers images for email addresses and OpenIDs
10 - Very easy to setup.
11 - No graphics processing is done on the server, keeping the CPU load low.
12   All avatar images get pre-generated for a set of sizes
13 - If no image at the user requested size is found, the next larger image gets
14   returned.
15 - Supports the ``mm`` fallback image (mystery man)
16
17 __ https://www.libravatar.org/
18
19 Homepage: `sf.net/p/surrogator`__
20
21 __ https://sourceforge.net/p/surrogator/
22
23 =====
24 Setup
25 =====
26
27 1. Copy ``data/surrogator.config.php.dist`` to ``data/surrogator.config.php``
28    (remove the ``.dist``)
29 2. Adjust the config file to your needs
30 3. (optional) Create a default image and put it into the raw folder, name it ``default.png``
31 4. Setup your web server and set the document root to the ``www/`` directory.
32    Make sure you allow the ``.htaccess`` file and have ``mod_rewrite`` activated.
33 5. Add DNS entries for ``_avatars._tcp`` and ``_avatars-sec._tcp``.
34    A bind config file excerpt would look like this::
35
36     _avatars._tcp.example.org.     IN SRV 0 0 80  avatars.example.org
37     _avatars-sec._tcp.example.org. IN SRV 0 0 443 avatars.example.org
38
39    This makes the avatar server ``avatars.example.org`` responsible for
40    the domain ``example.org``, on ports 80 (HTTP) and 443 (HTTPS).
41
42 It is possible to use an existing domain as avatar server.
43 Just copy ``avatar.php`` into its document root dir and copy the rewrite rule
44 from ``.htaccess`` into the domain's ``.htaccess`` file if one exists.
45 If not, copy the whole ``.htaccess`` file.
46 After that, you have to point the ``$cfgFile`` path at the beginning of
47 the ``avatar.php`` file to the correct location.
48
49
50 =====
51 Usage
52 =====
53
54 1. Put images in ``raw/`` folder.
55    Name has to be email address + image file extension, for example
56    ``foo@example.org.png``.
57    Surrogator supports ``.png`` and ``.jpg``.
58
59    For OpenIDs, use the url-encoded URL + extension as filename, for example
60    replace ``/`` with ``%2F``.
61    The filename for ``http://example.org/~foo`` would be
62    ``http:%2F%2Fexample.org%2F~foo.jpg``.
63
64 2. Run ``php surrogator.php``.
65    The small files get generated.
66 3. You will get more information with ``-v``
67 4. When you run ``surrogator.php`` again, it will only generate small files
68    when the raw file is newer than the "square" file in the var folder.
69    You can force the update with ``--force``.
70
71
72 ====
73 Test
74 ====
75
76 To check if everything is setup correctly, try the following tools:
77
78 - `Libravatar domain check tool`__ for DNS resolution tests
79 - `Libravatar server check tool`__ for image resolving tests
80
81 __ https://www.libravatar.org/tools/check_domain
82 __ https://www.libravatar.org/tools/check
83
84 See the libravatar wiki about `running a custom server`__ and
85 the `API specification`__ for more information.
86
87 __ http://wiki.libravatar.org/running_your_own/
88 __ http://wiki.libravatar.org/api/
89
90
91 =======
92 License
93 =======
94 Surrogator is licensed under the `AGPL v3`__ or later.
95
96 __ http://www.gnu.org/licenses/agpl.html
97
98
99 ======
100 Author
101 ======
102 Written by Christian Weiske, cweiske@cweiske.de