diff options
Diffstat (limited to 'doc/getting-started.md')
| -rw-r--r-- | doc/getting-started.md | 94 |
1 files changed, 68 insertions, 26 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 |