libravatarserv/README.md

**libravatarserv** is a simple libravatar server.
It is intended to be used as a
[CGI](https://en.wikipedia.org/wiki/Common_Gateway_Interface) program.

[Libravatar](https://www.libravatar.org/) is a free service and an open
specification for hosting profile images tied to email or OpenID addresses.

## Features

* Avatar delivery based on email addresses
* Default avatar for unknown addresses
* MD5 hashes
* SHA256 hashes
* Variable image size (`s` or `size`)
* Default fallbacks (`d` or `default`): 404, URL, mp/mm, identicon, retro

The API is explained in greater detail at the
[Libravar wiki](https://wiki.libravatar.org/api/).

### Not supported

* OpenID
  * Because it isn't possible to store filenames with '/' in it on most filesystems.
* The default fallbacks monsterid, wavatar, robohash and pagan
  * Patches welcome
* forcedefault

## Usage

Install nginx and
[fcgiwrap](https://www.nginx.com/resources/wiki/start/topics/examples/fcgiwrap/),
copy the [example config](https://schlomp.space/tastytea/libravatarserv/src/branch/master/doc/nginx-example.conf)
to the nginx configuration directory and edit it according to your needs. Other
webservers and cgi spawners will also work, of course.

Add the following DNS records to your nameserver:
``` plain
_avatars._tcp.example.com.     IN SRV 0 0 80  avatars.example.com
_avatars-sec._tcp.example.com. IN SRV 0 0 443 avatars.example.com
```

`_avatars._tcp.example.com` is for HTTP, `_avatars-sec._tcp.example.com` is for
HTTPS.

libravatarserv looks in each of `${XDG_DATA_DIRS}` for a directory named
`libravatarserv`. You can force a different directory by setting the environment
variable `LIBRAVATARSERV_DIR` (until 0.3.0 `AVATAR_DIR`).

The image files are named like your email address, no file extension. The
default behaviour for unknown users is to return a 404 error. You can change
that by setting the environment variable `LIBRAVATARSERV_DEFAULT_FALLBACK` to
any value accepted by `d` or `default`. If you want to force a default image for
unknown email addresses, name it `default`. The default image overrides the
specified fallback in the URL and in the environment variable.

If you want to support "Mystery persons" (mp/mm) as default avatars, place a
file named `mp` in the avatar dir. You can use the
[default libravatar mystery person](https://git.linux-kernel.at/oliver/ivatar/raw/master/ivatar/static/img/mm.png)
([SVG](https://git.linux-kernel.at/oliver/ivatar/raw/master/ivatar/static/img/mm.svg)),
for example.

Test your setup on <https://www.libravatar.org/tools/check/>.

### Example

The avatar directory could look like this:
``` plain
/usr/share/libravatarserv
├── [ 32K]  default
├── [ 759]  user@example.com
└── [  16]  user+newsletter@example.com -> user@example.com
```

### Configuration

Configuration is done through environment variables.

**LIBRAVATARSERV_DIR**

The directory containing the avatars.

Default: empty

**LIBRAVATARSERV_DEFAULT_FALLBACK**

Controls what happens if no fallback was requested.
Possible values: Anything that can be supplied with the `d` or `default`
parameter.

Default: 404

**LIBRAVATARSERV_REDIRECT_NOFALLBACK**

Set to 1 to redirect to libravatar.org if the user is not found and the
requested fallback is not supported.

Default: 0

**LIBRAVATARSERV_REDIRECT_NOUSER**

Set to 1 to redirect to libravatar.org if the user is not found.

Default: 0

### Things to keep in mind

libravatarserv resizes images on the fly and calculates both MD5 and SHA256
hashes for every user on every request. This could seriously strain the
ressources of your computer if many users use the service. Make sure to set up
caching if you expect more than occasional traffic.

## Install

### Gentoo

Gentoo ebuilds are available via my
[repository](https://schlomp.space/tastytea/overlay).

### From source

#### Dependencies

* C++ compiler (tested: [gcc](https://gcc.gnu.org/) 8/9,
  [clang](https://llvm.org/) 7)
* [cmake](https://cmake.org/) (at least 3.10)
* [crypto++](https://cryptopp.com) (tested: 7.0 / 5.6)
* [imagemagick](https://www.imagemagick.org/) (tested: 7.0 / 6.7)
* [libxdg-basedir](http://repo.or.cz/w/libxdg-basedir.git) (tested: 1.2)
* [identiconpp](https://schlomp.space/tastytea/identiconpp) (at least: 0.7.1)

On a Debian system, install the packages: `build-essential cmake libcrypto++-dev
libmagick++-dev libxdg-basedir-dev` and
[identiconpp](https://schlomp.space/tastytea/identiconpp).

#### Compile

``` shell
mkdir build && cd build
cmake ..
make
make install
```

##### cmake options

* `-DCMAKE_BUILD_TYPE=Debug` for a debug build
* One of:
    * `-DWITH_DEB=YES` to generate a deb-package
    * `-DWITH_RPM=YES` to generate an rpm-package

To generate a binary package, execute `make package`

## Contributing

Contributions are always welcome. You can submit them as pull requests or via
email to `tastytea`@`tastytea.de`.

## Speed

Tests on a laptop with an x86_64 2GHz CPU with 2 cores showed that the average
response time is 140ms with 3 avatars in the "database", 180ms with 1003
avatars. The tests were done with a 27KiB image, scaled down from 569px to
512px. It took 3,8s / 5-7s to transfer 50 unique avatars (about 3 KiB each) on
one page.

## Contact

See https://tastytea.de/