handle default=mm requests

[surrogator.git] / README.rst

diff --git a/README.rst b/README.rst
index f4aaba4db0ea493b28facbe47670e6d1d19b87c2..3c219e95bb1147e00db4635e5d0b0a16340e0f3e 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -2,17 +2,85 @@
 Surrogator
 **********
 
-Open source Libravatar__ compatible avatar image server written in PHP.
+Simple open source Libravatar__ compatible avatar image server written in PHP.
+
+Features:
+
+- Delivers images for email addresses
+- Very easy to setup.
+- No graphics processing is done on the server, keeping the CPU load low.
+  All avatar images get pre-generated for a set of sizes
+- If no image at the user requested size is found, the next larger image gets
+  returned.
 
 __ http://wiki.libravatar.org/api/
 
 
+=====
+Setup
+=====
+
+1. Copy ``data/surrogator.config.php.dist`` to ``data/surrogator.config.php``
+   (remove the ``.dist``)
+2. Adjust the config file to your needs
+3. Create a default image and put it into the raw folder, name it ``default.png``
+4. Setup your web server and set the document root to the ``www/`` directory.
+   Make sure you allow the ``.htaccess`` file and have ``mod_rewrite`` activated.
+5. Add DNS entries for ``_avatars._tcp`` and ``_avatars-sec._tcp``.
+   A bind config file excerpt would look like this::
+
+    _avatars._tcp.example.org.     IN SRV 0 0 80  avatars.example.org
+    _avatars-sec._tcp.example.org. IN SRV 0 0 443 avatars.example.org
+
+   This makes the avatar server ``avatars.example.org`` responsible for
+   the domain ``example.org``, on ports 80 (HTTP) and 443 (HTTPS).
+
+It is possible to use an existing domain as avatar server.
+Just copy ``avatar.php`` into its document root dir and copy the rewrite rule
+from ``.htaccess`` into the domain's ``.htaccess`` file if one exists.
+If not, copy the whole ``.htaccess`` file.
+After that, you have to point the ``$cfgFile`` path at the beginning of
+the ``avatar.php`` file to the correct location.
 
-Steps
+
+=====
+Usage
 =====
 
 1. Put images in ``raw/`` folder.
    Name has to be email address + image file extension, for example
    ``foo@example.org.png``.
-2. Generate/update big square files.
-3. Generate images for each size that is defined in ``$sizes``.
+   Surrogator supports ``.png`` and ``.jpg``.
+2. Run ``php surrogator.php``.
+   The small files get generated.
+3. You will get more information with ``-v``
+4. When you run ``surrogator.php`` again, it will only generate small files
+   when the raw file is newer than the "square" file in the var folder.
+   You can force the update with ``--force``.
+
+
+====
+Test
+====
+
+To check if everything is setup correctly, try the following tools:
+
+- `Libravatar domain check tool`__ for DNS resolution tests
+- `Libravatar server check tool`__ for image resolving tests
+
+__ https://www.libravatar.org/tools/check_domain
+__ https://www.libravatar.org/tools/check
+
+
+=======
+License
+=======
+Surrogator is licensed under the `AGPL v3`__ or later.
+
+__ http://www.gnu.org/licenses/agpl.html
+
+
+======
+Author
+======
+Written by Christian Weiske, cweiske@cweiske.de