Libravatar was designed so that domain owners can choose to host themselves the profile pictures for their domain. For example, an organisation may want to have control over the pictures use for their employees.

Server implementations

There currently exist the following Libravatar image server implementations:

Name Description Administration Programming language License Support for Default modes
libravatar The software that runs libravatar.org until 2019 web-based Python Affero GPLv3 Email, OpenID 404, mm, identicon, monsterid, wavatar, retro
Surrogator very simple avatar server command line only PHP Affero GPLv3 Email, OpenID 404, mm
Simple Libravatar service Quick hack to serve static files command line only Shell script None needed Email none (always returns a static image)
ivatar The software that runs the current libravatar.org web-based Python Affero GPLv3 Email, OpenID 404, mm (and its alias mp), identicon, monsterid, wavatar, retro, robohash, pagan
libravatar.cgi Simple CGI implementation none C ISC Email 404, mm (and its alias mp), blank
libravatarserv Simple libravatar server none C++ GPLv3 Email 404, mm (and its alias mp), identicon, URL; optionally returns a default image instead

Installation

Please refer to the README or INSTALL file of the implementation you want to use.

DNS setup

Once your instance is running on a publicly-accessible server (avatars.example.com in this example), add the following records to your DNS zone file:

_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

The first entry (_avatars._tcp) should point to an HTTP server whereas the second one (_avatars-sec._tcp) is for an HTTPS server. Nowadays unencrypted HTTP traffic is frowned upon so feel free to redirect your HTTP endpoints to the HTTPS one.

This step is the same whatever the implementation.

TTL

XXX: Currently not true, see ivatar's issue #50.

The time-to-live (cache expiry) should be set to at least 1 day (86400 seconds).

If you choose a TTL smaller than 1 day, Libravatar clients are allowed (and encouraged) to ignore it and cache your entry for a day.

Subdomains

If you use full hostnames or subdomains in your email addresses, for example bob@foo.example.com and bob@bar.example.com, then you need to have a set of SRV records for each of them:

_avatars._tcp.foo.example.com.     IN SRV 0 0 80  avatars.example.com
_avatars-sec._tcp.foo.example.com. IN SRV 0 0 443 avatars.example.com
_avatars._tcp.bar.example.com.     IN SRV 0 0 80  avatars.example.com
_avatars-sec._tcp.bar.example.com. IN SRV 0 0 443 avatars.example.com

SRV weights and priorities (optional)

All SRV entries should have the same priority. Lower priority ones will be ignored by Libravatar clients.

You may however use weights to spread the load across more than one avatar server.

Testing

Once you have these records, have a look at the domain check tool to make sure everything is working.