README.rst

   1 **********
   2 Surrogator
   3 **********
   4
   5 Simple open source Libravatar__ compatible avatar image server written in PHP.
   6
   7 __ http://wiki.libravatar.org/api/
   8
   9
  10 =====
  11 Setup
  12 =====
  13
  14 1. Copy ``data/surrogator.config.php.dist`` to ``data/surrogator.config.php``
  15    (remove the ``.dist``)
  16 2. Adjust the config file to your needs
  17 3. Create a default image and put it into the raw folder, name it ``default.png``
  18 4. Setup your web server and set the document root to the ``www/`` directory.
  19    Make sure you allow the ``.htaccess`` file and have ``mod_rewrite`` activated.
  20 5. Add DNS entries for ``_avatars._tcp`` and ``_avatars-sec._tcp``.
  21    A bind config file excerpt would look like this::
  22
  23     _avatars._tcp.example.org.     IN SRV 0 0 80  avatars.example.org
  24     _avatars-sec._tcp.example.org. IN SRV 0 0 443 avatars.example.org
  25
  26    This makes the avatar server ``avatars.example.org`` responsible for
  27    the domain ``example.org``, on ports 80 (HTTP) and 443 (HTTPS).
  28
  29 It is possible to use an existing domain as avatar server.
  30 Just copy ``avatar.php`` into its document root dir and copy the rewrite rule
  31 from ``.htaccess`` into the domain's ``.htaccess`` file if one exists.
  32 If not, copy the whole ``.htaccess`` file.
  33 After that, you have to point the ``$cfgFile`` path at the beginning of
  34 the ``avatar.php`` file to the correct location.
  35
  36
  37 =====
  38 Usage
  39 =====
  40
  41 1. Put images in ``raw/`` folder.
  42    Name has to be email address + image file extension, for example
  43    ``foo@example.org.png``.
  44    Surrogator supports ``.png`` and ``.jpg``.
  45 2. Run ``php surrogator.php``.
  46    The small files get generated.
  47 3. You will get more information with ``-v``
  48 4. When you run ``surrogator.php`` again, it will only generate small files
  49    when the raw file is newer than the "square" file in the var folder.
  50    You can force the update with ``--force``.
  51
  52
  53 =======
  54 License
  55 =======
  56 Surrogator is licensed under the `AGPL v3`__ or later.
  57
  58 __ http://www.gnu.org/licenses/agpl.html
  59
  60
  61 ======
  62 Author
  63 ======
  64 Written by Christian Weiske, cweiske@cweiske.de