How to Automate Streaming Engine Module Builds with Wowza Gradle Plugin

Building Wowza Streaming Engine modules manually takes too much time.

You compile Java classes, package them into JARs, copy files to the right directories, update configuration files, and restart services. Each step introduces potential errors. Miss one dependency and your module fails at runtime. Copy to the wrong directory and nothing works.

The Wowza Gradle Plugin eliminates this tedious process. This tutorial shows you exactly how to configure automated builds that compile, test, package, deploy, and restart your Wowza server with a single command.

You’ll get working configuration examples, practical deployment workflows, and solutions to common problems developers actually face.

The Wowza Gradle Plugin automates compiling, packaging, and deploying custom Wowza Streaming Engine modules. It replaces manual Ant builds with Gradle tasks that handle dependencies, create JAR files, deploy to your server, and restart services — all from one command. Setup requires adding the plugin to build.gradle, configuring your Wowza path, and defining custom tasks for your workflow.

Why Manual Wowza Module Builds Create Problems

Manual module development creates three major bottlenecks for developers.

First, repetitive tasks consume valuable coding time. You rebuild modules dozens of times during active development. Each rebuild means stopping work, running commands, copying files, and restarting services. These interruptions add up to hours of wasted time each week.

Second, manual processes introduce errors. Forget to copy a dependency JAR and your module crashes. Deploy to the wrong application folder and nothing happens. Update code but forget to restart the service and you test old code. These mistakes are frustrating and hard to track down.

Third, team collaboration suffers. Without automation, each developer sets up their environment differently. One person uses Eclipse with Ant scripts. Another uses IntelliJ with manual deployments. A third developer has their own custom workflow. This inconsistency makes onboarding new team members difficult and sharing projects nearly impossible.

What the Wowza Gradle Plugin Actually Does

The Wowza Gradle Plugin connects your development workflow directly to your Wowza server.

When you run a build command, the plugin compiles your Java source files using the Wowza SDK dependencies. It packages compiled classes and resources into a properly structured JAR file. The plugin then copies this JAR to your Wowza installation’s lib directory.

For deployment, the plugin can create or update application configurations in your Wowza conf directory. It copies Application.xml files to the correct locations and sets up module references automatically.

The plugin also manages your Wowza service. After deploying new code, it can stop your Wowza service, wait for a clean shutdown, and restart it with your updated modules loaded.

All of these steps happen from one Gradle command. You don’t touch configuration files manually. You don’t copy files between directories. The plugin handles everything based on your build.gradle settings.

Setting Up Your Development Environment

You need three components before configuring the Wowza Gradle Plugin.

Install Gradle first. Download version 6.x or newer from gradle.org. After installation, verify it works by running gradle --version in your terminal. You should see the version number and Java runtime information.

Next, set up your Wowza Streaming Engine installation. The plugin deploys to a local Wowza instance during development. Note the installation path — you’ll need it for configuration. Common paths are /usr/local/WowzaStreamingEngine on Linux/Mac or C:\Program Files (x86)\Wowza Media Systems\Wowza Streaming Engine on Windows.

Finally, create your module project structure. Your project needs a standard Gradle layout with src/main/java for source code and src/main/resources for configuration files. Create a build.gradle file in your project root — this is where all automation configuration lives.

Configuring Your build.gradle File

Your build.gradle file defines how the plugin builds and deploys your modules.

Start with the basic Gradle configuration:

plugins {
    id 'java'
    id 'ro.stancalau.wowza' version '2.2'
}

group = 'com.yourcompany.wowza'
version = '1.0.0'

sourceCompatibility = 1.8
targetCompatibility = 1.8

repositories {
    mavenCentral()
}

The Java plugin provides compilation tasks. The Wowza plugin adds deployment capabilities. Java 8 compatibility matches what Wowza Streaming Engine uses — stay with this version to avoid runtime issues.

Next, configure your Wowza server connection:

wowza {
    wowzaHome = 'C:/Program Files (x86)/Wowza Media Systems/Wowza Streaming Engine'
    applicationName = 'live'
    serviceName = 'WowzaStreamingEngine'
}

Replace wowzaHome with your actual installation path. Use forward slashes even on Windows — Gradle handles path conversion. The applicationName specifies which Wowza application receives your module. The serviceName must match your system service name exactly.

Add your dependencies:

dependencies {
    implementation fileTree(dir: "${wowza.wowzaHome}/lib", include: '*.jar')
    implementation 'com.google.code.gson:gson:2.8.9'
    
    testImplementation 'junit:junit:4.13.2'
}

The first dependency imports all Wowza SDK JARs from your installation. This gives you access to Wowza classes like ModuleBase and IApplicationInstance. Add any third-party libraries your module needs — Gson in this example for JSON handling.

