libravatarserv/README.md

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

Libravatar 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 actions (`d` or `default`): 404, URL, mp/mm

The default behaviour for unknown users is to return a 404 error. If a default
image is put in the avatar directory, that is returned instead. The default
image can not be overriden by adding the parameter `d` or `default` to the URL.

Clients are asked to cache results for up to 1 day to reduce load. This can
apply to negative results as well.

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

## 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. If you
want to deliver a default image for unknown email addresses, name it `default`.

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://seccdn.libravatar.org/mm/512.png), 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
```

## Install

### Gentoo

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

### Automatically generated packages

Binary packages are generated automatically for each
[release](https://schlomp.space/tastytea/libravatarserv/releases) in the
formats:

* deb
* rpm
* tar.gz

They are generated on Ubuntu Trusty 64 bit.

### From source

#### Dependencies

* C++ compiler (tested: [gcc](https://gcc.gnu.org/) 5/6/7/8,
  [clang](https://llvm.org/) 5/6)
* [cmake](https://cmake.org/) (at least 3.2)
* [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)

#### Compile

```SH
mkdir build
cd build
cmake ..
make
make install
```

## Contributing

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

## Contact

See https://tastytea.de/

## License & Copyright

```PLAIN
Copyright © 2018 tastytea <tastytea@tastytea.de>.
License GPLv3: GNU GPL version 3 <https://www.gnu.org/licenses/gpl-3.0.html>.
This program comes with ABSOLUTELY NO WARRANTY. This is free software,
and you are welcome to redistribute it under certain conditions.
```