Table of Contents
Kurento Media Server (KMS) is compiled and provided for installation by the Kurento team members, in a variety of forms. The only officially supported processor architecture is 64-bit x86, so for other platforms (such as ARM) you will have to build from sources.
Using an EC2 instance in the Amazon Web Services (AWS) cloud service is suggested to users who don’t want to worry about properly configuring a server and all software packages, because the provided template does all this automatically.
The Kurento Docker image allows to run KMS on top of any host machine, for example Fedora or CentOS. In theory it could even be possible to run under Windows, but so far that possibility hasn’t been explored by the Kurento team, so you would be at your own risk.
Setting up a local installation with
apt-get installallows to have total control of the installation process. It also means that it’s easier to make mistakes, so we don’t recommend this installation method. Do this only if you are a seasoned System Administrator.
If you want to try nightly builds of KMS, then head to the section Installing Nightly Builds.
The AWS CloudFormation template file for Amazon Web Services (AWS) can be used to create an EC2 instance that comes with everything needed and totally pre-configured to run KMS, including a Coturn server.
Follow these steps to use it:
Access the AWS CloudFormation Console.
Click on Create Stack.
Look for the section Choose a template, and choose the option Specify an Amazon S3 template URL. Then, in the text field that gets enabled, paste this URL:
Follow through the steps of the configuration wizard:
4.1. Stack name: A descriptive name for your Stack.
4.2. InstanceType: Choose an appropriate size for your instance. Check the different ones.
4.3. KeyName: You need to create an RSA key beforehand in order to access the instance. Check AWS documentation on how to create one.
4.4. SSHLocation: For security reasons you may need to restrict SSH traffic to allow connections only from specific locations. For example, from your home or office.
4.5. TurnUser: User name for the TURN relay.
4.6. TurnPassword: Password required to use the TURN relay.
Finish the Stack creation process. Wait until the status of the newly created Stack reads CREATE_COMPLETE.
Select the Stack and then open the Outputs tab, where you’ll find the instance’s public IP address, and the Kurento Media Server endpoint URL that must be used by Application Servers.
The Kurento CF template is written to deploy on the default VPC (see the Amazon Virtual Private Cloud docs). There is no VPC selector defined in this template, so you won’t see a choice for it during the AWS CF wizard. If you need more flexibility than what this template offers, you have two options:
Download the current CF from the link above, and edit it to create your own custom version with everything you need from it.
If you need to insert or extract files from a Docker container, there is a variety of methods: You could use a bind mount; a volume; cp some files from an already existing container; change your ENTRYPOINT to generate or copy the files at startup; or base FROM this Docker image and build a new one with your own customizations. Check About using Kurento with Docker for an example of how to use bind-mounts to provide your own configuration files.
These are the exact contents of the image:
apt-getinstallation of KMS, as described in Local Installation, plus all its extra plugins (chroma, platedetector, etc).
All default settings from the local installation, as found in
/etc/kurento/. For details, see Configuration.
Docker allows to fine-tune how a container runs, so you’ll want to read the Docker run reference and find out the command options that are needed for your project.
This is a good starting point, which runs the latest Kurento Media Server image with default options:
docker pull kurento/kurento-media-server:latest docker run -d --name kms --network host \ kurento/kurento-media-server:latest
By default, KMS listens on the port 8888. Clients wanting to control the media server using the Kurento Protocol should open a WebSocket connection to that port, either directly or by means of one of the provided Kurento Client SDKs.
The health checker script inside this Docker image does something very similar in order to check if the container is healthy.
Once the container is running, you can get its log output with the docker logs command:
docker logs --follow kms >"kms-$(date '+%Y%m%dT%H%M%S').log" 2>&1
For more details about KMS logs, check Debug Logging.
Notice how our suggested
docker run command uses
--network host? Using Host Networking is recommended for software like proxies and media servers, because otherwise publishing large ranges of container ports would consume a lot of memory. You can read more about this issue in our Troubleshooting Guide.
The Host Networking driver only works on Linux hosts, so if you are using Docker for Mac or Windows then you’ll need to understand that the Docker network gateway acts as a NAT between your host and your container. To use KMS without STUN (e.g. if you are just testing some of the Tutorials) you’ll need to publish all required ports where KMS will listen for incoming data.
For example, if you use Docker for Mac and want to have KMS listening on the UDP port range [5000, 5050] (thus allowing incoming data on those ports), plus the TCP port 8888 for the Kurento Client, run:
docker run --rm \ -p 8888:8888/tcp \ -p 5000-5050:5000-5050/udp \ -e KMS_MIN_PORT=5000 \ -e KMS_MAX_PORT=5050 \ kurento/kurento-media-server:latest
One of the nicest things about the Docker deployment method is that changing versions, or upgrading, is almost trivially easy. Just pull the new image version and use it to run your new container:
# Download the new image version: docker pull kurento/kurento-media-server:6.15.0 # Create a new container based on the new version of KMS: docker run [...] kurento/kurento-media-server:6.15.0
With this method, you will install Kurento Media Server from the native Ubuntu packages build by us. Kurento officially supports two Long-Term Support (LTS) versions of Ubuntu: Ubuntu 16.04 (Xenial) and Ubuntu 18.04 (Bionic) (64-bits x86 only).
Open a terminal and run these commands:
Make sure that GnuPG is installed.
sudo apt-get update && sudo apt-get install --no-install-recommends --yes \ gnupg
Add the Kurento repository to your system configuration.
Run these commands:
# Import the Kurento repository signing key sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 5AFA7A83 # Get Ubuntu version definitions source /etc/upstream-release/lsb-release 2>/dev/null || source /etc/lsb-release # Add the repository to Apt sudo tee "/etc/apt/sources.list.d/kurento.list" >/dev/null <<EOF # Kurento Media Server - Release packages deb [arch=amd64] http://ubuntu.openvidu.io/6.15.0 $DISTRIB_CODENAME kms6 EOF
This step applies only for a first time installation. If you already have installed Kurento and want to upgrade it, follow instead the steps described here: Local Upgrade.
sudo apt-get update && sudo apt-get install --no-install-recommends --yes \ kurento-media-server
This will install the release version of Kurento Media Server.
The server includes service files which integrate with the Ubuntu init system, so you can use the following commands to start and stop it:
sudo service kurento-media-server start sudo service kurento-media-server stop
Log messages from KMS will be available in
/var/log/kurento-media-server/. For more details about KMS logs, check Debug Logging.
To upgrade a local installation of Kurento Media Server, you have to write the new version number into the file
/etc/apt/sources.list.d/kurento.list, which was created during Local Installation. After editing that file, you can choose between 2 options to actually apply the upgrade:
Upgrade all system packages.
This is the standard procedure expected by Debian & Ubuntu maintainer methodology. Upgrading all system packages is a way to ensure that everything is set to the latest version, and all bug fixes & security updates are applied too, so this is the most recommended method:
sudo apt-get update && sudo apt-get dist-upgrade
However, don’t do this inside a Docker container. Running apt-get upgrade or apt-get dist-upgrade is frowned upon by the Docker best practices; instead, you should just move to a newer version of the Kurento Docker images.
Uninstall the old Kurento version, before installing the new one.
Note however that apt-get is not good enough to remove all of Kurento packages. We recommend that you use aptitude for this, which works much better than apt-get:
sudo aptitude remove '?installed?version(kurento)' sudo apt-get update && sudo apt-get install --no-install-recommends --yes \ kurento-media-server
Be careful! If you fail to upgrade all Kurento packages, you will get wrong behaviors and crashes. Kurento is composed of several packages:
To use a newer version you have to upgrade all Kurento packages, not only the first one.
Working with WebRTC requires developers to learn and have a good understanding about everything related to NAT, ICE, STUN, and TURN. If you don’t know about these, you should start reading here: About NAT, ICE, STUN, TURN.
Kurento Media Server, just like any WebRTC endpoint, will work fine on its own, for LAN connections or for servers which have a public IP address assigned to them. However, sooner or later you will want to make your application work in a cloud environment with NAT firewalls, and allow KMS to connect with remote clients. At the same time, remote clients will probably want to connect from behind their own NAT router too, so your application needs to be prepared to perform NAT Traversal in both sides. This can be done by setting up a STUN server or a TURN relay, and configuring it in both KMS and the client browser.
These links contain the information needed to finish configuring your Kurento Media Server with a STUN/TURN server:
To verify that the Kurento process is up and running, use this command and look for the kurento-media-server process:
$ ps -fC kurento-media-server UID PID PPID C STIME TTY TIME CMD kurento 7688 1 0 13:36 ? 00:00:00 /usr/bin/kurento-media-server
Unless configured otherwise, KMS will listen on the port TCP 8888, to receive RPC Requests and send RPC Responses by means of the Kurento Protocol. Use this command to verify that this port is open and listening for incoming packets:
$ sudo netstat -tupln | grep -e kurento -e 8888 tcp6 0 0 :::8888 :::* LISTEN 7688/kurento-media-
You can change these parameters in the file
To check whether KMS is up and listening for connections, use the following command:
curl \ --include \ --header "Connection: Upgrade" \ --header "Upgrade: websocket" \ --header "Host: 127.0.0.1:8888" \ --header "Origin: 127.0.0.1" \ http://127.0.0.1:8888/kurento
You should get a response similar to this one:
HTTP/1.1 500 Internal Server Error Server: WebSocket++/0.7.0
Ignore the “Server Error” message: this is expected, and it actually proves that KMS is up and listening for connections.