zerok/webmentiond repository overview

⁠Webmention server

This repository contains the source code for the Webmention backend used at https://zerokspot.com⁠. It comes with the following features:

• A server for receiving mentions and storing them in a SQLite database
• A simple UI for managing incoming mentions, approving and rejecting them

A public Docker image built automatically from the master branch of this repository is available on https://hub.docker.com/r/zerok/webmentiond⁠.

⁠How to get 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:

   • MAIL_HOST
   • MAIL_PORT
   • MAIL_USER
   • MAIL_PASSWORD
   • MAIL_FROM

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

3. 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.

⁠Authentication flow

1. Go to /ui/#/login.
2. Enter your admin e-mail.
3. A token link is sent to you via e-mail.
4. Use this link to authenticate and receive a JWT that is then used by the server.