From 02afd821943b59533286f6bec082ad4dc8eb9498 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vedran=20Ivankovi=C4=87?= <33936733+Veki301@users.noreply.github.com> Date: Wed, 14 Jan 2026 12:03:27 +0100 Subject: [PATCH 01/10] add upgrade documentation scaffold --- mkdocs.yml | 9 +++++++++ src/README.md | 1 + src/how-to/upgrade/01-planning.md | 1 + src/how-to/upgrade/02-preparing.md | 0 src/how-to/upgrade/03-upgrade.md | 0 src/how-to/upgrade/04-troubleshooting.md | 0 src/how-to/upgrade/README.md | 14 ++++++++++++++ 7 files changed, 25 insertions(+) create mode 100644 src/how-to/upgrade/01-planning.md create mode 100644 src/how-to/upgrade/02-preparing.md create mode 100644 src/how-to/upgrade/03-upgrade.md create mode 100644 src/how-to/upgrade/04-troubleshooting.md create mode 100644 src/how-to/upgrade/README.md diff --git a/mkdocs.yml b/mkdocs.yml index 5cdd29d..f9d5285 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,6 +31,15 @@ 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 - Administration: - Overview: how-to/administrate/README.md - kubernetes: how-to/administrate/kubernetes/README.md diff --git a/src/README.md b/src/README.md index ecc8869..c669f29 100644 --- a/src/README.md +++ b/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) diff --git a/src/how-to/upgrade/01-planning.md b/src/how-to/upgrade/01-planning.md new file mode 100644 index 0000000..73433ea --- /dev/null +++ b/src/how-to/upgrade/01-planning.md @@ -0,0 +1 @@ +# Planning \ No newline at end of file diff --git a/src/how-to/upgrade/02-preparing.md b/src/how-to/upgrade/02-preparing.md new file mode 100644 index 0000000..e69de29 diff --git a/src/how-to/upgrade/03-upgrade.md b/src/how-to/upgrade/03-upgrade.md new file mode 100644 index 0000000..e69de29 diff --git a/src/how-to/upgrade/04-troubleshooting.md b/src/how-to/upgrade/04-troubleshooting.md new file mode 100644 index 0000000..e69de29 diff --git a/src/how-to/upgrade/README.md b/src/how-to/upgrade/README.md new file mode 100644 index 0000000..51ceeb2 --- /dev/null +++ b/src/how-to/upgrade/README.md @@ -0,0 +1,14 @@ +# 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) From 228646e9682215d537c132d2d7c2e097c8274265 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vedran=20Ivankovi=C4=87?= <33936733+Veki301@users.noreply.github.com> Date: Wed, 14 Jan 2026 12:03:46 +0100 Subject: [PATCH 02/10] add upgrade configuration references documents --- src/how-to/upgrade/05-config-reference.md | 39 +++++++++ .../config-references/wire-server-5.24.0.md | 83 +++++++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 src/how-to/upgrade/05-config-reference.md create mode 100644 src/how-to/upgrade/config-references/wire-server-5.24.0.md diff --git a/src/how-to/upgrade/05-config-reference.md b/src/how-to/upgrade/05-config-reference.md new file mode 100644 index 0000000..114dde2 --- /dev/null +++ b/src/how-to/upgrade/05-config-reference.md @@ -0,0 +1,39 @@ +# 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) + +## 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. diff --git a/src/how-to/upgrade/config-references/wire-server-5.24.0.md b/src/how-to/upgrade/config-references/wire-server-5.24.0.md new file mode 100644 index 0000000..ed4bb98 --- /dev/null +++ b/src/how-to/upgrade/config-references/wire-server-5.24.0.md @@ -0,0 +1,83 @@ +# Wire-Server 5.24.0 release + +## Mandatory (breaking) changes + +### `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 +``` From 957cefb42fb441b8a8c83eb63a281ddbb4947f02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vedran=20Ivankovi=C4=87?= <33936733+Veki301@users.noreply.github.com> Date: Wed, 14 Jan 2026 12:16:09 +0100 Subject: [PATCH 03/10] add new gundeck settings (optional ones) --- .../config-references/wire-server-5.24.0.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/how-to/upgrade/config-references/wire-server-5.24.0.md b/src/how-to/upgrade/config-references/wire-server-5.24.0.md index ed4bb98..10ee2c8 100644 --- a/src/how-to/upgrade/config-references/wire-server-5.24.0.md +++ b/src/how-to/upgrade/config-references/wire-server-5.24.0.md @@ -81,3 +81,18 @@ background-worker: 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 references in the mandatory catefory + port: 6379 + connectionMode: "master" # master | cluster + enableTls: false + insecureSkipVerifyTls: false +``` From c606cabd516554870d65510495131c5f4a16bc69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vedran=20Ivankovi=C4=87?= <33936733+Veki301@users.noreply.github.com> Date: Wed, 14 Jan 2026 12:40:22 +0100 Subject: [PATCH 04/10] add 5.24.0 release build.json to 5.24.0 reference --- src/how-to/upgrade/config-references/wire-server-5.24.0.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/how-to/upgrade/config-references/wire-server-5.24.0.md b/src/how-to/upgrade/config-references/wire-server-5.24.0.md index 10ee2c8..7319f1a 100644 --- a/src/how-to/upgrade/config-references/wire-server-5.24.0.md +++ b/src/how-to/upgrade/config-references/wire-server-5.24.0.md @@ -1,4 +1,6 @@ -# Wire-Server 5.24.0 release +# 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). ## Mandatory (breaking) changes @@ -90,7 +92,7 @@ New settings, change only if required. The following are defaults as they come i gundeck: config: redis: - host: redis-ephemeral # This one is already references in the mandatory catefory + host: redis-ephemeral # This one is already referenced in the mandatory catefory port: 6379 connectionMode: "master" # master | cluster enableTls: false From f27649ebb1e0a0b2c19a3c337c1e1df1aba94ac7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vedran=20Ivankovi=C4=87?= <33936733+Veki301@users.noreply.github.com> Date: Tue, 20 Jan 2026 04:41:48 +0100 Subject: [PATCH 05/10] add brig section, per STACKIT request --- .../upgrade/config-references/wire-server-5.24.0.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/how-to/upgrade/config-references/wire-server-5.24.0.md b/src/how-to/upgrade/config-references/wire-server-5.24.0.md index 7319f1a..97f79b2 100644 --- a/src/how-to/upgrade/config-references/wire-server-5.24.0.md +++ b/src/how-to/upgrade/config-references/wire-server-5.24.0.md @@ -4,6 +4,18 @@ The following reference was written based on the following [`build.json` charts] ## Mandatory (breaking) changes +### `brig` + +```yaml +brig: + rabbitmq: + host: rabbitmq-host-or-service + port: 5672 # default + secrets: + username: wire-server + password: verysecurepassword +``` + ### `background-worker` ```yaml From c753a70e894c1140fd15600173f904078587706a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vedran=20Ivankovi=C4=87?= <33936733+Veki301@users.noreply.github.com> Date: Tue, 3 Feb 2026 12:34:24 +0100 Subject: [PATCH 06/10] fix bad config for brig.secrets, add changelog link to the 5.24 config reference document --- src/how-to/upgrade/config-references/wire-server-5.24.0.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/how-to/upgrade/config-references/wire-server-5.24.0.md b/src/how-to/upgrade/config-references/wire-server-5.24.0.md index 97f79b2..b71acd5 100644 --- a/src/how-to/upgrade/config-references/wire-server-5.24.0.md +++ b/src/how-to/upgrade/config-references/wire-server-5.24.0.md @@ -2,6 +2,8 @@ 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` @@ -12,8 +14,9 @@ brig: host: rabbitmq-host-or-service port: 5672 # default secrets: - username: wire-server - password: verysecurepassword + rabbitmq: + username: wire-server + password: verysecurepassword ``` ### `background-worker` From 8cb9a74e86e2ac395932cc1855227c71300c2346 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vedran=20Ivankovi=C4=87?= <33936733+Veki301@users.noreply.github.com> Date: Tue, 3 Feb 2026 12:34:44 +0100 Subject: [PATCH 07/10] add config reference document for release 5.25 --- .../config-references/wire-server-5.25.0.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 src/how-to/upgrade/config-references/wire-server-5.25.0.md diff --git a/src/how-to/upgrade/config-references/wire-server-5.25.0.md b/src/how-to/upgrade/config-references/wire-server-5.25.0.md new file mode 100644 index 0000000..902af97 --- /dev/null +++ b/src/how-to/upgrade/config-references/wire-server-5.25.0.md @@ -0,0 +1,43 @@ +# 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 +``` + \ No newline at end of file From 2c3d6ce5a9dadb862a682e2ebd00d52e8dc40f55 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vedran=20Ivankovi=C4=87?= <33936733+Veki301@users.noreply.github.com> Date: Tue, 3 Feb 2026 12:38:01 +0100 Subject: [PATCH 08/10] add links to the new config reference document --- src/how-to/upgrade/05-config-reference.md | 1 + src/how-to/upgrade/README.md | 1 + 2 files changed, 2 insertions(+) diff --git a/src/how-to/upgrade/05-config-reference.md b/src/how-to/upgrade/05-config-reference.md index 114dde2..cf7efaf 100644 --- a/src/how-to/upgrade/05-config-reference.md +++ b/src/how-to/upgrade/05-config-reference.md @@ -33,6 +33,7 @@ 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 diff --git a/src/how-to/upgrade/README.md b/src/how-to/upgrade/README.md index 51ceeb2..84571fa 100644 --- a/src/how-to/upgrade/README.md +++ b/src/how-to/upgrade/README.md @@ -12,3 +12,4 @@ Complete documentation for upgrading `wire-server` deployments. ## 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) From 90df4d622fbf62fc09203231c0af772e5b4337de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vedran=20Ivankovi=C4=87?= <33936733+Veki301@users.noreply.github.com> Date: Tue, 3 Feb 2026 12:48:32 +0100 Subject: [PATCH 09/10] add new document to navbar --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index f9d5285..971fd5e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,6 +40,7 @@ nav: - 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 From 09c62420d6f32ba306ca326c27e391a052ef9ef7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vedran=20Ivankovi=C4=87?= <33936733+Veki301@users.noreply.github.com> Date: Tue, 3 Feb 2026 12:52:36 +0100 Subject: [PATCH 10/10] fix formatting --- src/how-to/upgrade/config-references/wire-server-5.25.0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/how-to/upgrade/config-references/wire-server-5.25.0.md b/src/how-to/upgrade/config-references/wire-server-5.25.0.md index 902af97..1dd5e1e 100644 --- a/src/how-to/upgrade/config-references/wire-server-5.25.0.md +++ b/src/how-to/upgrade/config-references/wire-server-5.25.0.md @@ -26,6 +26,7 @@ nginx-ingress-services: ``` Options are: + * Always (default) - regenerates key on each renewal * Never - preserves key across renewals (for key pinning)