aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGuilhem Moulin <guilhem@fripost.org>2019-07-09 05:21:26 +0200
committerGuilhem Moulin <guilhem@fripost.org>2019-08-28 12:17:30 +0200
commiteeb05129383b802b8e9b98ecaa592ce90e3d2be4 (patch)
treef55a875b947e393ee77bc85bbaf1838a4651dcba
parentab6bc80e9935b7c2144300216b0c7e4cc2e1f73a (diff)
Improve presentation of interimap config.wip-getting-started
-rw-r--r--doc/getting-started.md94
-rwxr-xr-xtests/run2
2 files changed, 69 insertions, 27 deletions
diff --git a/doc/getting-started.md b/doc/getting-started.md
index d8f92d5..bc23b3a 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -163,34 +163,71 @@ Create directories for the InterIMAP configuration and data files:
$ install -m0700 -vd ${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:
+Create the configuration file. The included sample file
+`/usr/share/doc/interimap/interimap.sample` can be used as baseline, but
+for the sake of clarity we start from an empty file here.
+
+ $ install -m0600 /dev/null ${XDG_CONFIG_HOME:-~/.config}/interimap/config
+
+ 1. The file is in [INI format][INI file]. First, set general options
+ in the default section:
+
+ $ cat >${XDG_CONFIG_HOME:-~/.config}/interimap/config <<-EOF
+ # only consider subscribed mailboxes
+ list-select-opts = SUBSCRIBED
+ #list-mailbox = "*"
+
+ # ignore the mailbox named 'virtual' and its descendants
+ # WARN: for <=0.4 it should be: ^virtual(?:/|$)
+ ignore-mailbox = ^virtual(?:\x00|$)
+
+ EOF
+
+ 2. Next, append a `[local]` section pointing to the wrapper defined
+ above:
+
+ $ cat >>${XDG_CONFIG_HOME:-~/.config}/interimap/config <<-EOF
+ [local]
+ type = tunnel
+ command = exec ~/.local/bin/dovecot-imap
+
+ EOF
+
+ 3. And finally append a `[remote]` section with your account
+ information at `imap.example.org` (adapt the values accordingly):
+
+ $ cat >>${XDG_CONFIG_HOME:-~/.config}/interimap/config <<-EOF
+ [remote]
+ type = imaps
+ host = imap.example.net
+ username = myname
+ password = xxxxxxxx
+ EOF
+
+At this point running [`interimap`(1)] should create the database and
+copy the entire remote mail store locally. (If `~/Mail` was not empty,
+it will also copy its content remotely, possibly *yielding duplicates*.)
+Depending on the volume of messages this might take a while.
$ interimap
- Creating new schema in database file …/interimap.db
+ Creating new schema in database file …/imap.example.net.db
database: Created mailbox INBOX
[…]
-Override systemd unit if desired, for instance to reduce the interval
-between synchronization runs to 20s:
+A user unit for systemd is provided. To enable and start the service,
+simply run the following command:
+
+ $ systemctl --user enable --now interimap
+
+By default the connection to the IMAP servers remains open, and a status
+update is requested every minute. Thanks to the [`QRESYNC`][RFC 7162]
+IMAP extension a status update scales linearly with the number of
+mailboxes (not to the number of messages like [OfflineIMAP]). And
+thanks to the `COMPRESS` extension, the typical volume of data exchanged
+is rather small (*TODO* metrics). You may want to override the default
+settings, and for instance reduce the interval between status updates to
+20s:
$ mkdir -p ${XDG_CONFIG_HOME:-~/.config}/systemd/user/interimap.service.d
<!-- -->
@@ -201,10 +238,8 @@ between synchronization runs to 20s:
EOF
<!-- -->
$ systemctl --user daemon-reload
-
-Enable unit and start it:
-
- $ systemctl --user enable --now interimap
+<!-- -->
+ $ systemctl --user restart interimap
Configure email client
@@ -221,7 +256,14 @@ Put in your mutt configuration (XXX):
$ mutt -n -F /tmp/muttrc
+Further Reading and Resources
+=============================
+
+Manual, links to other use-case, benchmarks, etc.
+
+
[IMAP4rev1]: https://tools.ietf.org/html/rfc3501
+[INI file]: https://en.wikipedia.org/wiki/INI_file
[`interimap`(1)]: interimap.1.html
[LMTP server]: https://wiki.dovecot.org/LMTP
[Maildir]: https://en.wikipedia.org/wiki/Maildir
diff --git a/tests/run b/tests/run
index ee11757..a01300e 100755
--- a/tests/run
+++ b/tests/run
@@ -99,7 +99,7 @@ prepare() {
fi
cat >>"$HOME_local/.config/interimap/config$cfg" <<-EOF
database = $u.db
-
+
[local]
type = tunnel
command = exec ${HOME_local@Q}/.local/bin/doveadm exec imap