+-----------------------------------------------------------------------
| Running stalwart-jmap on OpenBSD
+-----------------------------------------------------------------------

Basic configuration gotchas
===========================

The complete documentation is at https://stalw.art/jmap/configure/overview/,
https://stalw.art/jmap/manage/overview/ &
https://stalw.art/imap/configure/overview, but here are some tips and tricks:

- stalwart-imap isn't mandatory at all, it's only here to provide IMAP access to
clients which don't support JMAP.

- JMAP clients should be configured to use the url specified in jmap-url, which
should be the public FQDN of the service configured in a reverse-proxy.

- The default credentials to manage stalwart-jmap via stalwart-cli are
admin:changeme.

- By default stalwart-jmap listens on port 8080, it is possible to check if the
server is properly configured by calling /.well-known/jmap like this:

$ curl -u admin:changeme http://localhost:8080/.well-known/jmap

- To be able to run stalwart-imap as an unprivileged user, the default ports to
bind were changed in the sample config for 1143 for plaintext/STARTTLS and 1993
for TLS. It is advised to use pf to redirect default 143/993 port to those
instead of running stalwart-imap as root.

Certificates
============

If you want to expose directly stalwart-jmap to the internet over HTTPS, a real
certificate (potentially generated via acme-client(1) against a
letsencrypt-compatible authority) is required for jmap-cert-path. A selfsigned
cert won't work.

It is possible to use selfsigned certificates for lmtp-cert-path &
rpc-cert-path. In all cases, the rust library used to handle certificates
expects keys to be in PKCS #8 format, while openssl/acme-client(1) generate
keys in PKCS #1 format.

One can convert from PKCS #1 to PKCS #8 using:

# openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in pkcs1.key -out pkcs8.key

It's generally easier to delegate TLS to a reverse-proxy such as nginx or
relayd(8).  To disable TLS in daemons, just comment the various *-cert-path &
*-key-path config keys.

Using stalwart-cli to manage the server
=======================================

stalwart-cli allows to manage:
- domains
- accounts
- imports
- lists & groups

the following commands should give you a headstart to:
- create a domain
$ stalwart-cli --url http://localhost:8080 -cadmin:changeme domain create -d 'test domain' jmap.test

- create an account in that domain
$ stalwart-cli --url http://localhost:8080 -cadmin:changeme account create user@jmap.test password accountname

- import a mailbox in that account
$ stalwart-cli --url http://localhost:8080 -cadmin:changeme import messages -f mbox user@jmap.test /var/mail/user

from that point:
- an IMAP client such as mutt or meli or thunderbird configured
  to point at stalwart-imap ip:port should show you imported messages over IMAP

- a JMAP client such as meli or cypht.org configured to point at
  stalwart-jmap jmap-url should show you messages over JMAP.
