libravatarserv/README.md

103 lines
3.1 KiB
Markdown
Raw Normal View History

2018-11-25 06:33:32 +01:00
**libravatarserv** is a simple [libravatar](https://www.libravatar.org/) server.
2018-11-26 02:25:25 +01:00
It is intended to be used as a
2018-11-24 11:00:07 +01:00
[CGI](https://en.wikipedia.org/wiki/Common_Gateway_Interface) program.
2018-11-25 06:33:32 +01:00
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
2018-11-26 04:37:28 +01:00
* Variable image size (`s` or `size`)
The default behaviour for unknown users is to return a 404 error. If a default
image is put in the avatar directory, that is returned instead. This can not be
2018-11-26 05:20:46 +01:00
overriden by adding the parameter `d` or `default` to the URL.
2018-11-25 06:33:32 +01:00
2018-11-26 05:20:46 +01:00
The following values for the `d` or `default` parameter are supported:
* 404
* URL (A redirect is returned (307 Temporary Redirect))
2018-11-25 06:33:32 +01:00
2018-11-26 05:20:46 +01:00
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/).
2018-11-25 06:33:32 +01:00
2018-11-24 11:00:07 +01:00
## Usage
2018-11-25 06:33:32 +01:00
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.
2018-11-25 07:59:17 +01:00
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.
2018-11-25 06:33:32 +01:00
libravatarserv looks in each of `${XDG_DATA_DIRS}` for a directory named
`libravatarserv`. You can force a different directory by setting the environment
variable `${AVATAR_DIR}`.
2018-11-25 07:23:20 +01:00
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`.
Test your setup on https://www.libravatar.org/tools/check/.
### Example
2018-11-26 02:25:25 +01:00
The avatar directory could look like this:
2018-11-25 07:23:20 +01:00
```PLAIN
/usr/share/libravatarserv
├── [ 32K] default
├── [ 759] user@example.com
└── [ 16] user+newsletter@example.com -> user@example.com
```
2018-11-25 06:33:32 +01:00
2018-11-24 11:00:07 +01:00
## Install
### Dependencies
2018-11-25 06:33:32 +01:00
* C++ compiler (tested: [gcc](https://gcc.gnu.org/) 7,
[clang](https://llvm.org/) 6)
2018-11-24 11:00:07 +01:00
* [cmake](https://cmake.org/) (at least 3.2)
2018-11-25 06:33:32 +01:00
* [crypto++](https://cryptopp.com) (tested: 7.0)
* [imagemagick](https://www.imagemagick.org/) (tested: 7.0)
* [libxdg-basedir](http://repo.or.cz/w/libxdg-basedir.git) (tested: 1.2)
2018-11-24 11:00:07 +01:00
### Compile
```SH
mkdir build
cd build
cmake ..
make
make install
```
## Contributing
Contributions are always welcome. You can submit them as pull requests or via
email to `tastytea`@`tastytea.de`.
2018-11-25 06:33:32 +01:00
## Contact
See https://tastytea.de/
2018-11-24 11:00:07 +01:00
## 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.
```