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.
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 below.
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 below.
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:
cp -a /usr/local/WowzaStreamingEngine/conf.modules/vif \
/usr/local/WowzaStreamingEngine/conf.modules/vif.backup-1.0Keep this backup until you're confident you won't need to roll back.
- Docker Compose installations - pull new images and recreate containers; only one manual step, and only if it applies to you.
- Standalone plugin installations - four manual steps, updating Server.xml, the plugin, and the Manager UI, then restarting and verifying.
- If your Engine
conf/directory is persisted from a 1.0.x install, complete Allow the new REST headers in Server.xml against that persisted file. If yourconf/directory is not persisted, skip to step 2. The 1.1.0 image already ships this change. - Pull the 1.1.0 images and recreate the containers.
- Complete Restart and verify.
- Allow the new REST headers in Server.xml.
- Update the plugin.
- Update the Manager UI. Don't skip this step.
- Restart and verify.
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.
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:
<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.
The bundled installer updates the jars, the XML configuration, and the Manager UI in one pass, and is safe to re-run:
java -jar wse-plugin-video-intelligence-1.1.0.jar InstallIf 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.
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:
mkdir -p /usr/local/WowzaStreamingEngine/manager/wse-plugins/server/vif
cp -r docker/manager/ui /usr/local/WowzaStreamingEngine/manager/wse-plugins/server/vifThen 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 Wowza Streaming Engine (or, on Docker, recreate the containers from the 1.1.0 images).
- Standalone installations only: restart Wowza Streaming Engine Manager, so it picks up the new UI.
- Hard-refresh the browser, open a Video Intelligence page in the Manager, change any setting, and save. The save should confirm immediately.
| 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, 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, 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, restart the Manager, and hard-refresh |
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:
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.
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:
rm -rf /usr/local/WowzaStreamingEngine/conf.modules/vif
cp -a /usr/local/WowzaStreamingEngine/conf.modules/vif.backup-1.0 \
/usr/local/WowzaStreamingEngine/conf.modules/vifOn 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.
- About Wowza Video Intelligence Framework: overview of VIF's components and deployment options
- Trial the Wowza VIF Postman Collection: exercise the v2 REST API this guide asks you to move to