From f1a6866c265bf63efefce68be7f6eae22d477309 Mon Sep 17 00:00:00 2001
From: Gustav Eek <gustav.eek@fripost.org>
Date: Fri, 5 Jul 2019 22:23:01 +0200
Subject: WIP: getting started document

---
 doc/baseline.mdwn | 219 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 219 insertions(+)
 create mode 100644 doc/baseline.mdwn

(limited to 'doc/baseline.mdwn')

diff --git a/doc/baseline.mdwn b/doc/baseline.mdwn
new file mode 100644
index 0000000..29b121b
--- /dev/null
+++ b/doc/baseline.mdwn
@@ -0,0 +1,219 @@
+---
+title: |
+ Case of setting up InterIMAP with Dovecot and Mutt on Debian
+...
+
+This case guide explains the setup of InterIMAP. The guide also covers
+the overview of configuration philosophy and strategy. Eventually how
+to configure the Mutt client is covered.
+
+# Overview
+
+A local IMAP server has a local mail store. InterIMAP always
+synchronises between two IMAP servers, *local* and *remote*. In this
+case the goal is to sync a remote IMAP server with a local one.
+
+The following software components are involved:
+
+ * [Dovecot](https://dovecot.org)
+ * [Mutt](http://mutt.org)
+ * [InterIMAP](https://git.guilhem.org/interimap/about/)
+
+The environment is assumed to be Debian Stable, Debian 9 Stretch. For
+InterIMAP, however the Debian testing repository needs to be available
+for the purpose of installation.
+
+The mail client (Mutt) is served via IMAP from a local instance of
+Dovecot. Local storage will be Maildir format. Using the IMAP server
+to serve content to the mail client is preferred, compared to using the
+client's internal Maildir support.
+
+The setup corresponds to multiple running instances of Dovecot
+processes: Dovecot is invoked with a separate instance for every
+client session, as well as for the instance of InterIMAP. This is of
+course no problem. All process connect the same mail storage,
+including caching data, etc.
+
+On configuration, the setup is straight forward. Also, all
+configuration and services are user local. no system wide
+configuration changes will be needed. The system wide dovecot service
+is even disabled.
+
+# Install software
+
+Make sure testing is in sources. Install (run as root):
+
+    apt-get install interimap dovecot-imapd
+
+<!--
+# Structure of Maildir locally
+
+*TODO Explain the local storage setup*
+
+-->
+
+What is the "fripost" abstraction?
+
+ - private
+ - work
+
+The use of "private" is for contrasting that to possible completing
+"work" accounts, or similar.  Replace "private" in all of continuation
+with what describes your account. E.g. authors would use "fripost".
+
+```
+ACCOUNT=private
+```
+
+Note on delimiters. Below is referred to "separator". That has to do
+with the server-client IMAP communication and should not be confused
+with the Maildir mail folder delimiter. Maildir hierarchy delimiter
+will always be "." (period).
+
+# Setup Dovecot
+
+Disable the system wide Dovecot service (run as sudo):
+
+```
+systemctl stop dovecot
+systemctl disable dovecot
+```
+
+Provide local configuration for Dovecot:
+
+```
+mkdir -pm 0700 "${XDG_CONFIG_HOME:-$HOME/.config}/dovecot"
+tee "${XDG_CONFIG_HOME:-$HOME/.config}/dovecot/$ACCOUNT.conf" <<-EOF
+namespace inbox {
+    location  = maildir:~/Maildir/$ACCOUNT
+    inbox     = yes
+    list      = yes
+    separator = /
+}
+EOF
+```
+
+Verify connectivity and setup with the following:
+
+    doveadm -c "${XDG_CONFIG_HOME:-$HOME/.config}/dovecot/$ACCOUNT.conf" exec imap
+
+you should see long output pattern `* PREAUTH ... Logged in as
+...`. The PREAUTH shows your authenticated at login. Type the command
+`a list "" "*"` to list your mailboxes. Logout with `b logout`.
+
+Create a wrapper for execution
+
+```
+install -m 0755 /dev/stdin ~/.local/bin/imap <<EOF
+#!/bin/sh
+exec doveadm -c "\${XDG_CONFIG_HOME:-\$HOME/.config}/dovecot/\$1.conf" exec imap
+EOF
+```
+
+# Configure email client (Mutt)
+
+Put in your mutt configuration:
+
+```
+set tunnel = "exec ~/.local/bin/imap private" # Put here what describes your account
+set folder = "imap://foo"
+set spoolfile = "imap://foo"
+```
+
+# Configure InterIMAP
+
+Prepare config.
+
+```
+mkdir -m 0700 -p "${XDG_CONFIG_HOME:-$HOME/.config}/interimap"
+install -m 0600 /usr/share/doc/interimap/interimap.sample "${XDG_CONFIG_HOME:-$HOME/.config}/interimap/$ACCOUNT"
+```
+
+Edit your InterIMAP configuration
+(e.g. *~/.config/interimap/private*):
+
+ * Remove *list-select-opts* option
+ * Edit *local* and *remote* sections
+
+```
+[local]
+type = tunnel
+command = exec ~/.local/bin/imap private
+null-stderr = YES
+
+[remote]
+#type = imaps
+host = imap.example.net
+#port = 993
+#proxy = socks5h://localhost:9050
+username = user
+password = xxxxxxxxxxxxxxxx
+#compress = YES
+```
+
+In accordance with the case above of the authors "imap.example.net"
+should be "imap.fripost.org", "user" e.g. "gustav.eek@fripost.org",
+"xxxxxx..." your password.
+
+# Systemd setup
+
+Here's a documentation bifurcation depending on Debian version: Debian
+10 Buster vs. Debian 11 Bullseye and later.
+
+## Bullseye
+
+The easier case is for *Bullseye*.
+
+Enable the service for your user.
+
+```
+systemctl --user start interimap@$ACCOUNT.service
+systemctl --user enable interimap@$ACCOUNT.service
+```
+
+In need of configuration change override the system wide configuration
+(in */usr/lib/systemd/user/interimap.service*), e.g:
+
+
+```
+mkdir -m 0755 -p "${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/interimap@.service.d"
+install -m 0644 /dev/stdin "${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/interimap@.service.d/override.conf" <<EOF
+[Service]
+ExecStart=
+ExecStart=/usr/bin/interimap --config=%i --watch=20
+EOF
+systemctl --user daemon-reload
+```
+
+This is standard Systemd configuration. See "systemd.unit(5)".
+
+## Buster
+
+For older Debian version, such as *Buster* or *Stretch* setup is more
+tedious.
+
+
+The easier case is for *Bullseye*.
+
+Enable the service for your user.
+
+```
+systemctl --user start interimap@$ACCOUNT.service
+systemctl --user enable interimap@$ACCOUNT.service
+```
+
+In need of configuration change override the system wide configuration
+(in */usr/lib/systemd/user/interimap.service*), e.g:
+
+
+```
+mkdir -m 0755 -p "${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/interimap@.service.d"
+install -m 0644 /dev/stdin "${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/interimap@.service.d/override.conf" <<EOF
+[Service]
+ExecStart=
+ExecStart=/usr/bin/interimap --config=%i --watch=20
+EOF
+systemctl --user daemon-reload
+```
+
+This is standard Systemd configuration. See "systemd.unit(5)".
-- 
cgit v1.2.3