Creating Your First Automated Build Task

Define a custom deployment task that automates your entire workflow.

Add this task to your build.gradle:

task deployWowza(type: Copy, dependsOn: 'jar') {
    from jar.archiveFile
    into "${wowza.wowzaHome}/lib"
    
    doLast {
        println "Module deployed to ${wowza.wowzaHome}/lib"
        
        // Copy application configuration
        copy {
            from 'Application.xml'
            into "${wowza.wowzaHome}/conf/${wowza.applicationName}"
        }
        
        println "Configuration updated for ${wowza.applicationName}"
    }
}

This task depends on the jar task — Gradle builds your JAR before deploying it. The Copy task moves your JAR to Wowza’s lib directory. The doLast block copies your Application.xml configuration file.

Run this task with gradle deployWowza. Gradle compiles your code, packages it, deploys it, and updates configuration files automatically.

Adding Service Restart Automation

Deploying code isn’t enough — you need to restart Wowza to load your changes.

Add service control tasks to build.gradle:

task stopWowza(type: Exec) {
    if (System.getProperty('os.name').toLowerCase().contains('windows')) {
        commandLine 'cmd', '/c', 'net', 'stop', "${wowza.serviceName}"
    } else {
        commandLine 'sudo', 'systemctl', 'stop', "${wowza.serviceName}"
    }
    
    ignoreExitValue = true
}

task startWowza(type: Exec) {
    if (System.getProperty('os.name').toLowerCase().contains('windows')) {
        commandLine 'cmd', '/c', 'net', 'start', "${wowza.serviceName}"
    } else {
        commandLine 'sudo', 'systemctl', 'start', "${wowza.serviceName}"
    }
}

task restartWowza {
    dependsOn stopWowza
    finalizedBy startWowza
    
    doLast {
        println "Waiting for service to stop..."
        Thread.sleep(3000)
    }
}

These tasks handle cross-platform service control. On Windows, they use net stop and net start. On Linux/Mac, they use systemctl commands. The restart task stops the service, waits 3 seconds for a clean shutdown, then starts it again.

Combine deployment and restart into one command:

task deployAndRestart {
    dependsOn deployWowza
    finalizedBy restartWowza
    
    doLast {
        println "Deployment complete. Service restarting..."
    }
}

Now run gradle deployAndRestart to build, deploy, and restart everything with one command.

Managing Dependencies Properly

Dependency management prevents version conflicts and runtime errors.

Wowza includes many third-party libraries in its installation. When your module uses the same libraries, version mismatches cause problems. Your code might compile fine, but fail at runtime because Wowza loads a different version.

Handle this with dependency scoping:

configurations {
    provided
    implementation.extendsFrom provided
}

dependencies {
    provided fileTree(dir: "${wowza.wowzaHome}/lib", include: '*.jar')
    
    implementation 'org.apache.commons:commons-text:1.9'
}

jar {
    from {
        configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }
    }
    
    exclude 'META-INF/*.SF'
    exclude 'META-INF/*.DSA'
    exclude 'META-INF/*.RSA'
}

The provided configuration includes Wowza libraries at compile time but excludes them from your JAR. Only your own dependencies get packaged. This creates a “fat JAR” with everything your module needs while avoiding conflicts with Wowza’s libraries.

For larger projects, consider dependency relocation using the Shadow plugin. This repackages third-party libraries under different Java package names, preventing conflicts completely.

Testing Your Modules Before Deployment

Automated testing catches bugs before they reach your server.

Add a test directory structure: src/test/java for test code and src/test/resources for test data.

Create a basic test:

package com.yourcompany.wowza;

import org.junit.Test;
import static org.junit.Assert.*;

public class ModuleTest {
    
    @Test
    public void testModuleInitialization() {
        YourWowzaModule module = new YourWowzaModule();
        assertNotNull("Module should initialize", module);
    }
    
    @Test
    public void testStreamProcessing() {
        // Test your module's core functionality
        String streamName = "test_stream";
        boolean result = processStream(streamName);
        assertTrue("Stream processing should succeed", result);
    }
}

Run tests before deployment by modifying your deployAndRestart task:

task deployAndRestart {
    dependsOn test
    dependsOn deployWowza
    finalizedBy restartWowza
}

Now gradle deployAndRestart runs your test suite first. If any test fails, deployment stops. This prevents broken code from reaching your server.

Integrating with Continuous Integration Systems

CI/CD integration lets you test and deploy automatically when code changes.

For Jenkins, create a Jenkinsfile in your project root:

pipeline {
    agent any
    
    stages {
        stage('Build') {
            steps {
                sh './gradlew clean build'
            }
        }
        
        stage('Test') {
            steps {
                sh './gradlew test'
            }
        }
        
        stage('Deploy to Dev') {
            when {
                branch 'develop'
            }
            steps {
                sh './gradlew deployWowza'
            }
        }
    }
}

