Deploying Stream Manager and Autoscaling on DigitalOcean


This document assumes that you have some basic knowledge of Digital Ocean platform management. It also assumes that you have some basic linux and network administration skills. If you need more detailed information, please contact us.

In order to use the Red5 Pro Stream Manager service you will need the following:

  1. The latest Red5 Pro Server build.
  2. The terraform-cloud-controller.jar, and from the Red5 Pro Autoscaling Library Extensions section.
  3. An active Red5 Pro license key, Startup Pro level or higher. REGISTER HERE.. Note: clustering and autoscaling are not supported by TRIAL or DEVELOPER license types.
  4. An active Digital Ocean account with administrative rights.
  5. Dedicated droplets on which you can deploy Red5 Pro.

Before you Begin

You will want to keep a record of the usernames, passwords, IP addresses, and other information generated during the setup process, as you will need the information for Stream Manager configuration and future operations via the API. Click here to download a handy list for tracking all of your Red5 Pro Simulated Cloud Autoscaling values

Generate DigitalOcean API Token

  1. From the left-hand navigation of the Digital Ocean dashboard, under the Manage section choose API
  2. Under Personal access tokens, click on Generate New Token
  3. In the New personal access token popup, enter a Token Name; Select scopes: Read and Write scopes (save API key), and click on Generate Token
  4. Copy the token (it will be 64-characters and alpha-numeric)

NOTE: if you have multiple autoscaling environments (for example, develop and production), then you need to create separate API keys for each environment, to ensure that they stay isolated.


Generate and Add an SSH key

The SSH key will be used for connecting to the droplets as root.

Generate Your SSH2-RSA Key Pair:

