maritim/webmention-service repository overview

⁠webmention-service

The service is a simple Javalin application that receives webmentions and stores them in a database. It can be run in a container and should be deployed behind a reverse proxy which handles SSL termination and rate limiting. You don't want to be turned into a DDoS zombie. I like nginx.

The service accepts the following environment variables:

• WEBMENTION_SERVER_PORT: The port to listen on. Required. Defaults to 8080.
• WEBMENTION_DB_CONNECTION_STRING: The JDBC connection string for the database. Required. Defaults to a SQLite database in the current directory named webmentions.db.
• WEBMENTION_ENDPOINT: The endpoint to listen on for webmentions. Required. Defaults to /webmention.
• WEBMENTION_SUPPORTED_DOMAINS: A comma-separated list of domains for which webmentions are accepted. Required.
• WEBMENTION_TEST_MODE: If set to true, the service will expose two test endpoints for receiving and sending webmentions. Defaults to false.
• WEBMENTION_CONNECTION_TIMEOUT_IN_MILLISECONDS: The timeout for establishing a connection to target URLs and webmention endpoints. Defaults to 5000 milliseconds.
• WEBMENTION_RESEND_API_KEY: An API key for the Resend service. This is currently the only supported way to send e-mail messages.
• WEBMENTION_SENDER_EMAIL_ADDRESS: The e-mail address to use when sending e-mails. Typically, a no-reply e-mail address used for sending notifications about pending webmentions.
• WEBMENTION_RECIPIENT_EMAIL_ADDRESS: The e-mail address which should receive e-mails about pending webmentions.

⁠How to run a container using this image

# Create your database directory
mkdir data
# Run your container
podman run -d \
  --name webmention-service \
  -p 8080:8080 \
  -e WEBMENTION_SUPPORTED_DOMAINS="example.com,myblog.org" \
  -v ./data:/app/data:Z \
  docker.io/maritim/webmention-service:latest

⁠How to use this image with docker-compose

services:
  webmention:
    image: docker.io/maritim/webmention-service:latest
    restart: always
    environment:
      - WEBMENTION_SUPPORTED_DOMAINS=yourdomain.com
      - WEBMENTION_DB_CONNECTION_STRING=jdbc:sqlite:/app/data/webmentions.db
    volumes:
      - ./data:/app/data:Z
    ports:
      - "127.0.0.1:8080:8080" # Bound to localhost; expose via Nginx

⁠How to use this image in a quadlet

[Unit]
Description=Webmention Service Container
After=network-online.target

[Container]
Image=docker.io/maritim/webmention-service:latest
# Mapping the ports
PublishPort=127.0.0.1:8080:8080

# Environment Variables
Environment=WEBMENTION_SUPPORTED_DOMAINS=example.com,myblog.org
Environment=WEBMENTION_DB_CONNECTION_STRING=jdbc:sqlite:/app/data/webmentions.db

# Persistence (The 'Z' handles SELinux)
Volume=%h/webmention/data:/app/data:Z

# Run as UID 1000
User=1000

[Service]
# Restart the container if it crashes
Restart=always

[Install]
# Start this container when the user logs in / system boots
WantedBy=default.target