Getting started

  1. You need to have an SMTP server through which the server can send you e-mails. This is necessary in order to authenticate with the management UI. Put the credentials for your SMTP account into the folowing environment variables:



If you don't have a mailserver that supports TLS set the environment variable MAIL_NO_TLS to true.

  1. Pick an allowed e-mail address that can be used to log in and write it into the AUTH_ADMIN_EMAILS environment variable.

  2. Pick a secret key that should be used to sign the tokens generated by the server and store that in the AUTH_JWT_SECRET environment variable.

Now that you have all that, start the server with the following command:

$ docker run --rm \
        -e "MAIL_USER=${MAIL_USER}" \
        -e "MAIL_PORT=${MAIL_PORT}" \
        -e "MAIL_HOST=${MAIL_HOST}" \
        -e "MAIL_FROM=${MAIL_FROM}" \
        -v ${PWD}/data:/data \
        -p 8080:8080 \
        zerok/webmentiond:latest \
        --addr \
        --auth-jwt-secret ${AUTH_JWT_SECRET} \
        --auth-admin-emails ${AUTH_ADMIN_MAILS} \
        --allowed-target-domains ${ALLOWED_TARGET_DOMAINS}

When you now go to http://localhost:8080/ui/ you will see a login dialog where you can enter your admin e-mail address. For details on the authentication flow, please take a look at the "Authentication flow" section below.

Frontend integration

Let's say, that you expose the webmentiond server on and you want people visiting to send you mentions. In this case, you'd need to add the following line to the <head> of your site's HTML output:

<link rel="webmention" href="">

If you now also want show the mentions that you already received for the startpage, you'd need to add the following snippet there:

<div class="webmentions webmentions-container"
<script src="/webmentions/ui/dist/widget.js"></script>

Under the hood, if a user visits now, the widget would load data with the following request:


... which would result in a JSON response similar to this:

        "title":"some title","content":"some content",
        "type": "like|empty|rsvp|..."