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
  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 2. Run ``php surrogator.php``.
  59    The small files get generated.
  60 3. You will get more information with ``-v``
  61 4. When you run ``surrogator.php`` again, it will only generate small files
  62    when the raw file is newer than the "square" file in the var folder.
  63    You can force the update with ``--force``.
  64
  65
  66 ====
  67 Test
  68 ====
  69
  70 To check if everything is setup correctly, try the following tools:
  71
  72 - `Libravatar domain check tool`__ for DNS resolution tests
  73 - `Libravatar server check tool`__ for image resolving tests
  74
  75 __ https://www.libravatar.org/tools/check_domain
  76 __ https://www.libravatar.org/tools/check
  77
  78 See the libravatar wiki about `running a custom server`__ and
  79 the `API specification`__ for more information.
  80
  81 __ http://wiki.libravatar.org/running_your_own/
  82 __ http://wiki.libravatar.org/api/
  83
  84
  85 =======
  86 License
  87 =======
  88 Surrogator is licensed under the `AGPL v3`__ or later.
  89
  90 __ http://www.gnu.org/licenses/agpl.html
  91
  92
  93 ======
  94 Author
  95 ======
  96 Written by Christian Weiske, cweiske@cweiske.de