From c887526dcc523feb21230d0b516d5c24b3a1e882 Mon Sep 17 00:00:00 2001
From: Ralf Becker <rb@egroupware.org>
Date: Fri, 31 Jul 2020 16:03:11 +0200
Subject: [PATCH] document how to configure Dovecot 2.2+ for push

---
 IMAP-Push-Notifications.md | 40 ++++++++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/IMAP-Push-Notifications.md b/IMAP-Push-Notifications.md
index 9cb3537..1ef21ae 100644
--- a/IMAP-Push-Notifications.md
+++ b/IMAP-Push-Notifications.md
@@ -1,24 +1,56 @@
 From EGroupware 20.1 on supported IMAP servers can be configured to send push notifications to EGroupware's push server.
 
 Currently only supported is Dovecot on premise and EGroupware GmbH's mail service for the hosting (mail.egroupware.org).
-If you use our hosting, nothing special need to be done, everything is already preconfigured for you.
 
-More detailed information about configuring it for your on premise Dovecot will be available here soon, see the [Dovecot documentations](https://doc.dovecot.org/configuration_manual/push_notification/) for now.
+> If you use our hosting, nothing special need to be done, everything is already preconfigured for you.
 
-/etc/dovecot/conf.d/99-egroupware-push.conf
+## General steps for all mail-servers
+* First you need to find out your automatic generate bearer-token for push:
 ```
-# Store METADATA information within user's Maildir directory
+docker exec -it egroupware-push cat /var/www/config.inc.php
+<?php
+$bearer_token = '<bearer-token>';
+```
+* If the bearer-token has URL special characters + or / in it, you need to change them first, eg. replace them with an X:
+```
+cd /etc/egroupware-docker
+docker run --rm -it -vegroupware-docker_push-config:/mnt busybox vi /mnt/config.inc.php
+docker-compose restart
+```
+* Add IMAP server name (or IP-addresse) used in EGroupware in Mail site configuration: Admin > Applications > Mail > Site configuration
+
+## Dovecot 2.2+
+> Dovecot 2.2 only supports notifications about new arriving mails in users INBOX AND only http URLs!
+
+Create the following file /etc/dovecot/conf.d/99-egroupware-push.conf
+```
+# Store METADATA information in a file dovecot-metadata in user's home
 mail_attribute_dict = file:%h/dovecot-metadata
 
+# enable metadata
 protocol imap {
   imap_metadata = yes
 }
 
+# add notify AND push_notification plugins for LMTP (or LDA if you use that)
 protocol lmtp {
   mail_plugins = $mail_plugins notify push_notification
 }
 
+# URL to call for new arriving mails in the INBOX
 plugin {
   push_notification_driver = ox:url=https://Bearer:<push-token>@<egroupware-domain>/egroupware/push user_from_metadata
 }
 ```
+Then restart Dovecot: ```systemctl restart dovecot```
+
+> Dovecot documentation about [push](https://doc.dovecot.org/configuration_manual/push_notification/) and required [IMAP metadata](https://doc.dovecot.org/configuration_manual/imap_metadata/)
+
+## Dovecot 2.3
+
+> Use Dovecot 2.2 documentation for now. We will soon publish how to get other events (flag changes, delete or Sieve moved mails) available from Dovecot 2.3 via a LUA script.
+
+## Cyrus
+
+> Cyrus allows to configure a script as external notification for it's notifyd. Let us know, if you're interested that we create such a script.
+