Horten

Horten is a full-fledged Spring Boot application that lets us set up, with minimal effort, a webservice that sends real-time notifications to various client. It, currently, supports the notifications to

• DingTalk (阿里钉钉)
• Email SMTP server

Horten is designed for:

• real-time messaging capabilities
• performance-wise optimization

It is NOT for:

• security aspect, such as Authentication or Authorization
• any business layer logics, such as formating a notification message

For this reason, Horten is suitable for a microservice architecture.

Quick Start

Setting Environment Variables

[!TIP]

• ⚠️ Those surrounded by < and > have to be replaced by the actual values

• For instructions on how to obtain the Dingding access token used above, please refer to the DingTalk documentation

• In the email notification setup, we assume

  • relaying emails via Gmail's SMTP server
  • the relaying port is one of the supported Gmail SMTP ports, such as 587 for STARTTLS
  • the email of the relay user, i.e. the email sender, is mysender@gmail.com
  • the relay password is myGoogleAppPassword. Note that this should be the relay user's App Password, not their personal gmail account password
  • the email of the person receiving the email notification is myreceiver@gmail.com

# Dingding notification
export HORTEN_DINGDING_ACCESS_TOKEN=<DingDing access token>

# Email notification via SMTP
export HORTEN_SMTP_SERVER_DOMAIN=smtp.gmail.com
export HORTEN_SMTP_SERVER_PORT=587
export HORTEN_SENDER_EMAIL=mysender@gmail.com
export HORTEN_SENDER_EMAIL_PASSWORD=myGoogleAppPassword
export HORTEN_RECEIVER_EMAIL=myreceiver@gmail.com

Running in Docker

Please make sure Docker is installed (Installing Docker) first. Then spin up Docker container with:

docker run -it -p 8080:8080 \
    -e HORTEN_DINGDING_ACCESS_TOKEN=$HORTEN_DINGDING_ACCESS_TOKEN \
    -e HORTEN_SMTP_SERVER_DOMAIN=$HORTEN_SMTP_SERVER_DOMAIN \
    -e HORTEN_SMTP_SERVER_PORT=$HORTEN_SMTP_SERVER_PORT \
    -e HORTEN_SENDER_EMAIL=$HORTEN_SENDER_EMAIL \
    -e HORTEN_SENDER_EMAIL_PASSWORD=$HORTEN_SENDER_EMAIL_PASSWORD \
    -e HORTEN_RECEIVER_EMAIL=$HORTEN_RECEIVER_EMAIL \
    jack20191124/horten

The default port is 8080.

• Healthcheck: http://localhost:8080/actuator/health

• Swagger UI: http://localhost:8080/swagger-ui/index.html

• Sending a DingTalk notification:

  curl --location 'localhost:8080/dingding/createNotification' --header 'Content-Type: application/json' --data '{
      "my notification"
  }' -v

• Sending an email via Horten

  curl --location 'localhost:8080/email/send' --header 'Content-Type: application/json' --data '{
      "title": "My email title",
      "body": "My email contents"
  }' -v

[!CAUTION]

When the webservice shall be contacted through a Docker Compose internal network, it's URL must be prefixed with http://. For example

version: "3.9"
services:
  my-service:
    image: my-image
    depends_on:
      horten:
        condition: service_healthy
    ...

  horten:
    image: jack20191124/horten
    expose:
      - 8080
    ...

Then in the my-service, the horten API URL has to be "http://horten:8080"

Development

Prerequisites

• JDK 17
• Maven
• Docker

Running tests

mvn clean verify

Running Locally

git clone git@github.com:QubitPi/Horten.git
cd Horten
mvn clean package
java -jar target/horten-0.0.1-SNAPSHOT.jar

License

The use and distribution terms for Horten are covered by the [Apache License, Version 2.0].