Update UPGRADING

UPGRADING.md

@@ -1,3 +1,64 @@
+Upgrading from `v0.12.x` (and `v0.11.x`) to `v0.13.x`
+------------------------------------
+
+## Important Notes
+
+Version `0.13.x` introduces a significant redesign of the MTA’s delivery and queueing subsystem. This includes a transition to a new message queue serialization format and a move to a strategy-based configuration model for routing, scheduling, and delivery control. Upon first launch of version `0.13.0`, any messages currently in the outbound queue will be automatically migrated to the new format. This migration is handled internally and does not require manual intervention.
+
+However, if your deployment includes custom routing rules or queueing logic, it is important to manually reconfigure those settings using the new strategy framework. The previous configuration format for routing is no longer compatible and will need to be updated. For systems that rely solely on the default configuration, no changes are required and the upgrade should proceed without issue.
+
+Even if your system uses the default settings, it is strongly recommended to read the accompanying [blog announcement](https://stalw.art/blog/virtual-queues) and consult the [updated documentation](https://stalw.art/docs/mta/outbound/overview). These resources provide a full overview of the new delivery architecture and can help you determine whether any adjustments are needed for your environment.
+
+Before applying the upgrade to a production system, take time to familiarize yourself with the new configuration structure and validate that your delivery behavior aligns with the new model.
+
+## Step-by-Step Upgrade Process
+
+- Stop Stalwart in **every single node of your cluster**. If you are using the systemd service, you can do this with the following command:
+
+  ```bash
+  $ sudo systemctl stop stalwart
+  ```
+
+- Backup your data following your database system's instructions. For example, if you are using RocksDB or SQLite, you can simply copy the `data` directory to a backup location. If you are using PostgreSQL or MySQL, you can use the `pg_dump` or `mysqldump` commands to create a backup of your database. If your database does not support backups, you can use the [built-in migration utility](https://stalw.art/docs/management/migration) to export your data to a file. For example:
+
+  ```bash
+  $ sudo /opt/stalwart/bin/stalwart --config /opt/stalwart/etc/config.toml --export /opt/stalwart/export
+  $ sudo chown -R stalwart:stalwart /opt/stalwart/export
+  ```
+
+- Download the `v0.13.x` binary for your platform from the [releases page](https://github.com/stalwartlabs/stalwart/releases/latest/) and replace the binary in `/opt/stalwart/bin`. 
+
+- Start the service. In a cluster, you can speed up the migration process by starting all nodes at once. 
+  ```bash
+  $ sudo systemctl start stalwart
+  ```
+
+- Upgrade the webadmin by clicking on `Manage` > `Maintenance` > `Update Webadmin`.
+
+## Step-by-Step Upgrade Process (Docker)
+
+- Stop the Stalwart container in **every single node of your cluster**. If you are using Docker, you can do this with the following command:
+
+  ```bash
+  $ docker stop stalwart
+  ```
+
+- Backup your data following your database system's instructions. For example, if you are using RocksDB or SQLite, you can simply copy the `data` directory to a backup location. If you are using PostgreSQL or MySQL, you can use the `pg_dump` or `mysqldump` commands to create a backup of your database. If your database does not support backups, you can use the `--export` command to export your data to a file. For example:
+
+  ```bash
+  $ docker run --rm -v <STALWART_DIR>:/opt/stalwart -it stalwart /usr/local/bin/stalwart --config /opt/stalwart/etc/config.toml --export /opt/stalwart/export
+  ```
+
+- Pull the latest image and restart the container:
+
+  ```bash
+  $ docker pull stalwartlabs/stalwart:latest
+  $ docker start stalwart
+  ```
+  
+- Upgrade the webadmin by clicking on `Manage` > `Maintenance` > `Update Webadmin`.
+
+
 Upgrading from `v0.11.x` to `v0.12.x`
 ------------------------------------