186 lines
5.4 KiB
Markdown
186 lines
5.4 KiB
Markdown
**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.
|
|
```
|