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

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 a default image is put in the avatar
directory, that is returned instead. The default image can not be overridden 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/).

### Not supported

* OpenID
  * Because it isn't possible to store filenames with '/' in it on most filesystems.
* The default fallbacks monsterid, wavatar and retro
  * Because I don't think anyone uses them?
  * Patches welcome

## 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
```

### 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 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 does not cache anything. It also
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.

## 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 Debian Stretch 64 bit and signed with my
[automatic signing key](https://tastytea.de/tastytea_autosign.asc).

Up to and including 0.6.2, the packages were generated on Ubuntu 16.04 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)

On a Debian system, install the packages: `build-essential cmake libcrypto++-dev
libmagick++-dev libxdg-basedir-dev`.

#### Compile

```SH
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`.

## 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.
```