For GitHub Actions, create .github/workflows/wowza-build.yml:

name: Wowza Module Build

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v2
    
    - name: Set up JDK 8
      uses: actions/setup-java@v2
      with:
        java-version: '8'
        distribution: 'adopt'
    
    - name: Build with Gradle
      run: ./gradlew build
    
    - name: Run tests
      run: ./gradlew test
    
    - name: Archive artifacts
      uses: actions/upload-artifact@v2
      with:
        name: wowza-module
        path: build/libs/*.jar

These configurations build and test your module automatically on every commit. Production deployments should require manual approval to prevent accidental updates.

Common Problems and Solutions

Problem: Gradle can’t find Wowza dependencies.

Solution: Verify your The wowzaHome path is correct and points to your actual installation. Check that wse-plugin.jar and other Wowza JARs exist in the lib directory. On some systems, you might need to escape spaces in paths or use quotes.

Problem: Module deploys but doesn’t load in Wowza.

Solution: Check that your Application.xml has the correct module class path. The fully qualified class name must match your package and class name exactly. Verify the JAR file actually contains your compiled classes by opening it with an archive tool.

Problem: Service restart fails with permission errors.

Solution: On Linux/Mac, service control requires sudo permissions. Run Gradle with elevated privileges or configure your user to control the Wowza service without a password. On Windows, ensure your command prompt runs as Administrator.

Problem: Module works locally but fails after CI/CD deployment.

Solution: Environmental differences cause this issue. Your CI server might use different Java versions, missing dependencies, or incorrect paths. Create a gradle.properties file with environment-specific settings and include it in your CI configuration.

Problem: Build takes too long on repeated runs.

Solution: Enable Gradle’s build cache  org.gradle.caching=true in gradle.properties. Use the Gradle daemon with org.gradle.daemon=true. These settings significantly speed up incremental builds by reusing outputs from previous runs.

Time and Cost Considerations

• Development Time: Initial setup takes 2-4 hours for a basic configuration. This includes installing Gradle, creating build scripts, and testing your first deployment. Complex projects with custom tasks and CI/CD integration might need 1-2 days.
• Ongoing Time Savings: After setup, you save 5-10 minutes per deployment cycle. During active development with 20+ deployments daily, automation saves 2-3 hours per developer per day. Teams of 3-5 developers save 10-15 hours daily.
• Cost Impact: The plugin itself is free and open-source. Your main investment is developer time for initial setup. However, reduced errors and faster iterations typically recover this cost within the first week of use.
• Infrastructure Requirements: You need a development Wowza server instance for testing. Production deployments might require staging servers. Budget $500-2000 monthly for cloud-hosted Wowza instances if you don’t run on-premises servers.

Tools and Resources List

Required Tools:

• Gradle 6.x or newer (free, gradle.org)
• Java Development Kit 8 (free, adoptopenjdk.net)
• Wowza Streaming Engine 4.8+ (paid license required)
• Git version control (free, git-scm.com)

Recommended Development Tools:

• IntelliJ IDEA Community Edition (free)
• Visual Studio Code with Gradle extension (free)
• Wowza Streaming Engine Manager for configuration (included with Wowza)

CI/CD Platforms:

• GitHub Actions (free for public repositories)
• Jenkins (free, self-hosted)
• GitLab CI (free tier available)

Documentation Resources:

• Wowza Developer Documentation (wowza.com/docs)
• Gradle User Manual (docs.gradle.org)
• Wowza Gradle Plugin GitHub (github.com/Stancalau-ro/wowza-gradle-plugin)

FAQ

Can I use the Wowza Gradle Plugin with Maven projects?

Not directly — the plugin is Gradle-specific. However, you can migrate Maven projects to Gradle or create a hybrid approach. Convert your pom.xml dependencies to build.gradle format. The Gradle init plugin can help with automatic conversion. Most developers find Gradle’s syntax simpler than Maven XML for build automation.

Does the plugin support Wowza Cloud deployments?

No — the plugin targets local or self-hosted Wowza Streaming Engine installations. Wowza Cloud uses a different deployment model with REST APIs. For cloud deployments, you’ll need to package your module as a JAR and upload it through the Wowza Cloud interface or use their deployment APIs directly.

Can I automate backups before deployment?

Yes — add a backup task to your build script. Create a task that copies your current Wowza lib directory and configurations to a backup location with timestamps. Make deployWowza depend on this backup task. If something breaks, you can restore from your backup quickly.

Note: This guide follows current best practices for Wowza Streaming Engine development and Gradle automation. Always test automation workflows in a development environment before applying them to production servers.