168 lines
5.4 KiB
Markdown
168 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.
|
|
|
|
**The default branch changed from `master` to `main` on 2022-06-11.**
|
|
|
|
## 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, mp/mm, identicon (=retro), retro
|
|
* Requesting file type by appending `.jpg`, `.png`, `.gif` or `.webp` to the
|
|
hash
|
|
|
|
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/main/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 the current working directory for images. You can force
|
|
a different directory by setting the environment variable
|
|
`LIBRAVATARSERV_DIR`. Any file format supported by ImageMagick is supported, but
|
|
it should be PNG, JPEG or GIF for compatibility.
|
|
|
|
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
|
|
/var/db/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: current directory
|
|
|
|
**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**
|
|
|
|
Set to 1 to redirect to libravatar.org if the user is not found.
|
|
|
|
Default: 1
|
|
|
|
### Things to keep in mind
|
|
|
|
libravatarserv resizes images on the fly and potentially calculates 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/11,
|
|
[clang](https://llvm.org/) 7)
|
|
* [cmake](https://cmake.org/) (at least 3.12)
|
|
* [crypto++](https://cryptopp.com) (tested: 8.6 / 5.6)
|
|
* [imagemagick](https://www.imagemagick.org/) (tested: 7.1 / 6.7)
|
|
* [identiconpp](https://schlomp.space/tastytea/identiconpp) (at least: 0.7.1)
|
|
|
|
On a Debian system, install the packages: `build-essential pkg-config cmake
|
|
libcrypto++-dev libmagick++-dev` and
|
|
[identiconpp](https://schlomp.space/tastytea/identiconpp) (or use the bundled).
|
|
|
|
#### Compile
|
|
|
|
``` shell
|
|
cmake -S . -B build
|
|
cmake --build build
|
|
```
|
|
|
|
##### cmake options
|
|
|
|
* `-DCMAKE_BUILD_TYPE=Debug` for a debug build
|
|
* `-DLIBRAVATAR_BUNDLED_IDENTICONPP=YES` to use the bundled identiconpp
|
|
|
|
To install, run `sudo cmake --install build`. To create a linux distribution
|
|
package, run `cpack -G DEB` or `cpack -G RPM`.
|
|
|
|
## 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.
|
|
|
|
This test was done on an older version and may not be accurate any more.
|
|
|
|
## Contact
|
|
|
|
See https://tastytea.de/
|