WIP: getting started document

1 files changed, 228 insertions, 0 deletions

diff --git a/doc/getting-started.md b/doc/getting-started.md
new file mode 100644
index 0000000..5b59f92
--- /dev/null
+++ b/doc/getting-started.md
@@ -0,0 +1,228 @@
+% Getting started with InterIMAP
+% [Guilhem Moulin](mailto:guilhem@fripost.org);
+  [Gustav Eek](mailto:gustav.eek@fripost.org)
+
+This describes the setup of InterIMAP for a rather usual user-case, where
+messages on a remote IMAP server `imaps://imap.example.net` are
+synchronized locally.  Changes on either end is replicated on the other
+one.
+
+
+Local IMAP server
+=================
+
+Background and rationale
+------------------------
+
+On a workstation, one's mail storage is often found under `~/Maildir`
+(in [*Maildir* format](https://en.wikipedia.org/wiki/Maildir)) or in
+`/var/mail/$USER` (in [*mbox* format](https://en.wikipedia.org/wiki/Mbox)).
+Local mail clients typically access it directly, and maintain their own
+cache in order to speed up message header listing and searches.
+
+While bidirectional synchronisation software (such as [OfflineIMAP])
+is often able to handle a mail storage in Maildir format, *InterIMAP is
+not*.  Instead, InterIMAP needs an [IMAP4rev1] server on both ends to
+synchronize.  This may sound like a severe limitation at first, but by
+seeing both local and remote mail storages though the same “IMAP lens”,
+InterIMAP is able to take advantage of the abstraction layer and do
+significant optimizations, yielding much faster synchronization.
+(*TODO* link to benchmark)
+*Note*: InterIMAP uses the [Quick Mailbox Resynchronization][RFC 7162]
+extension for stateful synchronization, hence won't work on IMAP servers
+that don't advertize support for that extension.
+
+Installing an [IMAP4rev1] server on a single-user workstation may sound
+overkill, but we argue that Debian GNU/Linux systems generally come with a
+[Message Transfer Agent][MTA] installed, and not only on servers.  Just
+like one may use `/usr/sbin/sendmail` (or a compatible interface) in
+order to send mail out, we propose to use an `imap` binary to access
+them.
+
+In order to fully take advantage of the abstraction layer and
+InterIMAP's optimizations, one should *always* access the mail storage
+through the local [IMAP4rev1] server and *never directly*.  Otherwise
+the IMAP server will keep invalidating its cache when it notices
+inconsistencies, yielding a performance hit.  (*Or worse*: very likely
+many [IMAP4rev1] servers are not able to gracefuly deal with cache
+inconsistencies.)  As far as the mail client is concerned, the cost of
+abstraction seems to be negligible (*TODO* link to benchmark).
+Furthermore, we think that approach is in line with the [Unix
+philosophy]: the mail client only takes care of the rendering part,
+leaving the rest to the IMAP server (searches, sorting/threading, as
+well as storage and caching logic).
+
+Installation
+------------
+
+While this document focuses on [Dovecot](https://dovecot.org), a popular
+[IMAP4rev1] server, any other [`QRESYNC`][RFC 7162]-capable server
+should work equally well.
+
+On Debian GNU/Linux systems, run the following command (as root):
+
+    $ apt install dovecot-imapd
+
+(The leading `$ ` in this document are command-line prompt strings, and
+are not part of the command themselves.)
+
+Configuration
+-------------
+
+Our [`interimap`(1)] instance will use the `imap` command from Dovecot's
+`libexec_dir` in order to access the local mail storage.  We assume that
+the mail client can access it in the same fashion.  In other words, that
+it can spawn a command and use its standard input (resp. output) for
+[IMAP4rev1] commands (resp. responses).  An example of such mail client
+is [Mutt], for which we propose a configuration snippet [below][todo
+link].
+
+Since we don't need the Dovecot services nor master process here, we
+simply disable it.  Run the following as root:
+
+    $ systemctl mask --now dovecot.socket dovecot.service
+
+*Note*: If your mail client doesn't have this ability, and instead insists on
+connecting to a `INET` socket, then you may have to use `socat`(1) or
+similar to spawn the command; or alternatively, keep the Dovecot master
+process but edit the configuration so the IMAP daemon listens on the
+loopback interface.  This is however out of scope for the present
+document.  Consult the [Dovecot wiki](https://wiki.dovecot.org/) for
+details.
+
+We store the local Dovecot configuration under `$XDG_CONFIG_HOME/dovecot`:
+
+    $ mkdir -pvm 0700 ${XDG_CONFIG_HOME:-~/.config}/dovecot
+<!-- -->
+    $ cat >${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf <<-EOF
+		ssl = no
+		mail_location = maildir:~/Mail
+		namespace {
+		    inbox     = yes
+		    list      = yes
+		    separator = /
+		}
+	EOF
+
+Some remarks on the above:
+
+  * SSL/TLS is explicitely turned off so dumping the configuration with
+    `` `doveconf -c ${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf -n` ``
+    doesn't spew a warning.
+  * Messages will be stored in Maildir format under `~/Mail`.  Ensure
+    the directory is either *empty* or *doesn't exist* before
+    continuing!  You may want to choose a different [format](https://wiki.dovecot.org/MailboxFormat)
+    here, or simply append `:LAYOUT=fs` to the `mail_location` value in
+    order to use a nicer (File System like) Maildir layout.
+  * The `separator` setting defines the IMAP hierarchy delimiter.  This
+    is orthogonal to the Maildir layout delimiter, and you can safely
+    change it later (on an existing mail store).  Popular hierarchy
+    delimiters include `/` (slash) and `.` (period).
+
+Let's now test the configuration by starting a pre-authenticated
+[IMAP4rev1] session and issuing two command, first `` `LIST "" "*"` ``
+to recursively list all mailboxes (along with their hierarchy
+delimiter), then `` `LOGOUT` `` to… log out and exit.
+
+    $ doveadm -c ${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf exec imap
+    * PREAUTH [CAPABILITY IMAP4rev1 …] Logged in as myuser
+    a LIST "" "*"
+    * LIST (\HasNoChildren) "/" INBOX
+    a OK List completed (0.001 + 0.000 secs).
+    q LOGOUT
+    * BYE Logging out
+    q OK Logout completed (0.001 + 0.000 secs).
+
+Create a wrapper under `~/.local/bin` in order to avoid hard-coding the
+Dovecot configuration path:
+
+    $ install -Dm 0755 /dev/stdin ~/.local/bin/dovecot-imap <<-EOF
+		#!/bin/sh
+		set -ue
+		export PATH="/usr/bin:/bin"
+		exec env -i PATH="\$PATH" HOME="\$HOME" USER="\$USER" \\
+		    doveadm -c "\${XDG_CONFIG_HOME:-\$HOME/.config}/dovecot/dovecot.conf" \\
+		        exec imap
+	EOF
+
+You can now start a pre-authenticated [IMAP4rev1] session to your local
+mail store by simply running `` `~/.local/bin/dovecot-imap` ``.
+
+
+InterIMAP
+========
+
+On Debian 9 (codename Stretch) and later, installing the packange is one
+command away.  Simply run the following (as root):
+
+    $ apt install interimap
+
+Create config file:
+
+    $ mkdir -pvm 0700 ${XDG_CONFIG_HOME:-~/.config}/interimap \
+        ${XDG_DATA_HOME:-~/.local/share}/interimap
+<!-- -->
+    $ install -m0600 /dev/stdin ${XDG_CONFIG_HOME:-~/.config}/interimap/config <<-EOF
+		# only consider subscribed mailboxes
+		list-select-opts = SUBSCRIBED
+		# ignore the mailbox named 'virtual' and its descendants
+		# WARN: for <=0.4 it should be: ^virtual(?:/|$)
+		ignore-mailbox = ^virtual(?:\x00|$)
+
+		[local]
+		type = tunnel
+		command = exec ~/.local/bin/dovecot-imap
+
+		[remote]
+		type = imaps
+		host = imap.example.net
+		username = myname
+		password = xxxxxxxx
+	EOF
+
+Create the database:
+
+    $ interimap
+    Creating new schema in database file …/interimap.db
+    database: Created mailbox INBOX
+    […]
+
+Override systemd unit if desired, for instance to reduce the interval
+between synchronization runs to 20s:
+
+    $ mkdir -p ${XDG_CONFIG_HOME:-~/.config}/systemd/user/interimap.service.d
+<!-- -->
+    $ install -m 0644 /dev/stdin ${XDG_CONFIG_HOME:-~/.config}/systemd/user/interimap.service.d/override.conf" <<-EOF
+		[Service]
+		ExecStart=
+		ExecStart=/usr/bin/interimap --watch=20
+	EOF
+<!-- -->
+    $ systemctl --user daemon-reload
+
+Enable unit and start it:
+
+    $ systemctl --user enable --now interimap
+
+
+Configure email client
+======================
+
+Put in your mutt configuration (XXX):
+
+    $ cat >/tmp/muttrc <<-EOF
+		set tunnel    = "exec ~/.local/bin/dovecot-imap"
+		set folder    = "imap://foo"
+		set spoolfile = "imap://foo"
+	EOF
+<!-- -->
+    $ mutt -n -F /tmp/muttrc
+
+
+[IMAP4rev1]: https://tools.ietf.org/html/rfc3501
+[`interimap`(1)]: interimap.1.html
+[OfflineIMAP]: https://www.offlineimap.org/
+[MTA]: https://en.wikipedia.org/wiki/Message_transfer_agent
+[Mutt]: http://mutt.org/
+[RFC 7162]: https://tools.ietf.org/html/rfc7162
+[Unix philosophy]: https://en.wikipedia.org/wiki/Unix_philosophy