WIP: Add upgrade documentation and references

mkdocs.yml

@@ -31,6 +31,16 @@ nav:
       - Using tinc: how-to/install/ansible-tinc.md
       - Troubleshooting during installation: how-to/install/troubleshooting.md
       - Verifying your installation: how-to/install/post-install.md
+  - Upgrade:
+      - Overview: how-to/upgrade/README.md
+      - Planning an upgrade: how-to/upgrade/01-planning.md
+      - Preparing an upgrade: how-to/upgrade/02-preparing.md
+      - Upgrade process: how-to/upgrade/03-upgrade.md
+      - Troubleshooting: how-to/upgrade/04-troubleshooting.md
+      - Configuration Reference:
+        - Overview: how-to/upgrade/05-config-reference.md
+        - Wire Server 5.24: how-to/upgrade/config-references/wire-server-5.24.0.md
+        - Wire Server 5.25: how-to/upgrade/config-references/wire-server-5.25.0.md
   - Administration:
       - Overview: how-to/administrate/README.md
       - kubernetes: how-to/administrate/kubernetes/README.md

src/README.md

@@ -20,6 +20,7 @@ Release notes of `wire-server` can be found [here](https://github.com/wireapp/wi
 # Contents:
 
 * [Installation](how-to/install/README.md)
+* [Upgrade](how-to/upgrade/README.md)
 * [Administration](how-to/administrate/README.md)
 * [Reference](understand/README.md)
 * [Developers Notes](developer/README.md)

src/how-to/upgrade/01-planning.md

@@ -0,0 +1 @@
+# Planning

src/how-to/upgrade/05-config-reference.md

@@ -0,0 +1,40 @@
+# Configuration Reference
+
+## Overview
+
+These references outline configuration changes between `wire-server` versions.
+It is intended for users who:
+
+- Maintain custom deployment templates
+- Use non-standard `wire-server-deploy` Ansible/Helm deployment
+- Need to know exact configuration changes to adapt their setups
+
+## Categories
+
+- Mandatory (breaking) changes - configuration changes that **must** be applied or services will fail to start
+- Optional changes - new features, enhancements or monitoring/logging options
+- Deprecated - configuration settings that can be removed or omitted, have no impact on the upgrade
+
+## How to use
+
+### Identify your versions
+
+- Current version you are running
+- Target version you want to upgrade to
+
+### Review all intermediate versions
+
+Configuration changes are cumulative. Review each version reference for mandatory changes.
+
+### Apply config to your templates
+
+Apply each configuration change to your templates as applicable to your model.
+
+## References
+
+- [Wire Server 5.24.0](config-references/wire-server-5.24.0.md)
+- [Wire Server 5.25.0](config-references/wire-server-5.25.0.md)
+
+## Contributing
+
+If you find configuration changes not documented here, please report them to us directly or through a GitHub issue in our [documentation repository](https://github.com/wireapp/wire-docs). Include version numbers, configuration section and exact change needed.

src/how-to/upgrade/README.md

@@ -0,0 +1,15 @@
+# Wire Server Upgrade Guide (WIP)
+
+Complete documentation for upgrading `wire-server` deployments.
+
+## 1. [Planning an upgrade](01-planning.md)
+
+## 2. [Preparing for an upgrade](02-preparing.md)
+
+## 3. [Upgrade process](03-upgrade.md)
+
+## 4. [Troubleshooting](04-troubleshooting.md)
+
+## 5. [Configuration Reference](05-config-reference.md)
+  - [Wire Server 5.24.0](config-references/wire-server-5.24.0.md)
+  - [Wire Server 5.25.0](config-references/wire-server-5.25.0.md)

src/how-to/upgrade/config-references/wire-server-5.24.0.md

@@ -0,0 +1,115 @@
+# Wire-Server 5.24.0 release
+
+The following reference was written based on the following [`build.json` charts](https://raw.githubusercontent.com/wireapp/wire-builds/79660a72c74c8644fb3717bd147368e4c5848117/build.json).
+
+For additional details, you can also read our [release chagelog](https://github.com/wireapp/wire-server/releases/tag/v2025-11-26).
+
+## Mandatory (breaking) changes
+
+### `brig`
+
+```yaml
+brig:
+  rabbitmq:
+    host: rabbitmq-host-or-service
+    port: 5672 # default
+  secrets:
+    rabbitmq:
+      username: wire-server
+      password: verysecurepassword
+```
+
+### `background-worker`
+
+```yaml
+background-worker:
+  config:
+    federationDomain: "example.com" # must match federation domain used for the instance in other services (brig etc.)
+    cassandraBrig:
+      host: your-cassandra-host-or-service # same as your current cassandra.host value
+    cassandraGalley:
+      host: your-cassandra-host-or-service # same as your current cassandra.host value
+```
+
+#### Conversation Data Migration
+
+The following configuration is only mandatory if you decide to migrate conversation data to PostgreSQL at this stage.
+
+Starting this release, migrating conversation data to PostgreSQL from Cassandra is possible. This is only required for channel search and channel management from Team Settings. Follow [this document](../../../developer/reference/config-options.md#using-postgresql-for-storing-conversation-data) for the steps and configuration required.
+
+If you do so, the following configurations are for `background-worker` are required.
+
+```yaml
+background-worker:
+  config:
+    postgresql:
+      host: your-postgresql-host-or-service
+```
+
+And for secrets:
+
+```yaml
+background-worker:
+  secrets:
+    pgPassword: "your-postgresql-password"
+```
+
+### `gundeck`
+
+Upstream Helm chart for `redis-ephemeral` has been replaced. New Redis service hostname has been changed from `{{ .Release.Name }}-master` to `{{ .Release.Name }}`. Verify your Redis service name with:
+
+```bash
+kubectl get svc | grep redis
+```
+
+Then set accordingly:
+
+```yaml
+gundeck:
+  config:
+    redis:
+      host: "your-redis-service"
+```
+
+## Optional changes
+
+### `background-worker`
+
+New settings, change only if required. The following are defaults as they come in charts
+
+```yaml
+background-worker:
+  postgresql:
+    host: postgresql # This one is already referenced in the mandatory category
+    port: "5432"
+    user: wire-server
+    dbname: wire-server
+  # Background jobs consumer configuration
+  backgroundJobs:
+    # Maximum number of in-flight jobs per process
+    concurrency: 8
+    # Per-attempt timeout in seconds
+    jobTimeout: 60s
+    # Total attempts, including the first try
+    maxAttempts: 3
+  postgresqlPool:
+    size: 5
+    acquisitionTimeout: 10s
+    agingTimeout: 1d
+    idlenessTimeout: 10m
+```
+
+### `gundeck`
+
+New settings, change only if required. The following are defaults as they come in charts
+
+```yaml
+gundeck:
+  config:
+    redis:
+      host: redis-ephemeral # This one is already referenced in the mandatory catefory
+      port: 6379
+      connectionMode: "master" # master | cluster
+      enableTls: false
+      insecureSkipVerifyTls: false
+```    

src/how-to/upgrade/config-references/wire-server-5.25.0.md

@@ -0,0 +1,44 @@
+# Wire-Server 5.25.0 release
+
+The following reference was written based on the following [`build.json` charts](https://raw.githubusercontent.com/wireapp/wire-builds/5a74084feeb1138925dcb671b333da0c76f88f08/build.json).
+
+For additional details, you can also read our [release changelog](https://github.com/wireapp/wire-server/releases/tag/v2026-01-13).
+
+## Mandatory (breaking) changes
+
+No mandatory changes in comparison to the last release.
+
+## Optional changes
+
+### `nginx-ingress-services`
+
+Support for `cert-manager` certificate private key rotation policy has been added in this release. This allows preserving private keys across certificate renewals for client key pinning scenarios in both federator and ingress certificates. The following shown are defaults as they come in charts from referenced `build.json`.
+
+```yaml
+nginx-ingress-services:
+  federator:
+    tls:
+      privateKey:
+        rotationPolicy: Always
+  tls:
+    privateKey:
+      rotationPolicy: Always
+```
+
+Options are:
+
+* Always (default) - regenerates key on each renewal
+* Never - preserves key across renewals (for key pinning)
+
+### `background-worker`
+
+Configuring page size and parallelism for conversation migration to PostgreSQL is now possible. This can be configured like this:
+
+```yaml
+background-worker:
+  config:
+    migrateConversationsOptions:
+      pageSize: 10000
+      parallelism: 2
+```
+