Docker Express Install

Docker is a container platform. There is a desktop version of Docker available for Windows and macOS. This tutorial will assume the use of one of those versions and explain how to use Docker to do two things:

  • Get your own copy of our VOD demo environment up and running
  • Quickly set up your own Live teststream using Unified Origin

Prerequisites of VOD and Live demos

The VOD and Live tutorials have three requirements in common:

  • An evaluation license key, which can easily be obtained after registration
  • A working copy of Docker, installed on the system that will act as the host
  • Internet access on host through ports 53 and 80; needed to check license key

How to fulfill the first two requirements will be covered below and more specific info about the third requirement can be found here. The actual tutorials can be found further down below, at Your own Video on Demand demo and Your own Live streaming demo.

Installing Docker

First, download Docker's installer for your platform.

Assuming you are using a desktop machine, once installed and started you will see the Docker logo in your taskbar or system tray indicating Docker is running.

After having installed Docker, there are two routes to getting a container with Unified Origin to run. The quickest method uses a prebuilt image from Docker Hub. This tutorial will make use of this method.

A more elaborate but more flexible method makes use of images that you can build yourself, with Alpine Linux packages of Origin and Packager that we provide. How these images can be built is explained at the end of this tutorial.

Using Docker Hub images

Docker Hub is a centralized platform that hosts a wide range of image repositories that can be run with a simple Docker command. There are prebuilt images available on Docker Hub of both Packager and Origin.

For the purpose of this tutorial we will be using two different images of Unified Origin (one for VOD, the other for Live). Both of these images already contain the Apache webserver installation that is required to run Unified Origin. If you would like to, Creating your own Docker images is possbile as well.

Obtaining a license key

After registration on our website, you can get an evaluation key by clicking the following button:




The website will ask you to login before you can get a key. If you do not have a login, please go to registration first.

If you have made sure that you have a license key, you can move on to the next step.

Your own Video on Demand demo

Apart from a valid evaluation license key and a working copy of Docker, you will need to download specfic demo contents to get your own copy of our VOD evaluation environment up and running. This content is free to use and is provided for download by us.

Downloading VOD contents

For the demo content, create a directory called usp, download below file ('x.y.z' should be replaced with the current version, see the release notes which are kept here) and extract it to the usp directory you just created:

http://repository.unified-streaming.com/tears-of-steel-x.y.z.zip

Rename the extracted directory to tears-of-steel for ease of use.

You should now have a directory called usp that contains a sub-directory called tears-of-steel, which contains the demo files.

Running the demo using Docker

Now that all the prerequisites for the VOD evaluation environment are in place, you can run Docker command below to create an Origin demo container.

Please use a localhost port that is available on your host. In the following example the first port 80 is the port of the host's machine and the second port 80 is the Apache port in the container.

#!/bin/bash

docker run \
  -e USP_LICENSE_KEY=<your-license-key> \
  -v /<full-path>/usp/tears-of-steel:/var/www/unified-origin \
  -p 80:80 unifiedstreaming/origin

Note

Please use the full path (e.g. /Users/<login>/usp or /home/<user>/usp etc.) to the tears-of-steel directory you created.

Using the VOD demo

When the container launches and starts running, you will see the demo page with links to all the features on the port you have specified, e.g. localhost:80. It should look like our online Unified Streaming Demo, which looks like this:

../_images/demo.png

All the streams are played out by the Origin running in the Docker container.

Also note that if you have a question or need help, you can ask in our forum.

Your own Live streaming demo

Using a slighty different Docker setup, it's possible to set up a live streaming environment easily. Assuming you have an evaluation license key, this guide will let you do the following:

  • Start a Unified Origin container that hosts a publishing point
  • Build and start a container that runs FFmpeg
  • Make the FFmpeg container push a livestream to the Origin's publishing point

To be able to do this, a working installation of Docker Compose is a required. If you're running a recent version of Windows or macOS, Compose should be part of your standard Docker installation. If you're running Linux, this will not be the case.

