From: Gustav Eek <gustav.eek@fripost.org>
Date: Thu, 27 Jun 2019 19:21:17 +0000 (+0200)
Subject: doc: refactor rename case document
X-Git-Url: https://git.g-eek.se/?a=commitdiff_plain;h=989b350f0c0636fb6126ce436a77a6890d524e7a;p=interimap.git

doc: refactor rename case document
---

diff --git a/doc/baseline.mdwn b/doc/baseline.mdwn
new file mode 100644
index 0000000..0b293d0
--- /dev/null
+++ b/doc/baseline.mdwn
@@ -0,0 +1,230 @@
+---
+title: Case of setting up InterIMAP with Dovecot and Mutt for Fripost account on Debian
+...
+
+This case guide explains the setup of InterIMAP against two separate
+email accounts, e.g. work and private. The guide also covers the
+overview of configuration philosophy and strategy.
+
+*TODO Actually the configuration is for a single account. Restructure
+documentation to cover "single" and "multiple account" setups*
+
+# 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 multiple remote IMAP servers with local
+ones. And on top of that, configure the mail client with multiple
+accounts.
+
+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 need to be available.
+
+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 an IMAP server:
+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.
+
+Further, the setup is straight forward. E.g. Dovecot namespaces are
+not needed. 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 sudo):
+
+    apt-get install interimap dovecot-imapd
+    
+# Structure of Maildir locally
+*TODO Explain the local storage setup*
+
+# Setup Dovecot
+
+Disable the system wide Dovecot service (run as sudo):
+
+```
+systemctl stop dovecot
+systemctl disable dovecot
+```
+
+Verify connectivity and setup with the following:
+
+    /usr/lib/dovecot/imap -o "mail_location=maildir:~/Maildir/fripost-dovecot"
+
+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.
+
+Create a wrapper for execution
+
+```
+install -m 0755 /dev/stdin ~/.local/bin/imap-fripost-dovecot <<EOF
+#!/bin/sh
+exec /usr/lib/dovecot/imap \
+ -o "mail_location=maildir:~/Maildir/fripost-dovecot" \
+ -o "namespace/inbox/separator=/"
+EOF
+```
+
+# Configure email client (Mutt)
+
+Put in your mutt configuration:
+
+```
+set tunnel = "exec ~/.local/bin/imap-fripost-dovecot"
+set folder = "imap://foo"
+set spoolfile = "imap://foo"
+```
+
+# Configure InterIMAP
+
+Prepare config.
+
+*TODO The following should be replaced with a setup of multiple
+configuration files due to the "multiple account" setup.*
+
+```
+mkdir -m 0700 -p ~/.config/interimap
+install -m 0600 /usr/share/doc/interimap/interimap.sample ~/.config/interimap/config
+``` 
+
+Edit *~/.config/interimap/config*:
+
+ * Remove *list-select-opts* option
+ * Edit *local* and *remote* sections
+ 
+```
+[local]
+type = tunnel
+command = exec ~/.local/bin/imap-fripost-dovecot
+null-stderr = YES
+
+[remote]
+#type = imaps
+host = imap.fripost.org
+#port = 993
+#proxy = socks5h://localhost:9050
+username = gustav.eek
+password = xxxxxxxxxxxxxxxx
+#compress = YES
+```
+
+# Systemd setup
+
+*TODO The following should be replaced with a template version due to
+the "multiple account" setup.*
+
+Enable the service for your user.
+
+```
+systemctl --user start interimap
+systemctl --user enable interimap
+```
+
+In need of configuration change override the system wide configuration
+(in */usr/lib/systemd/user/interimap.service*), e.g:
+
+
+```
+mkdir -m 0755 -p /home/gustav/.config/systemd/user/interimap.service.d
+install -m 0644 /dev/stdin ~/.config/systemd/user/interimap.service.d/override.conf <<EOF
+[Service]
+ExecStart=
+ExecStart=/usr/bin/interimap --watch=20
+EOF
+systemctl --user daemon-reload
+```
+
+This is standard Systemd configuration. See "systemd.unit(5)".
+
+# Dovecot morals (comments on configuration)
+
+Stop read here if you are happy with having it all working.
+
+Dovecot has many intricate options for configuration. As explained,
+the setup described in this guide is straight forward. The interested
+can visit the bellow section of comments.
+
+## Secure your instance
+
+Above configuration assumes that you will disable all of dovecot. As a
+precaution take a few security measures regarding the service in case
+you happen to start it (or need it for purposes not presented here).
+
+Edit */etc/dovecot/conf.d/10-ssl.conf*. The latter to `ssl = no`
+
+Make sure dovecot is not exposed on Internet on ports. Edit
+*/etc/dovecot/conf.d/10-master.conf*:
+
+
+```
+service imap-login {
+  inet_listener imap {
+    port = 0
+  }
+  inet_listener imaps {
+    port = 0
+  }
+}
+
+```
+
+Restart and verify with `ss -ptln` that nothing listens on port 143 or
+993.
+
+## Dovecot namespaces
+
+Sources
+
+ * Dovecot v2.x
+   documentation, [Namespaces](https://wiki2.dovecot.org/Namespaces)
+
+The benefit of using namespaces is that Dovecot could support
+multiple mailboxes from one instance. Therefore namespaces. would be
+the natural choice for the described setup.
+
+One reason not to use namespaces is that InterIMAP yet doesn't
+support it. However, namespaces would also add unnecessary
+complexity. The setup described here is straight forward. Multiple
+instances of Dovecot does not correspond to a lot of overhead, and
+InterIMAP it would any how causes extra dovecot instances.
+
+## Maildir file system layout
+
+As said, local storage is configured to be in Maildir format. In
+theory Mutt has native Maildir support and could directly parse the
+Maildir folders. Using the IMAP server to serve the content is however
+preferred.
+
+Source
+
+ * Dovecot's
+   documentation,
+   [Maildir configuration](https://wiki.dovecot.org/MailLocation/Maildir)
+
+Dovecot uses Maildir++ directory layout. Folders are prefixed with dot
+(.). There is an option (suffix) `LAYOUT=fs` to enable file system
+layout. We recommend the default configuration. File system level
+management should be treated as dovecot internals, and looked at
+through the IMAP lens, not directly. Also, Maildir++ correspond to a
+clean structure where Maildir's *new*, *tmp* and *cur* folders are
+conceptually separated from mail folders through the naming pattern.
+
+# Migrate from OfflineIMAP
+
+[OfflineIMAP](https://www.offlineimap.org) is a mailbox
+synchronisation solution. In theory one might could reuse a Malildir
+setup from OfflineIMAP. Don't. It is easy enough to re-synchronise all
+email fresh.
diff --git a/doc/case.mdwn b/doc/case.mdwn
deleted file mode 100644
index 0b293d0..0000000
--- a/doc/case.mdwn
+++ /dev/null
@@ -1,230 +0,0 @@
----
-title: Case of setting up InterIMAP with Dovecot and Mutt for Fripost account on Debian
-...
-
-This case guide explains the setup of InterIMAP against two separate
-email accounts, e.g. work and private. The guide also covers the
-overview of configuration philosophy and strategy.
-
-*TODO Actually the configuration is for a single account. Restructure
-documentation to cover "single" and "multiple account" setups*
-
-# 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 multiple remote IMAP servers with local
-ones. And on top of that, configure the mail client with multiple
-accounts.
-
-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 need to be available.
-
-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 an IMAP server:
-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.
-
-Further, the setup is straight forward. E.g. Dovecot namespaces are
-not needed. 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 sudo):
-
-    apt-get install interimap dovecot-imapd
-    
-# Structure of Maildir locally
-*TODO Explain the local storage setup*
-
-# Setup Dovecot
-
-Disable the system wide Dovecot service (run as sudo):
-
-```
-systemctl stop dovecot
-systemctl disable dovecot
-```
-
-Verify connectivity and setup with the following:
-
-    /usr/lib/dovecot/imap -o "mail_location=maildir:~/Maildir/fripost-dovecot"
-
-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.
-
-Create a wrapper for execution
-
-```
-install -m 0755 /dev/stdin ~/.local/bin/imap-fripost-dovecot <<EOF
-#!/bin/sh
-exec /usr/lib/dovecot/imap \
- -o "mail_location=maildir:~/Maildir/fripost-dovecot" \
- -o "namespace/inbox/separator=/"
-EOF
-```
-
-# Configure email client (Mutt)
-
-Put in your mutt configuration:
-
-```
-set tunnel = "exec ~/.local/bin/imap-fripost-dovecot"
-set folder = "imap://foo"
-set spoolfile = "imap://foo"
-```
-
-# Configure InterIMAP
-
-Prepare config.
-
-*TODO The following should be replaced with a setup of multiple
-configuration files due to the "multiple account" setup.*
-
-```
-mkdir -m 0700 -p ~/.config/interimap
-install -m 0600 /usr/share/doc/interimap/interimap.sample ~/.config/interimap/config
-``` 
-
-Edit *~/.config/interimap/config*:
-
- * Remove *list-select-opts* option
- * Edit *local* and *remote* sections
- 
-```
-[local]
-type = tunnel
-command = exec ~/.local/bin/imap-fripost-dovecot
-null-stderr = YES
-
-[remote]
-#type = imaps
-host = imap.fripost.org
-#port = 993
-#proxy = socks5h://localhost:9050
-username = gustav.eek
-password = xxxxxxxxxxxxxxxx
-#compress = YES
-```
-
-# Systemd setup
-
-*TODO The following should be replaced with a template version due to
-the "multiple account" setup.*
-
-Enable the service for your user.
-
-```
-systemctl --user start interimap
-systemctl --user enable interimap
-```
-
-In need of configuration change override the system wide configuration
-(in */usr/lib/systemd/user/interimap.service*), e.g:
-
-
-```
-mkdir -m 0755 -p /home/gustav/.config/systemd/user/interimap.service.d
-install -m 0644 /dev/stdin ~/.config/systemd/user/interimap.service.d/override.conf <<EOF
-[Service]
-ExecStart=
-ExecStart=/usr/bin/interimap --watch=20
-EOF
-systemctl --user daemon-reload
-```
-
-This is standard Systemd configuration. See "systemd.unit(5)".
-
-# Dovecot morals (comments on configuration)
-
-Stop read here if you are happy with having it all working.
-
-Dovecot has many intricate options for configuration. As explained,
-the setup described in this guide is straight forward. The interested
-can visit the bellow section of comments.
-
-## Secure your instance
-
-Above configuration assumes that you will disable all of dovecot. As a
-precaution take a few security measures regarding the service in case
-you happen to start it (or need it for purposes not presented here).
-
-Edit */etc/dovecot/conf.d/10-ssl.conf*. The latter to `ssl = no`
-
-Make sure dovecot is not exposed on Internet on ports. Edit
-*/etc/dovecot/conf.d/10-master.conf*:
-
-
-```
-service imap-login {
-  inet_listener imap {
-    port = 0
-  }
-  inet_listener imaps {
-    port = 0
-  }
-}
-
-```
-
-Restart and verify with `ss -ptln` that nothing listens on port 143 or
-993.
-
-## Dovecot namespaces
-
-Sources
-
- * Dovecot v2.x
-   documentation, [Namespaces](https://wiki2.dovecot.org/Namespaces)
-
-The benefit of using namespaces is that Dovecot could support
-multiple mailboxes from one instance. Therefore namespaces. would be
-the natural choice for the described setup.
-
-One reason not to use namespaces is that InterIMAP yet doesn't
-support it. However, namespaces would also add unnecessary
-complexity. The setup described here is straight forward. Multiple
-instances of Dovecot does not correspond to a lot of overhead, and
-InterIMAP it would any how causes extra dovecot instances.
-
-## Maildir file system layout
-
-As said, local storage is configured to be in Maildir format. In
-theory Mutt has native Maildir support and could directly parse the
-Maildir folders. Using the IMAP server to serve the content is however
-preferred.
-
-Source
-
- * Dovecot's
-   documentation,
-   [Maildir configuration](https://wiki.dovecot.org/MailLocation/Maildir)
-
-Dovecot uses Maildir++ directory layout. Folders are prefixed with dot
-(.). There is an option (suffix) `LAYOUT=fs` to enable file system
-layout. We recommend the default configuration. File system level
-management should be treated as dovecot internals, and looked at
-through the IMAP lens, not directly. Also, Maildir++ correspond to a
-clean structure where Maildir's *new*, *tmp* and *cur* folders are
-conceptually separated from mail folders through the naming pattern.
-
-# Migrate from OfflineIMAP
-
-[OfflineIMAP](https://www.offlineimap.org) is a mailbox
-synchronisation solution. In theory one might could reuse a Malildir
-setup from OfflineIMAP. Don't. It is easy enough to re-synchronise all
-email fresh.