> For the complete documentation index, see [llms.txt](https://docs.zigiwave.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zigiwave.com/installation-and-deployment/upgrade.md).

# Upgrade

How to move your ZigiOps instance to a newer release while keeping your existing configuration intact.

### ZigiOps upgrade path

ZigiOps supports upgrading from previous versions while retaining your existing configuration. To upgrade successfully, first identify your current ZigiOps release, then follow the standard upgrade instructions together with any release-specific steps that apply between your current version and the version you want to reach.

{% hint style="info" %}
**Example:** If you are currently running ZigiOps 2021.01.x and want to upgrade to ZigiOps 2024.04.x, you must apply the release-specific instructions for every version between your current release and the target release, in order.
{% endhint %}

ZigiOps upgrade path: apply release-specific steps in sequence between your current and target versions.

### Upgrade instructions

{% stepper %}
{% step %}
**Stop ZigiOps**

{% endstep %}

{% step %}
**Back up the existing installation**

Back up the existing ZigiOps installation folder to another location.

* Linux only, if ZigiOps was installed as a service: back up the ZigiOps service file (`/etc/systemd/system/zigiwave.service`).
  {% endstep %}

{% step %}
**Install the new release**

Start the installation of the new ZigiOps release in your existing ZigiOps installation folder.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
You must follow the corresponding release-specific instructions for every release between your current and desired version. If none of the versions in between require release-specific steps, you can skip that section and continue with the rest of the upgrade.
{% endhint %}

#### Release-specific instructions

Some ZigiOps releases require extra steps during the upgrade. The table below summarizes them; expand each entry for the full instructions.

| ZigiOps release | Required action                                                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2021.07.648     | Delete the `/conf/settings/accounts`, `/conf/settings/credentials`, and `/conf/settings/users` folders.                                                             |
| 2021.10.145     | Remove the `key-password` and `key-manager-pass` lines from `/conf/config.properties` and save the file.                                                            |
| 2023.01.191     | Delete the contents of the `/conf/settings/queries` folder.                                                                                                         |
| 2023.08.2.18    | Replace Java 8 (64-bit) with Oracle Java 17 (64-bit) or Open Java 17 (64-bit), update `JAVA_HOME`, and redeploy the ZigiOps service with the **OS Service** option. |
| 2024.05.1.303   | Redeploy the ZigiOps service with the **OS Service** option to pick up the new startup parameters introduced in this release.                                       |

<details>

<summary>ZigiOps 2021.07.648 (release-specific steps)</summary>

Delete the following folders:

* `/conf/settings/accounts`
* `/conf/settings/credentials`
* `/conf/settings/users`

</details>

<details>

<summary>ZigiOps 2021.10.145 (release-specific steps)</summary>

Remove the following lines from the `/conf/config.properties` file and save the changes afterward:

* `key-password`
* `key-manager-pass`

</details>

<details>

<summary>ZigiOps 2023.01.191 (release-specific steps)</summary>

Delete the contents of the `/conf/settings/queries` folder.

</details>

<details>

<summary>ZigiOps 2023.08.2.18 (release-specific steps)</summary>

{% stepper %}
{% step %}

## Uninstall Java 8

Uninstall the old Java 8 (64-bit) from the ZigiOps host and restart it.
{% endstep %}

{% step %}

## Install Java 17

Install Oracle Java 17 (64-bit) or Open Java 17 (64-bit).

* Ensure the `JAVA_HOME` variable is set to the Java 17 deployment.
  {% endstep %}

{% step %}

## Redeploy the ZigiOps service

Redeploy the ZigiOps service so the platform picks up the new Java 17 deployment required by this release.

* Select the **OS Service** option during the installation.
  {% endstep %}
  {% endstepper %}

</details>

<details>

<summary>ZigiOps 2024.05.1.303 (release-specific steps)</summary>

Redeploy the ZigiOps service, since this release introduces new startup parameters.

* Select the **OS Service** option during the installation.

</details>

After completing the applicable release-specific steps:

* Wait for the installation to finish, then start the ZigiOps service or process.
* Go to the **Connected Systems** page and confirm that the test connection is successful.
* Go to the **Configurator** page, then select and enable the integration template you need.
* Confirm that the integration works as expected.

### Backout plan

If you need to revert to the previous version after an upgrade, follow these steps.

{% stepper %}
{% step %}
**Stop ZigiOps**

{% endstep %}

{% step %}
**Restore the previous backup**

Restore the previous version's backup to the application's installation folder, replacing all files.
{% endstep %}

{% step %}
**Start ZigiOps**

{% endstep %}
{% endstepper %}

### Backout plan: from ZigiOps 2024.11.3.173 (or newer) to an earlier release

{% hint style="warning" %}
The ZigiOps 2024.11.3.173 release introduced a service-oriented architecture (SOA). Because of this change, reverting to a version older than 2024.11.3.173 requires additional steps beyond the standard backout plan.
{% endhint %}

#### Windows

{% stepper %}
{% step %}
**Stop ZigiOps**

{% endstep %}

{% step %}
**Uninstall the ZigiOps SOA release and its services**

* Run `C:\ZigiWave\ZigiOps\webapp\service\uninstall_service.bat` to uninstall the **ZigiOps Web App** service.
* Run `C:\ZigiWave\ZigiOps\platform\service\uninstall_service.bat` to uninstall the **ZigiOps Platform** service.
* Manually delete the ZigiOps installation folder, typically `C:\ZigiWave\ZigiOps`, unless a different location was specified during installation.
  {% endstep %}

{% step %}
**Restore the ZigiOps installation**

Restore the ZigiOps installation from your backup.
{% endstep %}

{% step %}
**Reinstall the old ZigiOps service**

Run `C:\ZigiWave\ZigiOps\service\install_service.bat` to reinstall the old (non-SOA) ZigiOps service.
{% endstep %}

{% step %}
**Start ZigiOps**
{% endstep %}
{% endstepper %}

#### Linux

{% stepper %}
{% step %}
**Stop ZigiOps**

{% endstep %}

{% step %}
**Uninstall the ZigiOps SOA release and its services**

* Delete the `/etc/systemd/system/zigiwave_webapp.service` **ZigiOps Web App** service file (skip this step if you did not install the ZigiOps services).
* Delete the `/etc/systemd/system/zigiwave_platform.service` **ZigiOps Platform** service file (skip this step if you did not install the ZigiOps services).
* Manually delete the ZigiOps installation folder, typically `/opt/zigiwave/zigiops`, unless a different location was specified during installation.
  {% endstep %}

{% step %}
**Restore the ZigiOps installation**

Restore the ZigiOps installation from your backup.

* Linux only, if ZigiOps was installed as a service: restore the old (non-SOA) `zigiwave.service` file from your backup to the `/etc/systemd/system/` folder.
  {% endstep %}

{% step %}
**Start ZigiOps**
{% endstep %}
{% endstepper %}

### Frequently asked questions

<details>

<summary>Can I upgrade ZigiOps directly to the latest version?</summary>

Only if no release-specific instructions apply between your current release and the target release. If any release in between has release-specific instructions, apply them in order before moving on.

</details>

<details>

<summary>Does upgrading ZigiOps affect my existing configuration?</summary>

No. The new release is installed directly into your existing ZigiOps installation folder, so your configuration is retained.

</details>

<details>

<summary>What changed with the ZigiOps 2024.11.3.173 release?</summary>

This release introduced a service-oriented architecture (SOA) that splits the platform into separate Web App and Platform services. Reverting from this release or a newer one to an earlier version requires the additional backout steps described above.

</details>

Related: [System Requirements](broken://pages/2a29c8fdcf7ac221fe2e700aa9fa7098d15af13a) · [Scaling and Sizing](broken://pages/9dbd8c4a45a154938a2973ab5707557214ffd558) · [Install on Linux](broken://pages/d0392c9513ad033363f5927ccf234c3e58838c96) · [Install on Windows](broken://pages/3bfc9bf28885539358e09083d9b248c1667540ee)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zigiwave.com/installation-and-deployment/upgrade.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.