To check whether Compose is installed, run the command below. If you have a working copy installed, the command will return some basic documentation. For more information on installing Docker Compose, consult the Docker Compose installation documentation.

docker-compose

In addition to having Docker Compose installed, you will need a properly configured Compose file. You can download it from our Github repository: Live Origin demo Compose file.

One other thing that you need to do before you can run your own Live streaming demo, is to store your license key in an environment variable. The Compose file specifies a variable for this and by storing your license key in that variable, you will ensure that Docker Compose will pass the key to the Unified Origin container (which will not run without it). To store your key in the correct variable, use the following command (replace <your_license_key> with your actual license key):

#!/bin/bash

export USP_LICENSE_KEY=<your_license_key>

Finally, with the environment variable and the Compose file in place, you can run the Live streaming demo using the following command in the directory of the Compose file:

docker-compose up -d

Warning

As this demo requires a patch to add functionality to FFmpeg for improved live streaming, the FFmpeg container will be built locally the first time (using FFmpeg Dockerfile). This process takes about ten minutes.

Of course, you can edit the Compose file to your liking. By adding or changing some of the publishing point options, for example. Consult VOD and Live as well as Live only for all of the possible options.

If you're done testing and want to stop (and remove) the Live Origin and FFmpeg containers, and also remove the related networks and images that were created using the docker-compose up command, you can run the following command (in the directory of the associated Compose file):

docker-compose down

But beware: because the above command will remove the locally built image of the FFmpeg container, you will need to rebuild it in case you want to run the demo again.

Testing the livestream

To test live playout, you can use any of the following URLs. In case you altered the Compose file and bound port 80 of the Unified Origin container to a different port on your host, please make sure to reflect that change in the URLs below:

Local playout URL Streaming protocol
localhost:80/test/test.isml/.mpd MPEG-DASH
localhost:80/test/test.isml/.m3u8 Apple's HLS
localhost:80/test/test.isml/Manifest Microsoft's Smooth Streaming
localhost:80/test/test.isml/.f4m Adobe's Dynamic Streaming

Important

The above is a rudimentary test setup. In real world scenarios you should always configure a hostname for the server that runs Unified Origin: Virtual hosts and DNS.

Using a different source

Only starting the Live Origin (and not the FFmpeg container) is possible as well, by specifying the service in the Docker Compose command:

docker-compose up live-origin

You can check the state of the publishing point using the following URL, as detailed further in Retrieving additional publishing point information. Assuming you have not started pushing any content to the publishing point, its state should be 'idle'. When you do push content to it, it should become 'started'.

localhost:80/test/test.isml/state

Creating your own Docker images

To create your own images for use with Docker, you need our Alpine Linux packages of Origin and Packager. Using a Dockerfile, you can instruct Docker to fetch these packages from our repository.

The package repository for Origin and Packager is at the following url:

http://apk.unified-streaming.com/repo

To install both packages, your Dockerfile should contain the following commands:

RUN apk --update add bash bash-completion apache2 --repository \
http://nl.alpinelinux.org/alpine/edge/testing

RUN wget -q -O /etc/apk/keys/alpine@unified-streaming.com.rsa.pub \
http://apk.unified-streaming.com/alpine@unified-streaming.com.rsa.pub

RUN apk --update add mp4split mod_smooth_streaming --repository \
http://apk.unified-streaming.com/repo

The first command fetches and installs the public key to validate the repository contents.

The second command installs the Packager and the Origin. Both are required for the Origin to function.

To build the image you can do the following:

#!/bin/bash

cd <path>/<directory-containing-your-dockerfile>

docker build -t <your-repository-name>/origin .

This will install the latest public release of the software, of which you can check the release notes kept here.

Note

For reference, have a look at the Dockerfile of our Unified Origin container, as well as its entrypoint.sh script and Apache configuration. Note that the Apache configuration contains 'LOG_FORMAT' and 'LOG_LEVEL' variables that are replaced by the entrypoint script, based on environment variables that are passed to the container when running it.