tastytea
3433f88dcc
All checks were successful
continuous-integration/drone/push Build is passing
See <https://cwe.mitre.org/data/definitions/601.html>.
172 lines
5.4 KiB
Markdown
172 lines
5.4 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 (only on the same server), 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
|
|
* Fallback URLs for to external sites (due to [CWE-601](https://cwe.mitre.org/data/definitions/601.html))
|
|
* We have a server setting (`LIBRAVATARSERV_REDIRECT_*`) to redirect to
|
|
libravatar.org.
|
|
|
|
## 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/
|