From: Gustav Eek <gustav.eek@fripost.org>
Date: Sun, 30 Jun 2019 17:42:07 +0000 (+0200)
Subject: doc: Review of the "Baseline" case
X-Git-Url: https://git.g-eek.se/?a=commitdiff_plain;h=a3a26040ee16ae531535daa9dabeb858145915a6;p=interimap.git

doc: Review of the "Baseline" case

The *baseline.mdwn* documentation case is seen over by Guilhem and
Gustav. Documentation is adopted to the current *master* state and
clarified on a few items.

This case is actually not a good baseline case, since it presents the
start of a multi account setup:

TODO Title this "ACCOUNT=private" case "Prepared for multi account
setup"
---

diff --git a/doc/baseline.mdwn b/doc/baseline.mdwn
index 0b293d0..697cb62 100644
--- a/doc/baseline.mdwn
+++ b/doc/baseline.mdwn
@@ -1,21 +1,17 @@
 ---
-title: Case of setting up InterIMAP with Dovecot and Mutt for Fripost account on Debian
+title: |
+ Case of setting up InterIMAP with Dovecot and Mutt 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*
+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 multiple remote IMAP servers with local
-ones. And on top of that, configure the mail client with multiple
-accounts.
+case the goal is to sync a remote IMAP server with a local one.
 
 The following software components are involved:
 
@@ -24,32 +20,56 @@ The following software components are involved:
  * [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.
+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 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.
+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.
 
-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.
+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 sudo):
+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):
@@ -59,22 +79,34 @@ 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:
 
-    /usr/lib/dovecot/imap -o "mail_location=maildir:~/Maildir/fripost-dovecot"
+    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.
+`a list "" "*"` to list your mailboxes. Logout with `b logout`.
 
 Create a wrapper for execution
 
 ```
-install -m 0755 /dev/stdin ~/.local/bin/imap-fripost-dovecot <<EOF
+install -m 0755 /dev/stdin ~/.local/bin/imap <<EOF
 #!/bin/sh
-exec /usr/lib/dovecot/imap \
- -o "mail_location=maildir:~/Maildir/fripost-dovecot" \
- -o "namespace/inbox/separator=/"
+exec doveadm -c "\${XDG_CONFIG_HOME:-\$HOME/.config}/dovecot/\$1.conf" exec imap
 EOF
 ```
 
@@ -83,7 +115,7 @@ EOF
 Put in your mutt configuration:
 
 ```
-set tunnel = "exec ~/.local/bin/imap-fripost-dovecot"
+set tunnel = "exec ~/.local/bin/imap private" # Put here what describes your account
 set folder = "imap://foo"
 set spoolfile = "imap://foo"
 ```
@@ -92,45 +124,82 @@ set spoolfile = "imap://foo"
 
 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
-``` 
+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 *~/.config/interimap/config*:
+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-fripost-dovecot
+command = exec ~/.local/bin/imap private
 null-stderr = YES
 
 [remote]
 #type = imaps
-host = imap.fripost.org
+host = imap.example.net
 #port = 993
 #proxy = socks5h://localhost:9050
-username = gustav.eek
+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
 
-*TODO The following should be replaced with a template version due to
-the "multiple account" 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
-systemctl --user enable interimap
+systemctl --user start interimap@$ACCOUNT.service
+systemctl --user enable interimap@$ACCOUNT.service
 ```
 
 In need of configuration change override the system wide configuration
@@ -138,11 +207,11 @@ In need of configuration change override the system wide configuration
 
 
 ```
-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
+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 --watch=20
+ExecStart=/usr/bin/interimap --config=%i --watch=20
 EOF
 systemctl --user daemon-reload
 ```