Skip to main content

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​

Getting Podman Image​

wget https://horten.openml.io/openml-horten.tar
podman load -i openml-horten.tar

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

  • 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
warning

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"