stalwart/UPGRADING/v0_05.md

Upgrading from v0.5.2 to v0.5.3

• The following configuration attributes have been renamed, see store.toml for an example:
  • jmap.store.data -> storage.data
  • jmap.store.fts -> storage.fts
  • jmap.store.blob -> storage.blob
  • jmap.encryption.* -> storage.encryption.*
  • jmap.spam.header -> storage.spam.header
  • jmap.fts.default-language -> storage.fts.default-language
  • jmap.cluster.node-id -> storage.cluster.node-id
  • management.directory and sieve.trusted.default.directory -> storage.directory
  • sieve.trusted.default.store -> storage.lookup
• Proxy networks are now configured under server.proxy.trusted-networks rather than server.proxy-trusted-networks. IP addresses/masks have to be defined within a set ({}) rather than a list ([]), see server.toml for an example.

Upgrading from v0.5.1 to v0.5.2

• Make sure that implicit TLS is enabled for the JMAP listener configured under ets/jmap/listener.toml:

  [server.listener."jmap".tls]
  implicit = true
  

• Optional: Enable automatic TLS with ACME.
• Replace the binary with the new version.
• Restart the service.

Upgrading from v0.5.0 to v0.5.1

• Replace the binary with the new version.
• Restart the service.

Upgrading from v0.4.x to v0.5.0

What's changed

• Database Layout: Version 0.5.0 utilizes a different database layout which is more efficient and allows multiple backends to be supported. For this reason, the database must be migrated to the new layout.
• Configuration file changes: The configuration file has been updated to support multiple stores, most configuration attributes starting with store.* and directory.* need to be reviewed.
• SPAM filter: Sieve scripts that interact with databases need to be updated. The functions lookup and lookup_map has been renamed to key_exists and key_get. It is recommended to replace all scripts with the new versions rather than updating them manually. Additionally, the SPAM database no longer requires an SQL server, it can now be stored in Redis or any of the supported databases.
• Directory superusers: Due to problems and confusion with the superuser-group attribute, the concept of a superuser group has been removed. Instead, a new attribute type has been added to external directories. The value of this attribute can be individual, group or admin. The admin type is equivalent to the old superuser group. The type attribute is required for all principals in the directory, it defaults to individual if not specified.
• Purge schedules: The attributes jmap.purge.schedule.db and jmap.purge.schedule.blobs have been removed. Instead, the purge frequency is now specified per store in store.<name>.purge.frequency. The attribute jmap.purge.schedule.sessions has been renamed to jmap.purge.sessions.frequency.

What's been added

• Multiple stores: The server now supports multiple stores to be defined in the configuration file under store.<name>. Which store to use is defined in the jmap.store.data, jmap.store.fts and jmap.store.blob settings.
• More backend options: It is now possible to use RocksDB, PostgreSQL and MySQL as data stores. It is also now possible to store blobs in any of the supported databases instead of being limited to the filesystem or an S3-compatible storage. Full-text indexing can now be done using Elasticsearch and the Spam database stored in Redis.
• Internal Directory: The server now has an internal directory that can be used to store user accounts, passwords and group membership. This directory can be used instead of an external directory such as LDAP or SQL.
• New settings: When running Stalwart in a cluster, jmap.cluster.node-id allows to specify a unique identifier for each node. Messages containing the SPAM headers defined in jmap.spam.header are moved automatically to the user's Junk Mail folder.
• Default Sieve stores: For Sieve scripts such as the Spam filter that require access to a directory and a lookup store, it is now possible to configure the default lookup store and directory using the sieve.trusted.default.directory and sieve.trusted.default.store settings.

Migration Steps

Rather than manually updating the configuration file, it is recommended to start with a fresh configuration file and update it with the necessary settings:

• Install v0.5.0 in a distinct directory. You now have the option to use an internal directory, which will allow you to manage users and groups directly from Stalwart server. Alternatively, you can continue to use an external directory such as LDAP or SQL.
• Update the configuration files with your previous settings. All configuration attributes are backward compatible, except those starting with store.*, directory.* and jmap.purge.*.
• Export each account following the procedure described in the migration guide.
• Stop the old v0.4.x server.
• If there are messages pending to be delivered in the SMTP queue, move the queue directory to the new installation.
• Start the new v0.5.0 server.
• Import each account following the procedure described in the migration guide.

Once again, we apologize for the lack of an automated migration tool for this upgrade. However, we are planning on introducing an automated migration tool once the web-admin is released in Q1 2024. Thank you for your understanding and patience.