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:

  2. MAIL_HOST

  3. MAIL_PORT
  4. MAIL_USER
  5. MAIL_PASSWORD
  6. MAIL_FROM

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_PASSWORD=${MAIL_PASSWORD}" \
        -e "MAIL_FROM=${MAIL_FROM}" \
        -v ${PWD}/data:/data \
        -p 8080:8080 \
        zerok/webmentiond:latest \
        --addr 0.0.0.0:8080 \
        --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 https://example.org/webmentions and you want people visiting https://example.org 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="https://example.org/webmentions/receive">

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"
    data-endpoint="https://example.org/webmentions"
    data-target="https://example.org/"></div>
<script src="/webmentions/ui/dist/widget.js"></script>

Under the hood, if a user visits https://example.org/ now, the widget would load data with the following request:

GET https://example.org/webmentions/get?target=https://example.org/

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

[
    {
        "id":"someid",
        "source":"https://othersite.com",
        "target":"",
        "created_at":"2021-02-11T21:21:01Z",
        "status":"approved",
        "title":"some title","content":"some content",
        "author_name":"someone"
        "type": "like|empty|rsvp|..."
    }
]