Add composer.json so we can validate php extension requirements

[surrogator.git] / README.rst

diff --git a/README.rst b/README.rst
index 557e7a003e5b7d05b1e1999e1bfde4ebf7d2bc95..6f3575fb5660f6bb5ffc6e23ba427fa6e623b6e6 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -4,8 +4,21 @@ Surrogator
 
 Simple open source Libravatar__ compatible avatar image server written in PHP.
 
-__ http://wiki.libravatar.org/api/
+Features:
+
+- Delivers images for email addresses and OpenIDs
+- 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.
+- Supports the ``mm`` fallback image (mystery man)
+
+__ https://www.libravatar.org/
+
+Homepage: `sf.net/p/surrogator`__
 
+__ https://sourceforge.net/p/surrogator/
 
 =====
 Setup
@@ -14,7 +27,7 @@ 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``
+3. (optional) 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``.
@@ -41,7 +54,13 @@ Usage
 1. Put images in ``raw/`` folder.
    Name has to be email address + image file extension, for example
    ``foo@example.org.png``.
-   Surrogator supports ``.png`` and ``.jpg``.
+   Surrogator supports ``.png``, ``.jpg`` and ``svg`` files.
+
+   For OpenIDs, use the url-encoded URL + extension as filename, for example
+   replace ``/`` with ``%2F``.
+   The filename for ``http://example.org/~foo`` would be
+   ``http:%2F%2Fexample.org%2F~foo.jpg``.
+
 2. Run ``php surrogator.php``.
    The small files get generated.
 3. You will get more information with ``-v``
@@ -49,6 +68,27 @@ Usage
    when the raw file is newer than the "square" file in the var folder.
    You can force the update with ``--force``.
 
+Note: PHP imagick extension is required for ``svg`` files.
+
+
+====
+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
+
+See the libravatar wiki about `running a custom server`__ and
+the `API specification`__ for more information.
+
+__ http://wiki.libravatar.org/running_your_own/
+__ http://wiki.libravatar.org/api/
+
 
 =======
 License