# How to upgrade to Wowza Video Intelligence Framework 1.1.0

**Applies to Wowza Video Intelligence Framework (VIF) 1.1.0**

This guide explains how to upgrade an existing VIF 1.0.x installation to 1.1.0. It's for
anyone running VIF via Docker Compose or as a manually installed plugin on Wowza Streaming
Engine (WSE). Wowza Streaming Engine 4.11.1 or later is still required.

VIF REST API v1 is deprecated
1.1.0 introduces the VIF REST API v2. **The v1 API is deprecated, and Wowza strongly urges
customers to move any integration to v2.** The v1 endpoints still answer for compatibility,
but writing configuration through v1 silently breaks settings saved through 1.1.0. See
[After the upgrade](#after-the-upgrade-write-configuration-through-the-v2-api-only) below.

Info
If you run VIF using the Docker-based setup, upgrading is usually just pulling the 1.1.0
images and recreating the containers. The only exception is if your Engine `conf/`
directory is persisted from a 1.0.x install (a volume or bind mount): in that case, also
complete [Allow the new REST headers in Server.xml](#allow-the-new-rest-headers-in-serverxml)
below.

## Before you begin

### Back up your configuration

VIF 1.1.0 saves configuration in a new format that 1.0.x cannot fully read. Back up your
existing configuration before you upgrade, so you have a way back if something goes wrong:


```shell
cp -a /usr/local/WowzaStreamingEngine/conf.modules/vif \
      /usr/local/WowzaStreamingEngine/conf.modules/vif.backup-1.0
```

Keep this backup until you're confident you won't need to [roll back](#rolling-back-to-10x).

## Choose your upgrade path

- **[Docker Compose installations](#docker-compose-installations)** - pull new images and
recreate containers; only one manual step, and only if it applies to you.
- **[Standalone plugin installations](#standalone-plugin-installations)** - four manual
steps, updating Server.xml, the plugin, and the Manager UI, then restarting and verifying.


### Docker Compose installations

1. If your Engine `conf/` directory is persisted from a 1.0.x install, complete
[Allow the new REST headers in Server.xml](#allow-the-new-rest-headers-in-serverxml)
against that persisted file. If your `conf/` directory is not persisted, skip to step 2.
The 1.1.0 image already ships this change.
2. Pull the 1.1.0 images and recreate the containers.
3. Complete [Restart and verify](#restart-and-verify).


### Standalone plugin installations

1. [Allow the new REST headers in Server.xml](#allow-the-new-rest-headers-in-serverxml).
2. [Update the plugin](#update-the-plugin-standalone-installations-only).
3. [Update the Manager UI](#update-the-manager-ui-standalone-installations-only). Don't skip this step.
4. [Restart and verify](#restart-and-verify).


## Allow the new REST headers in Server.xml

The Manager pages call the Engine REST API from your browser (Manager on port 8088, Engine
REST API on port 8087), and 1.1.0's save handshake uses two HTTP headers that the 1.0.x
policy doesn't allow.

Warning
Without this change, every page loads normally, but every save fails. This is the most
common symptom of an incomplete upgrade.

In `/usr/local/WowzaStreamingEngine/conf/Server.xml`, find `<RESTInterface>` and set the
`restUserHTTPHeaders` property inside its `<Properties>` to exactly:


```xml
<Property>
	<Name>restUserHTTPHeaders</Name>
	<Value>Access-Control-Allow-Origin:*|Access-Control-Allow-Methods:GET,POST,PUT,DELETE,PATCH,OPTIONS|Access-Control-Allow-Headers:Content-Type,Authorization,If-Match|Access-Control-Expose-Headers:ETag</Value>
	<Type>String</Type>
</Property>
```

If the property already exists (it does on most 1.0.x installs), replace its value. The
1.0.x value is missing `If-Match` and the whole `Access-Control-Expose-Headers` part. Add
the property if it's missing entirely.

**Docker:** the 1.1.0 image ships this `Server.xml` change already. You only need to make
this change yourself if your `conf/` directory is persisted (a volume or bind mount) from a
1.0.x install; edit the persisted `Server.xml` the same way. The plugin installer (the next
step, for standalone installs) doesn't touch this property either, so this step is manual
for everyone it applies to.

## Update the plugin (standalone installations only)

The bundled installer updates the jars, the XML configuration, and the Manager UI in one
pass, and is safe to re-run:


```shell
java -jar wse-plugin-video-intelligence-1.1.0.jar Install
```

If Java isn't installed natively, use the Engine's own copy:
`/usr/local/WowzaStreamingEngine/java/bin/java`. Add `--help` to the command to see the
available options.

If you install manually instead, follow the "Manually updating Wowza Streaming Engine"
section of the README. The jar list changed since 1.0.x, so replace all of the bundled
third-party jars, not just the plugin jar.

## Update the Manager UI (standalone installations only)

Warning
Don't skip this step. The 1.1.0 Manager pages and the 1.1.0 module only work as a pair. A
1.0.x page saving into a 1.1.0 Engine, or the other way around, fails in confusing ways,
so the UI must be updated in the same maintenance window as the jar.

The installer in the previous step already did this. If you install manually, note that
**the UI location changed** in 1.1.0:


```shell
mkdir -p /usr/local/WowzaStreamingEngine/manager/wse-plugins/server/vif
cp -r docker/manager/ui /usr/local/WowzaStreamingEngine/manager/wse-plugins/server/vif
```

Then clean up the 1.0.x install:

- Delete the old copy if present, so it can't be picked up again:
`/usr/local/WowzaStreamingEngine/manager/temp/webapps/enginemanager/wse-plugins/server/vif`
- If you previously deployed a rebuilt `WMSManager.war`, that flow is gone. 1.1.0 ships no
war and needs none. The stock Manager serves the files from the directory above.


After copying, restart Wowza Streaming Engine Manager and do a hard refresh in the browser
(Ctrl+F5, or Cmd+Shift+R on macOS) so no cached 1.0.x page lingers.

## Restart and verify

1. Restart Wowza Streaming Engine (or, on Docker, recreate the containers from the 1.1.0
images).
2. Standalone installations only: restart Wowza Streaming Engine Manager, so it picks up the
new UI.


1. Hard-refresh the browser, open a Video Intelligence page in the Manager, change any
setting, and save. The save should confirm immediately.


## If a save fails

| Symptom | Cause | Fix |
|  --- | --- | --- |
| "No revision for … Read it through the SDK first" | `Access-Control-Expose-Headers:ETag` missing from the policy | Complete [Allow the new REST headers in Server.xml](#allow-the-new-rest-headers-in-serverxml), then restart the Engine |
| Save fails with a network/CORS error while pages load fine | `If-Match` missing from `Access-Control-Allow-Headers` | Complete [Allow the new REST headers in Server.xml](#allow-the-new-rest-headers-in-serverxml), then restart the Engine |
| Pages look like 1.0.x, or behave inconsistently | Stale UI copy or a cached page | Redo [Update the Manager UI](#update-the-manager-ui-standalone-installations-only), restart the Manager, and hard-refresh |


## After the upgrade - write configuration through the v2 API only

1.1.0 introduces a new REST API (v2), and the Manager saves through it. **The v1 API is
deprecated as of 1.1.0, and Wowza strongly urges customers to use the v2 API for every new
and existing integration.** The old (v1) endpoints still answer for compatibility, but:

Warning
A v1 write rewrites the configuration in the old format and silently breaks settings saved
through 1.1.0: per-stream overrides lose their meaning and stop layering over their
defaults.

Reading through v1 remains safe. But once anything has been saved from the 1.1.0 Manager,
retire every script or integration that *writes* configuration through v1 and move it to
the v2 endpoints. Don't mix the two write paths on one installation.

## Rolling back to 1.0.x

Configuration written by 1.1.0 isn't fully usable by 1.0.x. To roll back, restore the 1.0.x
plugin (or images) **and** the configuration backup you took at the start of this guide:


```shell
rm -rf /usr/local/WowzaStreamingEngine/conf.modules/vif
cp -a /usr/local/WowzaStreamingEngine/conf.modules/vif.backup-1.0 \
      /usr/local/WowzaStreamingEngine/conf.modules/vif
```

On standalone installations, also restore the 1.0.x Manager UI. Then restart the Engine and
the Manager. The Server.xml change from the first step is harmless to leave in place.

## Related guides

- [About Wowza Video Intelligence Framework](/docs/wowza-video-intelligence-framework/about-wowza-video-intelligence-framework): overview of VIF's components and deployment options
- [Trial the Wowza VIF Postman Collection](/docs/wowza-video-intelligence-framework/rest-api-in-postman/trial-vif-postman-collection): exercise the v2 REST API this guide asks you to move to