+-----------------------------------------------------------------------
| Running stalwart-mail on OpenBSD
+-----------------------------------------------------------------------

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

The complete documentation is at https://stalw.art/docs/get-started

- By default stalwart tries to listen on the following ports:
  - smtp
  - https (for jmap and web admin)
  - imap
  - imaps
  - sieve
  - submission
  - submissions

if you want to disable some of the listeners, comment out the corresponding
server.listener section in /var/stalwart/etc/config.toml.

it is possible to check if the server is properly configured by calling
/.well-known/jmap like this:

$ curl https://<jmap_url>/.well-known/jmap
{"type":"about:blank","status":401,"title":"Unauthorized","detail":"You have to authenticate first."}
$ curl -u admin:changeme https://<jmap_url>/.well-known/jmap

- stalwart-mail starts as root, binds to ports then drops privilege to the
  unpriviledged _stalwart-smtp user.

- once installed, you need to at least initialize the administrator password:

# env ADMIN_SECRET=changeme STALWART_PATH=/var/stalwart stalwart-mail --config /var/stalwart/etc/config.toml

(or if you don't like env vars configure the
authentication.fallback-admin.secret key in /var/stalwart/etc/config.toml)

the initial startup of the server will:
- download spam filters from https://get.stalw.art/resources/config/spamfilter.toml
- download the web admin interface from https://github.com/stalwartlabs/webadmin/releases/latest/download/webadmin.zip
- rewrite its own config file

From that point, you should be able to connect as admin/changeme on the https
interface to configure the daemon/services. The web admin interface uses
WebAssembly which is switched off by default on Chromium-based browsers. You
need to enable it by setting ENABLE_WASM=1 in the environment if you want to
use the admin web interface.

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 https://localhost -cadmin:changeme domain create -d 'test domain' jmap.test

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

- import a mailbox in that account
$ stalwart-cli --url https://localhost -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-mail ip:port should show you imported messages over IMAP

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

Upgrading
=========

As being in development, stalwart-mail tends to have breaking changes often,
refer to https://github.com/stalwartlabs/mail-server/blob/main/UPGRADING.md for
upgrade notes.
