Test/Demo Environment

Below are the necessary steps to install the Unified Streaming Platform (USP) on Ubuntu LTS. Running USP in the cloud or using containers is also possible.

Different deployment options and workflow approaches will be discussed in the individual chapters.

Learning Outcomes

  • Understand how to install Apache and USP using a package manager
  • Understand what the virtual host file contains and why
  • Understand how to use or check the license key
  • Understand how to verify correct installation of USP

Certification Handbook

This handbook can be found as HTML at the following URL (the ‘IP’ in ‘ec2-IP.eu-west-1.compute.amazonaws.com’ is the IP address assigned by AWS):

http://ec2-IP.eu-west-1.compute.amazonaws.com/docs/certification/index.html

The online version allows for easy copy/paste of command-lines.

Setup

Virtual Machine

Login to your VM using ssh (the ‘IP’ in ‘ec2-IP.eu-west-1.compute.amazonaws.com’ is the IP address assigned to your instance by AWS, and the password for the user ‘ubuntu’ is ‘ubuntu’):

#!/bin/bash

ssh -i YOURKEY -p 22 ubuntu@ec2-IP.eu-west-1.compute.amazonaws.com

Please note the #!/bin/bash is added to all command-lines for informational purposes. It indicates which shell should be used. If you are writing a bash script it is good custom to start with this ‘shebang’. When running commands from the exercises directly on the command-line you should not copy it. This applies to all examples.

Attention

Always use the ‘ubuntu’ user, unless explicitly indicated in an example.

You only need to explicitly use the hostname of your instance once, when logging in. For the hands-on exercises in this course, a variable aws_hostname has been set up for you (in your .bashrc). This variable stores the public hostname of your instance, based on a request to a specific AWS API endpoint:

aws_hostname=$(curl http://169.254.169.254/latest/meta-data/public-hostname)

Warning

The instance that you are now logged in to has been fully installed and configured. The following sections are there to provide you background information only. You should not do anything, except verifying your setup (all the way at the end of this chapter)! Only read the rest of the sections.

License Key

In order to get a license key, you usually register at https://www.unified-streaming.com/licenses/access. In the environment you’re working in now, a special license key for the certification course has already been installed for you.

Note

Every time Apache is started, the general error log will note if it was able to load the license key successfully. By working with a license key-file instead of a plain license key, Apache will log the path to the file instead of the actual key.

Aliases

Each time you run our command-line tools you need to provide your license key. For ease of use the following aliases have been setup in $HOME/.bashrc: [1]

#!/bin/bash

alias mp4split='mp4split --license-key /etc/usp-license.key $@'
alias unified_capture='unified_capture --license-key /etc/usp-license.key $@'
alias unified_remix='unified_remix --license-key /etc/usp-license.key $@'

Attention

Be aware that aliases do not work in scripts.

Errors

The installation section of the documentation contains a list with possible errors related to licensing. [2]

Virtual Host

Virtual hosts define how Apache serves a website. As we use name based virtual hosts, it is important to setup the DNS correctly and to use a ‘fully qualified domain name’ (fqdn) as the url. Without the ‘fqdn’ Apache will not make the correct mapping from url to virtual host. [4] [5]

The install script installs a virtual host file in /etc/apache2/sites-enabled. This file configures Apache like so:

  • Loads the mod_smooth_streaming module
  • Configures it to handle files ending in ‘.ism’ and ‘.isml’ (files with these extensions are ‘server manifests’).
  • Enables the module for the DocumentRoot (‘/’)
  • Applies important settings (CORS, Live options), discussed below

Note

The UspHandleIsm configuration token must be specified using the <Location> directive, not the <Directory> directive.

Cross Domain Access

The Cross-Origin Resource Sharing (CORS) headers are also configured as part of the virtual host configuration. These headers are necessary for HTML5 based playout scenarios in which the (JavaScript) player and the content are hosted on different domains, without these headers playout will not work.

Note

Although not the focus of this course, it’s good to know that similar information needs to be communicated for playout scenarios using Flash (Adobe HTTP Dynamic Streaming) or Silverlight (Microsoft HTTP Smooth Streaming). Both scenarios use separate files for this, as explained in our documentation regarding cross domain access. [6]

Live Settings

You must take special care with ‘limits for requests’ and ‘timeout’ settings when using Unified Origin for streaming Live. Since a long-running HTTP POST is used to transfer the audio/video from the encoder to the webserver, we need to be sure Apache won’t close the connection when a certain limit or timeout has been reached.

Apache’s default ‘limit for requests’ and ‘timeout’ settings are fine. But to make sure global changes to these settings don’t affect Unified Origin, we specifically disable them for Origin’s virtual host.

  • The LimitRequestBody is set to 0 (the global default, i.e. no limit)
  • The global configuration of the mod_reqtimeout module is disabled, in case it is used

This is done through the following configuration:

LimitRequestBody 0
<IfModule reqtimeout_module>
   RequestReadTimeout header=0 body=0
</IfModule>

Upgrade

Whenever you decide to upgrade our software you just need to use install command without stating any version number. We recommend using a staging environment to fully control the upgrade. [3]

Verify setup

Validate License on command-line

To check if your license key is valid or not you can instruct mp4split to print a human-readbable version of the key:

#!/bin/bash

mp4split --show-license

Note

Because of the configured alias the above command-line actually runs mp4split --license-key /etc/usp-license.key --show-license.

Verify License for Origin is Loaded

Apache is already running on your instances. Each time it restarts, it checks the license when loading the Origin module. Check Apache’s general error log to determine whether it has found your license key the last time it was started.

Check Playback Through Origin

Open the following URL in your browser (once again, the ‘IP’ in ‘ec2-IP.eu-west-1.compute.amazonaws.com’ is the IP address assigned by AWS). A page with a video player will open and a stream will be loaded automatically. Please check if playback works as expected:

http://ec2-IP.eu-west-1.compute.amazonaws.com

Everything is now set up and ready for the certification course.

Footnotes

[1]http://docs.unified-streaming.com/installation/license.html#license-key-wrapper
[2]http://docs.unified-streaming.com/installation/license.html#error-messages
[3]http://docs.unified-streaming.com/installation/upgrade.html
[4]https://httpd.apache.org/docs/2.4/vhosts/
[5]https://httpd.apache.org/docs/2.4/vhosts/name-based.html
[6]http://docs.unified-streaming.com/installation/origin/apache.html#cross-domain-access