On Mac/Linux:

  • Open Terminal
  • Type: ssh-keygen -t rsa
  • Accept the default path and modify the file name if you wish (Enter file in which to save the key (~/.ssh/id_dsa)
  • Enter a passphrase and confirm (make sure this is SECURE, and noted somewhere for future reference)
  • Private and public keys will be generated

On Windows:

  • Download and run PuTTYgen
  • Click on “Generate” button and follow instructions displayed to help PuTTYgen generate your private public key-pair.
  • Once PuTTYgen finishes generating keys it will display the public key and other details in the application window.
  • Enter a passphrase and confirm. (make sure this is SECURE, and noted somewhere for future reference)
  • Click “Save public key” and save the key with a filename (ex: red5pro_node) on your file system in a secure location (or a common standard folder such as ~/.ssh/ under your user profile). Provide an extension of .pub to the file (public key).
  • Click “Save private key” and save the key with the same filename as the public key (ex: red5pro_node) on your file system in a secure location (or a common standard folder such as ~/.ssh/ under your user profile). Provide an extension of .ppk to the file (private key).

Add SSH Key:

  1. From the left-hand navigation of the Digital Ocean dashboard, under the Account section, choose Security
  2. Under SSH Keys, click on Add SSH Key
  3. Open your public key (from above) with a text editor and copy the contents
  4. Paste the public key into the SSH key content field
  5. Give the key a name
  6. Click on Add SSH Key


Create SM Instance and assign a Floating IP

We will be configuring the Stream Manager instance later, but to start, we need the floating IP address to assign to a domain name.

  1. From the left-hand navigation of the Digital Ocean dashboard, under the Manage section, choose Droplets
  2. Click on Create
  3. Choose Droplets from pull-down
  4. Choose an image: Ubuntu 16.04.6 (LTS) x64
  5. Choose a plan: CPU-Optimized; 4GB/2 CPUs (minimum suggested for running Red5 Pro) newdroplet01
  6. Choose a datacenter region
  7. Additional options are optional
  8. Authentication: choose SSH keys (select the key(s) you want to include newdroplet02
  9. Finalize and create: Choose a hostname; Select a Project; click on Create Droplet newdroplet03

Assign Floating IP

  1. From the left-hand navigation of the Digital Ocean dashboard, under the Manage section, choose Networking, Floating IPs
  2. Under Assign a floating IP, click on the link "To reserve a floating IP for a specific datacenter, click here."
  3. Choose the Datacenter location where you created your Stream Manager instance, then click on Assign. floating01
  4. Select the Floating IP from the list; click on More v and choose Reassign floating02
  5. Find your stream manager droplet and select it.

Note: the new static Floating IP will be assigned in addition to the ipv4 address that was assigned to the droplet on creation.

Now, you can create a DNS entry associating the Stream Manager floating IP with your intended Stream Manager domain name (for example,

Create Firewall rules for StreamManager and Nodes

  1. From the left-hand navigation of the Digital Ocean dashboard, under the Manage section, choose Networking, Firewalls
  2. Click on Create Firewall
  3. Give a name to the Firewall
  4. Add Inbound Rules for the Red5 Pro ports:
Port Description Protocol
5080 default web access of Red5 Pro/Websockets for WebRTC TCP
443 modified https access of Red5 Pro; secure websockets for WebRTC / Stream Manager TCP
1935 default Red5 Pro RTMP port TCP
8554 default RTSP port TCP
6262 websockets for HLS TCP
40000-65535 TURN/STUN/ICE port range for WebRTC UDP

Prepare Red5 Pro Node droplet

  1. From the left-hand navigation of the Digital Ocean dashboard, under the Manage section, choose Droplets
  2. Click on Create
  3. Choose Droplets from pull-down
  4. Choose an image: Ubuntu 16.04.6 (LTS) x64
  5. Choose a plan: CPU-Optimized; 4GB/2 CPUs (minimum suggested for running Red5 Pro)
  6. Choose a datacenter region
  7. Additional options are optional
  8. Authentication: choose SSH keys (select the key(s) you want to include
  9. Finalize and create: Choose a hostname; Select a Project; click on Create Droplet

Install Red5 Pro on the Instance:

  • Connect to your instance over ssh as the root account.
  • Follow the Installing Red5Pro on a Linux Server instructions.
  • Make sure that Red5 Pro service is set to auto-start on launch.
  • Red5 Pro Clustering does not work without a license. You will need to purchase a Red5 Pro Professional license from Red5 Pro. Add a file named LICENSE.KEY with your Pro license key (16 characters, plus dashes, like: YOUR-LIC-ENSE-KEY1) to the root of the Red5 Pro Server installation ({red5prohome}/LICENSE.KEY).

Configure Autoscaling on the Instance:

Navigate to the location where you extracted the Red5 Pro files, and edit the file {red5prohome}/conf/autoscale.xml

<bean name="config"class="com.red5pro.clustering.autoscale.Configuration">
   <property name="active" value="false"/>
   <property name="cloudWatchHost" value=""/>
  • Change the active value from “false” to “true
  • Replace with the static ip of the Stream Manager
  • Save and close the file

Set a Unique Cluster Password:

Edit the file {red5prohome}/conf/cluster.xml and replace the default <!-- edge/origin link cluster password --> password from changeme to sometime unique. Make a note of this password, to be used in the Stream Manager file.

NOTE: The cluster password can not contain any CAPITAL LETTERS at this time

Enable Red5 Pro Server API and Set Management Password:

Configure the Server API per this document. Modify the security.accessToken value in {red5pro/webapps/api/WEB-INF/, and make a note of it. You will need this value for your Stream Manager.


Add the Stream Manager's Floating IP address to the {red5pro}/webapps/api/WEB-INF/security/hosts.txt file (or add * to make the API accessible from anywhere).


Remove Unnecessary Webapps:

To ensure a faster startup time for your server, we suggest deleting any webapps that you will not be using from the {red5prohome}/webapps directory (for example: secondscreen, template, vod, streammanager). For ease of setup for the Stream Manager, leave a zipped copy of the server distribution on the server. If you are running a custom webapp, then you would want to include that on your node servers.

Verifying Red5 Pro on Instance:

Start Red5 Pro service

sudo systemctl start red5pro

Once you have started the Red5 Pro Server, you can verify that it is running and available by opening a web browser and navigating to http://<server-ip>:5080, where is the Public address value of your Red5 Pro server.

Create Node Image

  1. From the left-hand navigation of the Digital Ocean dashboard, under the Manage section, choose Images, Snapshots
  2. Under Take a Snapshot select the node droplet you just configured from the drop-down; either use the assigned image name, or rename it to something more descriptive
  3. Then click on Take Snapshot. It will take a few minutes to create the image. image01
  4. Make a note of the Node Image Name

Copy Image to Regions

If you wish to autoscale across multiple regions, then you will need to copy the image created to all of the regions that you will be using.

  1. Once the snapshot has been created it will be listed under Snapshots, Droplets. Choose the snapshot and click on More, then choose Add to region. region01
  2. Click on each region to which you would like to copy the image. region02
  3. Make a note of the Regions which contain the image.

Create PostgreSQL Database

  1. From the left-hand navigation of the Digital Ocean dashboard, under the Manage section, choose Databases
  2. Click on Create in top left, then in pull-down choose Databases
  3. Under Create a database cluster, choose PostgreSQL 11; choose a node plan - if you are going to have high-volume traffic, you will want more memory/CPU/disk space. For testing, you can choose the 1G/1CPU/10GB Disk plan.
  4. Choose the datacenter where your Stream Manager droplet resides. db01
  5. Under Finalize and create choose a unique database cluster name (or accept the assigned name) and select your project, then click on Create a Database Cluster. db02
  6. After the database is provisioned, you can secure and configure the database cluster. NOTE: this can take 10-15 minutes, so now is a good time to get up and stretch your legs.
  7. Add trusted sources - from the Overview tab, cilck on Secure this database cluster by restricting access. in the TRUSTED SOURCES section. Click on the Edit button next to Trusted Sources. Find your stream manager in the Add Trusted Sources pull-down; you can also add your IP address if you wish. Then click on Allow these inbound sources only.
  8. Make a note of the time for scheduled updates; if you want to change that time you can modify that in settings.
  9. Click on the Users & Databases tab. We will be adding a new user, and two new databases.
  10. Add an autoscaling admin User account to the database. A secure password will be generated - make a note of that password (or you can reset it if you like).
  11. Add two new databases: cluster and terraform. Note: these databases will be populated by the Stream Manager and Terraform at startup. db04

Configure Stream Manager Instance

Install Red5 Pro on the Instance:

  • SSH into the Stream Manager droplet that you created above.
  • Follow the Installing Red5 Pro on a Linux Server instructions
  • Make sure that Red5 Pro service is set to auto-start on launch
  • Navigate to the directory where you installed Red5 Pro (e.g. /usr/local/red5pro)
  • Delete the following files/directories:
    • {red5prohome}/conf/autoscale.xml
    • {red5prohome}/plugins/red5pro-autoscale-plugin-*
    • {red5prohome}/plugins/red5pro-webrtc-plugin-*
    • {red5prohome}/plugins/inspector.jar
    • {red5prohome}/webapps/inspector/
  • Install an SSL certificate on your Stream Manager instance so that it can be used as a proxy for publishers and subscribers. If you aren't using SSL proxy, it is still recommended that you install an SSL certificate for secure communication.

Upload and Configure Terraform on Stream Manager

Copy the file to the Stream Manager, and unzip in {red5pro}/webapps/streammanager/WEB-INF directory. This contains the following, which will be saved in the lib directory:

  • terraform 0.12.7 Binary file
  • and configuration files
  • modules directory which contain additional Terraform configuration files.

Terraform configuration

The Terraform configuration will be managed by the Stream Manager properties and API.

However, if you are using a load balancer, then you will need to uncomment and modify the first five lines in the Terraform file {red5pro}/webapps/streammanager/WEB-INF/lib/

# terraform {
#   backend "pg" {
#     conn_str = "postgresql://doadmin:<password>@<database_url>:25060/defaultdb?sslmode=require"
#   }
# }

Initialize Terraform

From the lib directory (cd {red5pro}/webapps/streammanager/WEB-INF/lib), initialize terraform with the following commands:

./terraform workspace new sm

./terraform init

Along with some other messages, you should see: Terraform has been successfully initialized!

Import and Activate the Terraform Cloud Controller

Copy the terraform-cloud-controller.jar into {red5prohome}/webapps/streammanager/WEB-INF/lib/

Edit the applicationContext.xml file, located at {red5prohome}/webapps/streammanager/WEB-INF/applicationContext.xml as per the following:

  • Locate the Terraform Cloud controller “bean” and uncomment it as shown below (note: do not modify the values, only uncomment the bean configuration to make it active):
<bean id="apiBridge"
        <property name="operationTimeoutMilliseconds"
             value="${terra.operationTimeoutMilliseconds}" />
        <property name="regionNames" value="${terra.regionNames}" />
        <property name="availabilityZoneNames"
             value="${terra.regionNames}" />
        <property name="instanceName"
        value="${terra.instanceName}" />

Comment out (or delete the entry for) the default controller as shown below to disable it:

<!-- Default CONTROLLER -->
<bean id="apiBridge" class="" init-method="initialize">

Modify Stream Manager App Properties

The Stream Manager’s configuration details are stored in the file, found in: {red5prohome}/webapps/streammanager/WEB-INF/ This is where Stream Manager reads all its settings from. Each configurable setting is organized into its own section. For more details on the file sections, read here.

You will need to modify the following values:


  • config.dbHost={host} -- the DB Endpoint URL of your PostgreSQL server instance
  • config.dbPort=3306 - change this to 25060, the default PostgreSQL port
  • config.dbUser={username} -- Database Master Username
  • config.dbPass={password} -- Database Master Password


  • instancecontroller.replaceDeadClusters=false -- by default, any cluster that becomes unresponsive will be shut down. Setting this value to true will automatically replace any clusters that have failed.
  • instancecontroller.deleteDeadGroupNodesOnCleanUp=true -- by default, any unresponsive nodes will be deleted from the dashboard. Setting this value to false will stop the instances, but not delete them.

Corrupted Nodes Check (added with server release 6.2.0)

By default, Stream Manager uses RTMP response from nodes to determine their health (this check originates on the node side). Optionally, you can also monitor HTTP response from the nodes, by modifying the following values in the NODE CONTROLLER section:

  • instancecontroller.checkCorruptedNodes=false -- change to true to monitor HTTP response from the autoscaling nodes.
  • instancecontroller.corruptedNodeCheckInterval=300000 -- frequency of stream manager checks to nodes in milleseconds (default is 5 minutes)
  • instancecontroller.corruptedNodesEndPoint=live -- webapp to monitor. This is set to live by default, but can be changed to any webapp.
  • instancecontroller.httptimeout=30000 -- allowed HTTP response time in milleseconds (30 seconds by default)


  • cluster.password=changeme -- modify this to be the same as the password that you set in the cluster.xml file on your disk image.


You will need to uncomment and modify these properties.

  • terra.regionNames -- This attribute takes a comma separated list of available region in Terraform. Currently available: ams2, ams3, blr1, fra1, lon1, nyc1, nyc2, nyc3, sfo1, sfo2, sgp1, tor1
  • terra.operationTimeoutMilliseconds: 20000 -- do not modify this
  • terra.instanceName: digitalocean_droplet


  • rest.administratorToken= -- You need to set a valid password string here before you start using Stream Manager. This is the password that you will use to execute API commands.


  • serverapi.port: The port on which the Red5 Pro http service is accessible. Unless this has been changed explicitly, it defaults to 5080.
  • serverapi.protocol: The protocol over which the http service is accessible. If your instances have ssl certificates on them, then the valus should be https, else it should be http. The default is http.
  • serverapi.version: The api version that is applicable to your Red5 Pro instances. You can get information on the latest serevr api version for the Red5 Pro server api documentation. The default value is v1.
  • serverapi.accessToken: The security access token required to make api calls to the node servers. Use the security access token value that you set on your nodes.


  • proxy.enabled set to true enables, or set to false disables the websocket proxy service. You must use the proxy if you are using WebRTC with Red5 Pro autoscaling.


  • webapp which the stream manager uses for checking node cluster status. The default value is live


  • debug.logaccess -- Set to true if you want to allow access to log files via REST API. This can be specially useful during development on cloud. With log access enabled you can use the Stream Manager REST api to download log files with using SSH. For more info on how to use the log access api refer to the Stream Manager Rest API.

Please note that if you modify any of the above values after your initial deployment, you will need to restart the Red5 Pro service.

Sample file content:









terra.regionNames=ams2, ams3, blr1, fra1, lon1, nyc1, nyc2, nyc3, sfo1, sfo2, sgp1, tor1





Start Red5 Pro Service to Use the Stream Manager

sudo systemctl start red5pro

API Basics, to get you started

(for full API, see Red5 Pro Stream Manager API)

Verify Stream Manager Controller (GET)

GET call:


should return: Terraform Cloud Service

Create a Scale Policy (post)

  • Make sure to include a role section for each node type you want to include (origin, edge, relay, transcoder):

POST call: https://<streammanager_URL>/streammanager/api/3.1/admin/configurations/scalepolicy?accessToken=<accessToken>

Data (make sure to select JSON as the body type):

  "policy": {
          "name": "<policy-name>",
          "description": "<policy-description>>",
          "type": "<policy-type>",
          "version": "<policy-version>",
          "targets": {
              "region": [
                      "name": "default",
                      "target": [
          "role": "<role>",
          "minLimit": "<min-node-count>",
          "maxLimit": "<max-node-count>",
          "scaleAdjustment": "<node-scale-adjustment>"

Create a Launch Policy (post)

For ease of administration, we recommend naming the policy something easily identifiable and descriptive, such as <imagename>-<nodetypes> (e.g., red5pro620-origin-edge).

POST call: https://<streammanager_URL>/streammanager/api/3.1/admin/configurations/launchconfig?accessToken=<accessToken>

Data (make sure to select JSON as the body type):

    "launchconfig": {
      "name": "<configuration-name>",
      "description": "<configuration-descrption>",
      "image": "<red5pro-image>",
      "version": "0.0.3",

    "targets": {
        "target": [
        "role": "<role>",
        "instanceType": "<instance-type>",
        "connectionCapacity": "<instance-capacity>"

      "properties": {
        "property": [
            "name": "<property-name>",
            "value": "<property-value>"
      "metadata": {
        "meta": [
            "key": "<meta-name>",
            "value": "<meta-value>"

Create a New Node Group (POST)

Using a tool like Postman, create a new node group via the API.

POST call: https://<streammanager_URL>/streammanager/api/3.1/admin/nodegroup?accessToken=<rest.administratorToken>

Data (make sure to select JSON as the body type):

 "regions": [
   "<do-region, eg: nyc3>"
 "launchConfig": "<launchconfig-created-above>",
 "scalePolicy": "<scaleconfig-created-above>"

Note the cluster “name” that is returned by the above call. It will be used to create a new Origin server.

Launch New Origin (POST)

After you create a node group, create the origin server. Creating an origin server will also generate at least one edge, per scaling policy min limit.

https://<streammanager_URL>/streammanager/api/3.1/admin/nodegroup/<cluster-name>/node/origin?accessToken=<rest.administratorToken from file>

Set Alarm Threshold (POST)

By default, the alarm threshold (the capacity percentage at which the cluster will scale up any given node type) is set to 60%. To modify this, POST the following:









List Groups (GET)


Stream Manager Publish and Subscribe Examples

Stream Manager Proxy Publish and Subscribe Examples

With the latest release, the live webapp includes two examples: proxy-publisher.html and proxy-subscriber.html. These examples will take the following query parameters:

Name Description Default Value
host hostname or IP window.location.hostname
protocol protocol which Stream Manager is served over (http or https) window.location.protocol
port port number that Stream Maager is served on window.location.port
app webapp name to stream to on the server live
streamName The unique stream name to broadcast with or subscribe to None. Required
verbose Flag to enable verbose logging in Dev Console None. optional
view Target broadcast tech (rtc, rtmp or hls) None. Optional

Example URI:

Red5 Pro HTML5 SDK Examples:

Stream Manager examples

Note: the streaming-html5 examples testbed is included with the Red5 Pro server distribution, and can be accessed via your stream manager at https://your.server.url/webrtcexamples/.

Red5 Pro iOS SDK Examples:

Publish - Stream Manager

Subscribe - Stream Manager

Red5 Pro Android SDK Examples:

Publish - Stream Manager

Subscribe - Stream Manager


  1. If you have created a new nodegroup, but adding an Origin server doesn't automatically initiate an accompanying Edge server, check the following on your server instance:

  2. Verify that red5pro/conf/autoscale.xml in your Red5Pro server image points to the IP address of your stream manager (replace in <property name="cloudWatchHost" value=""/>); make sure that you the change active value from default “false” to “true” (<property name="active" value="true"/>)

  3. Check {red5pro}/conf/cluster.xml - make sure that the password set for <!-- edge/origin link cluster password --> matches the cluster.password= in the stream manager file.
  4. Make sure that your have your LICENSE.KEY file in the {red5pro} root directory; clustering (and in turn, autoscaling) will not work without a valid license key.
  5. If all of these check out, then start up red5pro service on your ami instance, and tail the Stream Manager {red5pro}/log/red5.log file - you should see messages about an instance pinging the Stream Manager. If you don't, then check for inbound port access to your stream manager (or outbound port access from your node security group).
  6. If you have any issues with, or are updating anything in your environment, you should restart your instances in the following order:
  7. 1 - Restart the ORIGIN server(s) first
  8. 2 - Then, restart the EDGE server(s)
  9. 3 - Finally, restart the STREAM MANAGER last.