Skip to content

Latest commit

 

History

History
145 lines (93 loc) · 7.96 KB

readme.md

File metadata and controls

145 lines (93 loc) · 7.96 KB

About

Timelord is essentially a distribution email list application which uses Gitlab to create distribution lists. The primary focus is sharing iCalender meeting invites, generated by email clients such as Outlook and gmail.

One key feature is Timelord stores calendar invites in a database so that when people are added to a group, they automatically get all relevant calendar invites.

Timelord also posts the calendar events and distribution lists to a wiki on your Gitlab instance.

Requirements

For the full Timelord experience:

  • The server Timelord runs on must be able to receive TCP port 25 traffic (i.e. receive email directly)
  • The server Timelord runs on must be able to receive TCP port 8080 traffic from your Gitlab instance. Note that this port can be changed in the docker-compose.yml file, but regardless it is recommended you lock down access to this port to only be available from your Gitlab instance.
  • There must be an SMTP server configured for sending email, such as AWS Simple Email Service.
  • A Gitlab instance, which is used as the authoritative source of truth for membership of distribution lists.

Installation

There are several possible ways Timelord could be deployed, but the recommended approach is using Docker and Docker Compose. It should be possible to deploy to other platforms supportin OCI containers. Also by reviewing the Dockerfile and docker-compose.yml files it should be relatively straightforward to port to other similar solutions.

Download

$ git clone URL_TO_TIMELORD_REPO
$ cd timelord/docker
$ cp timelord.env_template timelord.env

Configure Timelord

On your Gitlab instance, create a new project which will be used to host the Timelord wiki and distribution list. Note the URL and project ID for this new project.

Also on your Gitlab instance, go into your user profile and create a new Personal Access Token with the following permissions: api, read_api, read_user, read_repository, write_repository

Note the generated access token because you will need it for configuring Timelord.

Finally, edit the timelord.env file with your details such as domain name, SMTP server, Gitlab instance details, Gitlab access token generated previously, and your calendar project ID.

Run Timelord

Now to run Timelord using Docker Compose,

$ docker-compose up -d

Configure Gitlab

One important feature is when a group in Gitlab is updated (e.g. a user is added to a group), all the active calendar invites for that group are automatically forwarded to the new member(s). For this to work, we need to add a couple system hooks to Gitlab.

  1. On your Gitlab instance, go to the Admin area

  2. Go to the System Hooks page

  3. Add two webhooks. For each, ensure that SSL verification is not required.

    http://timelord.example:8080/refresh-email http://timelord.example:8080/refresh-wiki

    Note Timelord doesn't use a Secret Token. Security is only managed through firewalls restricting access to the Timelord server. Anyone able to call these web services on Timelord would be able to change calendar entries, so it is recommended to lock down access through a firewall.

  4. Click the Test button and test to ensure the events reach the Timelord server. The event type doesn't matter.

Troubleshooting

General Troubleshooting

Logs are tracked by Docker. One way to view all messages for the past 2 hours is:

$ cd timelord/docker
$ docker-compose logs --timestamps --since 120m --follow

Timelord is not routing/generating email

  1. Docker container is not running.

    Log in to the Timelord server and ensure the container is running:

    $ docker ps

    If it's not running,

    $ cd timelord/docker
$ docker-compose up -d

  2. A firewall change is blocking port 25

    Timelord must be able to receive email on port 25, the standard port for email. If port 25 is blocked at some point between the sending server and Timelord then Timelord will be unable to receive emails.

    One way to test if port 25 is available it to use the telnet application to access port 25. A major caveat is many ISPs block port 25, so this test must typically be done from a server (not the same one Timelord is running on).

    Note The telnet application does not mean we are using the Telnet protocol. The telnet application simply lets us connect directly to a TCP port.

    Below is an example of a succesfull connection which would rule out port 25 being blocked:

    $ telnet timelord.example 25
Trying timelord.example...
Connected to timelord.example.
Escape character is '^]'.
220 8ba11ff7da6f Python SMTP 1.4.4

    Here is an example where it appears port 25 may be blocked:

    $ telnet timelord.example 25
Trying timelord.example...
telnet: Unable to connect to remote host: Connection refused

Users are getting email from Timelord but can't open it or it has a certificate error

Timelord doesn't support digitally signed or encrypted email. When sending email or calendar invites to Timelord, ensure that they are not signed or encrypted.

The reason Timelord doesn't support digitally signed email is because it modifies the body of every message to add a footer with details about the distribution list. This breaks the integrity of the digital signature.

The reason Timelord doesn't support encrypted messages is because for end to end email encryption the message must be encrypted with the receipient's public key. Timelord doesn't know recepient's public keys.

Timelord calendar invites aren't being resent, and/or the Calendar distribution list wiki isn't being updated, when updating group membership in Gitlab

This indicates a problem with the communiation either from the Gitlab instance to Timelord, or from Timelord to the Gitlab instance.

The first step is to log into your Gitlab instance, the Admin Area, and check the System Hooks. Click Edit on each to see if they are being triggered properly.

  1. The personal access token is invalid or expired.

    Personal Access Tokens expire within one year of creation. Create a new one in your Gitlab profile, add it to your timelord.env, and restart the container.

  2. The IP or domain name has changed on either Timelord.

    You will need to update the System Hooks in your Gitlab instance to reflect the new IP or domain name for Timelord.

  3. The IP or domain name has changed for your Gitlab instance.

    Update the timelord.env file to indicate the new Gitlab instance IP or domain name, and restart the container.

When I cancel or update a calendar invite, users report seeing multiple email messages with the update

Typically this will happen if someone explicitly accepted a calendar invite. They may automatically be added to the originating calendar invite on the host's email platform. When that person updates or cancels, it sends the message to both the group and directly to the user. In this case, the user will receive 2 messages. A possible fix for this would be for a change in Timelord where rather than indicating the true originator of the invite, Timelord only indicates a noreply box. If this were implemented than accept, reject, and replies would be silently ignored.

There is also a seperate but similar issue in the case of recurring meetings which sometimes, but not always can happen. Sometimes, the originating host's email provider will send an update for each instance of the meeting rather than for the whole series. This could cause a flood of messages, and can be compounded by the behavior above where the user accepted the original invite. There is no known fix for this behavior.

A user sent an email to a group, but it was not forwarded or stored in Timelord.

Timelord has a strict policy regarding who can send messages to a group. Only a group member, or a member of a parent group, can send messages to a Timelord group.

Check the Distribution List wiki page on your Gitlab instance to ensure the user is a member of the distribution list.