forked from tastytea/libravatarserv
197 lines
5.9 KiB
Markdown
197 lines
5.9 KiB
Markdown
**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
|
|
|
|
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. 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://seccdn.libravatar.org/mm/512.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 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.
|
|
|
|
The algorithm for identicon generation has not been thoroughly tested. The
|
|
generated images are maybe not individual enough. Please open a bug report if
|
|
that is the case.
|
|
|
|
## 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`.
|
|
|
|
## 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/
|
|
|
|
## 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.
|
|
```
|