Deploying OpenVidu on premises



Deployment instructions 🔗

OpenVidu is deployed in production as a set of Docker containers managed with Docker Compose.
You can deploy OpenVidu in any modern Linux distribution.

This procedure installs the following services:

  • OpenVidu Server (openvidu-server): this is the brain of OpenVidu platform. In charge of the signaling plane.
  • Kurento Media Server (kms): this is the heart of the OpenVidu platform. In charge of media plane.
  • Coturn (coturn): server used to allow media communications with browsers in certain special networks.
  • Redis (redis): database to manage users in Coturn server.
  • Nginx (nginx): a reverse proxy used to configure SSL certificate and to allow both Openvidu Server and the Application to be served in the standard https port (443).
  • Videoconference Application (app): OpenVidu Call application or any other application. Can be disabled.

NOTE 1 : Docker basic knowledge is not required, but recommended. If you are completely new to Docker and containers, take a few minutes to read the official Docker Get started documentation.

NOTE 2 : instructions below are intended for production environments. For development environments it is recommended to use this simple Docker image that wraps everything necessary to work inside your network in just a single container: openvidu/openvidu-server-kms

1) Prerequisites 🔗

  • Install Docker

  • Install Docker Compose. NOTE: install docker-compose from the link (official Docker site) as minimum version 1.24 is required.

  • Configure a domain name: OpenVidu is deployed using HTTPS because it is mandatory to use WebRTC. Then, if you do not have a domain name, an autogenerated SSL certificate will be used and an ugly warning will appear to your users when entering to your site. And of course you can suffer a man-in-the-middle attack. So it is recommended that you configure a domain name pointing to your machine's public IP. A valid SSL certificate can be automatically generated using Let's Encrypt in the installation process. If you already have a valid SSL certificate of your own, it also can be configured.

  • Port configuration in the server

    • Open these ports (in section Close ports to avoid external attacks you have an UFW sample to configure a firewall)

      • 22 TCP: to connect using SSH to admin OpenVidu.
      • 80 TCP: if you select Let's Encrypt to generate an SSL certificate this port is used by the generation process.
      • 443 TCP: OpenVidu server and application are published by default in standard https port.
      • 3478 TCP+UDP: used by TURN server to resolve clients IPs.
      • 40000 - 57000 TCP+UDP: used by Kurento Media Server to establish media connections.
      • 57001 - 65535 TCP+UDP: used by TURN server to establish relayed media connections.

    • Close all other ports: this is VERY important to avoid external attacks to OpenVidu internal services. Check troubleshooting section Close ports to avoid external attacks to learn more about this.

    • Free ports inside the server: OpenVidu platform services will need the following ports to be available in the machine: 80, 443, 3478, 5442, 5443, 6379 and 8888. If some of these ports is used by any process, OpenVidu platform won't work correctly. It is a typical error to have an NGINX process in the system before installing OpenVidu. Please uninstall it.



2) Deployment 🔗

You need root permissions to deploy OpenVidu.

sudo su

The recommended folder to install OpenVidu is /opt. Every other instruction in the documentation regarding on premises deployment assumes this installation path.

cd /opt

Now execute the following command to download and run the installation script.

curl https://s3-eu-west-1.amazonaws.com/aws.openvidu.io/install_openvidu_latest.sh | bash

This will download all required files into openvidu folder and will show this message with basic instructions:

=======================================
Openvidu Platform successfully installed.
=======================================

1. Go to openvidu folder:
$ cd openvidu

2. Configure DOMAIN_OR_PUBLIC_IP and OPENVIDU_SECRET in .env file:
$ nano .env

3. Start OpenVidu
$ ./openvidu start

For more information, check:
https://docs.openvidu.io/en/2.16.0/deployment/deploying-on-premises/

To deploy a fixed version, including previous ones, replace latest with the desired version number.
For example: curl https://s3-eu-west-1.amazonaws.com/aws.openvidu.io/install_openvidu_2.16.0.sh | bash



3) Configuration 🔗

OpenVidu Platform configuration is specified in the .env file with environment variables.

  • You must give a value to properties DOMAIN_OR_PUBLIC_IP and OPENVIDU_SECRET. Default empty values will fail.
  • You can change the CERTIFICATE_TYPE if you have a valid domain name. Setting this property to letsencrypt will automatically generate a valid certificate for you (it is required to set property LETSENCRYPT_EMAIL). Or if for any unknown reason you prefer to use your own certificate, set the property to owncert and place the certificate files as explained.
  • All other configuration properties come with sane defaults. You can go through them and change whatever you want. Visit OpenVidu Server configuration for further information.

The .env file is pretty self-explanatory. It looks like this:

# OpenVidu configuration
# ----------------------
# Documentation: https://docs.openvidu.io/en/stable/reference-docs/openvidu-config/

# NOTE: This file doesn't need to quote assignment values, like most shells do.
# All values are stored as-is, even if they contain spaces, so don't quote them.

# Domain name. If you do not have one, the public IP of the machine.
# For example: 198.51.100.1, or openvidu.example.com
DOMAIN_OR_PUBLIC_IP=

# OpenVidu SECRET used for apps to connect to OpenVidu server and users to access to OpenVidu Dashboard
OPENVIDU_SECRET=

# Certificate type:
# - selfsigned:  Self signed certificate. Not recommended for production use.
#                Users will see an ERROR when connected to web page.
# - owncert:     Valid certificate purchased in a Internet services company.
#                Please put the certificates files inside folder ./owncert
#                with names certificate.key and certificate.cert
# - letsencrypt: Generate a new certificate using letsencrypt. Please set the
#                required contact email for Let's Encrypt in LETSENCRYPT_EMAIL
#                variable.
CERTIFICATE_TYPE=selfsigned

# If CERTIFICATE_TYPE=letsencrypt, you need to configure a valid email for notifications
LETSENCRYPT_EMAIL=user@example.com
...

If you have questions about how to configure your Domain and SSL certificates, you can check these examples:

Videoconference application 🔗

By default, the OpenVidu Call application is deployed alongside OpenVidu Platform. It is accessible in the URL:

https://DOMAIN_OR_PUBLIC_IP:HTTPS_PORT/

For more information on how to disable it and deploy your own application (if needed) visit the section Deploy OpenVidu based Applications.


4) Execution 🔗

To start OpenVidu Platform (and the application if enabled) you can execute this command:

./openvidu start

All docker images for services will be downloaded (only the first time) and executed.

The first part of the log shows how docker-compose command executes all services:

Creating openvidu-docker-compose_coturn_1          ... done
Creating openvidu-docker-compose_app_1             ... done
Creating openvidu-docker-compose_kms_1             ... done
Creating openvidu-docker-compose_nginx_1           ... done
Creating openvidu-docker-compose_redis_1           ... done
Creating openvidu-docker-compose_openvidu-server_1 ... done

Then, openvidu-server service logs are shown. When OpenVidu Platform is ready you will see this message:

----------------------------------------------------

   OpenVidu Platform is ready!
   ---------------------------

   * OpenVidu Server: https://DOMAIN_OR_PUBLIC_IP/

   * OpenVidu Dashboard: https://DOMAIN_OR_PUBLIC_IP/dashboard/

----------------------------------------------------

You can press Ctrl+C to come back to the shell and OpenVidu will be executed in the background.

Available services 🔗

  • Consume OpenVidu REST API through https://DOMAIN_OR_PUBLIC_IP/
  • If the application is enabled, it will also be available at https://DOMAIN_OR_PUBLIC_IP/
  • You can open OpenVidu Dashboard to verify everything is working as expected at https://DOMAIN_OR_PUBLIC_IP/dashboard/ with credentials:
    • user: OPENVIDUAPP
    • pass: the value of OPENVIDU_SECRET in .env file



5) Administration 🔗

Run the following commands to manage OpenVidu Platform service:

  • Start OpenVidu

    ./openvidu start
    
  • Stop OpenVidu

    ./openvidu stop
    
  • Restart OpenVidu

    ./openvidu restart
    
  • Show logs of OpenVidu

    ./openvidu logs
    
  • Show logs of Kurento Media Server

    ./openvidu kms-logs
    
  • Show actual installed version of OpenVidu and basic information about the deployment

    ./openvidu version
    
  • Generate a report with useful information of the OpenVidu deployment. This report includes: system information, containers running, logs and configuration files

    ./openvidu report
    
  • List commands

    ./openvidu help
    

To change current configuration, you just need to update .env configuration file with the new desired values and run ./openvidu restart command.



Domain and SSL Configuration Examples 🔗

For these examples, all steps from Deploying OpenVidu on premises should be followed. These examples are focusing in the Domain and SSL Configuration. The necessary parameters to use are explained in the Configuration Section. This examples scenarios have the purpose to clarify any doubt on how to configure the Domain and SSL configuration of OpenVidu on premises.

As OpenVidu is deployed with default sane configuration, your domain and SSL certificate configuration are the most important parameters to deploy your stack correctly.

Let's see all different scenarios:

1) Self-signed certificate 🔗

This scenerario should be used only for development environments. Don't use it in production.

This scenario is meant for you if you want to:

  • Deploy OpenVidu quickly for testing or developing purposes.
  • Deploy OpenVidu without a Fully Qualified Domain Name (FQDN).

Let's suppose that OpenVidu is installed following the instructions from here, and we have, for example, this public IP: 123.12.123.12

For this specific scenario you will need to:

1.1) Edit /opt/openvidu/.env 🔗

To make our deployment works with a self-signed certificate, you just need to edit the file in /opt/openvidu/.env and fill the next variables:

DOMAIN_OR_PUBLIC_IP=123.12.123.12

CERTIFICATE_TYPE=selfsigned

OPENVIDU_SECRET=<YOUR_SECRET>

Only these variables are needed to make it works. The rest of the variables in the /opt/openvidu/.env are referred to OpenVidu Configuration parameters.

The variable LETSENCRYPT_EMAIL should be empty for this kind of certificate.

Also, if you have a Fully Qualified Domain Name pointing to your IP address, you can use it in the DOMAIN_OR_PUBLIC_IP. For example:

DOMAIN_OR_PUBLIC_IP=example.openvidu.io

2) Let's Encrypt certificate 🔗

This scenario is meant for you if you want to:

  • Deploy OpenVidu for production or even developing purposes.
  • Deploy OpenVidu with a Fully Qualified Domain Name (FQDN).
  • Use a valid SSL certificate.

For this specific scenario you will need to:

2.1) Register a FQDN pointing to your public IP 🔗

This depends of the DNS register you want to use. You need to create a DNS register of type A pointing to your server public IP. Let's suppose that our domain is: example.openvidu.io.

2.2) Edit /opt/openvidu/.env 🔗

To make our deployment works with a Let's encrypt certificate, you just need to edit the file in /opt/openvidu/.env and fill the next variables:

DOMAIN_OR_PUBLIC_IP=example.openvidu.io

CERTIFICATE_TYPE=letsencrypt

OPENVIDU_SECRET=<YOUR_SECRET>

LETSENCRYPT_EMAIL=youremail@youremail.com

Only these variables are needed to make it works. The rest of the variables in the /opt/openvidu/.env are referred to OpenVidu Configuration parameters.

You must define the LETSENCRYPT_EMAIL where you want to register the domain and receive Let's Encrypt notifications.

3) Custom Certificate (Commercial CA) 🔗

This scenario is meant for you if you want to:

  • Deploy OpenVidu for production.
  • Deploy OpenVidu with a Fully Qualified Domain Name (FQDN).
  • Use a valid SSL certificate from a Commercial CA.

To use this kind of certificate, you need to generate two files, certificate.cert (public keys of the certificate) and certificate.key (private key) and copy them into the /opt/openvidu/owncert directory.

3.1) Register a FQDN pointing to your public IP 🔗

This depends of the DNS register you want to use. You need to create a DNS register of type A pointing to your server public IP. Let's suppose that our domain is: example.openvidu.io.

3.2) Generate certificates files 🔗

1) Create a CSR and a private key. This can be easily done by executing:

openssl req -newkey rsa:2048 -nodes -keyout certificate.key -out certificate.csr

While executing this command, you will be asked to enter some information to generate the files certificate.key and certificate.csr. Ensure that all these information are correctly inserted (Common Name, Organization Name, etc...). The most important parameter is the Common Name field which should match the name that you want to use for your certificate.

For example, let's suppose that your domain is example.openvidu.io. The parameter Common Name could be: example.openvidu.io or www.example.openvidu.io. Otherwise, if you're using a WildCart certificate, the Common Name parameter would be *.openvidu.io.

2) The previous command generated the certificate.key and certificate.csr files. The certificate.csr is the one that you need to provide to your CA. Depending of your CA this step can differ. Check your CA documentation about this topic.

3) Usually the files to generate the certificate.cert can be downloaded or are sent via email from the CA. These files are:

  • The intermediate certificate. (It usually have more than one key with ---BEGIN CERTIFICATE--- This file will be called as intermediate.cert in following steps.
  • Your ssl certificate. An unique certificate key with ---BEGIN CERTIFICATE---. This file will be called as public.cert in following steps.

4) You need to concat these two files in an unique certificate.cert file in this way:

cat public.cert intermediate.crt > certificate.cert

5) Now you have the certificate.key generated in step 1) and the certificate.cert generated in step 4).

If you're still having doubts about how to generate the certificates files, you can follow this guide for a further understanding.



3.3) Copy certificate.key and certificate.cert 🔗

Now that you have both certificate files, you need to copy the certificate.key and the certificate.cert into /opt/openvidu/owncert

The directory should look like this:

/opt/openvidu/owncert
├── certificate.cert
└── certificate.key

3.4) Edit /opt/openvidu/.env 🔗

To make our deployment works with a Custom Certificate (Commercial CA) certificate, you just need to edit the file in /opt/openvidu/.env and fill the next variables:

DOMAIN_OR_PUBLIC_IP=example.openvidu.io

OPENVIDU_SECRET=<YOUR_SECRET>

CERTIFICATE_TYPE=owncert

Only these variables are needed to start OpenVidu. The rest of the variables in the /opt/openvidu/.env are referred to OpenVidu Configuration parameters.

The variable LETSENCRYPT_EMAIL should be empty for this kind of certificate.

Common problems 🔗


Troubleshooting 🔗

Configuration errors 🔗

If there's any error with the configuration, a report detailing which configuration property has issues and a step-by-step guide to fix it will be immediately shown by OpenVidu. The report will be similar to this:

Configuration errors
--------------------

* Property OPENVIDU_SECRET is not set. Cannot be empty.
* Property DOMAIN_OR_PUBLIC_IP is not set. Cannot be empty


Fix config errors
---------------

1) Return to shell pressing Ctrl+C
2) Set correct values in '.env' configuration file
3) Restart OpenVidu with:

    $ ./openvidu restart

Docker compose 🔗

To solve any other issue, it is important to understand how is OpenVidu executed.

OpenVidu is executed as a docker-compose file. The commands executed by the script are the standard docker-compose commands, so internally they just do:

  • start
    • $ docker-compose up -d
    • $ docker-compose logs -f openvidu-server
  • stop
    • $ docker-compose down
  • restart
    • $ docker-compose down
    • $ docker-compose up -d
    • $ docker-compose logs -f openvidu-server
  • logs
    • $ docker-compose logs -f openvidu-server


As you can see, logs of openvidu-server service are shown when platform is started or restarted. This log contains the most important information for the OpenVidu execution.


Show service logs 🔗

Take a look to service logs to see what happened.

OpenVidu logs 🔗

To show all logs, execute:

./openvidu logs

Also you can execute this if you want to follow logs in real time:

./openvidu logs -f

Kurento Media Server logs 🔗

If you want to check Kurento Media Server, you can't do docker-compose logs kms. Kurento media server logs are not managed by Docker. They're stored in /opt/openvidu/kurento-logs. If you want to check Kurento logs you can check this directory or execute:

./openvidu kms-logs

To follow Kurento Media Server logs in real time you can execute:

./openvidu kms-logs -f

Other services logs 🔗

You can also see all service logs together:

docker-compose logs -f

Or you can inspect one by one the other services:

docker-compose logs -f nginx
docker-compose logs -f coturn
docker-compose logs -f redis
docker-compose logs -f app

Review the configuration 🔗

Sometimes we may have a typo when writing a property name. For this reason, openvidu-server prints in the log all the configuration properties you have set in .env file and the default values for all other configuration properties. In that way, you can double check what openvidu-server actually sees.

Configuration properties
---------------------
* CERTIFICATE_TYPE=selfsigned
* OPENVIDU_CDR=false
* OPENVIDU_CDR_PATH=/opt/openvidu/cdr
* DOMAIN_OR_PUBLIC_IP=my.domain.com
* OPENVIDU_RECORDING=false
* OPENVIDU_RECORDING_AUTOSTOP-TIMEOUT=120
* OPENVIDU_RECORDING_COMPOSED-URL=

...

Change log level of the services 🔗

To change the level of OpenVidu logs (openvidu-server docker service) change the property OV_CE_DEBUG_LEVEL in configuration file .env.

To change the level of Kurento Media Server logs (kms docker service) change the property KMS_DOCKER_ENV_GST_DEBUG in configuration file .env. For more information about possible values visit Kurento Debug Logging.


Change Kurento Media Server docker image 🔗

OpenVidu and Kurento Media Server evolve at a different pace. Sometimes, it is possible that a new KMS is released but OpenVidu is not still updated. In that case, if you hit a bug that might be solved in the last KMS version, you can test if just updating KMS fixes your issue. KMS_IMAGE property allows you to specify the new KMS image in configuration file .env.


Close ports to avoid external attacks 🔗

Closing all non-necessary ports in your server is very important to avoid external attacks. Some administrators using OpenVidu have reported attacks because their ports weren't properly closed. Of course, all of the opened ports stated in Prerequisites section must be accessible from the exterior, but the rest must be closed to grant proper protection.

Typically, cloud providers initiate their machines with all ports closed by default, so usually it is only necessary to open the required ones. For example, you can configure public/private ports in in OpenStack with OpenStack security groups, in AWS with AWS security groups, etc...

If your only choice is to manually configure a firewall, you can for example install in any GNU/LInux system the great UFW (Uncomplicated Firewall) (sudo apt install ufw) with the following configuration to only allow the required ports:

ufw allow ssh
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 3478/tcp
ufw allow 3478/udp
ufw allow 40000:57000/tcp
ufw allow 40000:57000/udp
ufw allow 57001:65535/tcp
ufw allow 57001:65535/udp
ufw enable

Kurento Media Server crash 🔗

Sometimes Kurento Media Server (the service in charge of streaming media inside of Media Nodes) may crash. If this happens on a regular basis, or better, you have isolated a specific use case where KMS always crashes, then perform the following steps to collect a crash report that will help us fix the issue.

You must perform these steps in the server hosting your OpenVidu deployment. Take into account that all of these instructions must be executed with root permissions:

sudo su

1) Enable KMS crash reporting 🔗

echo "/opt/openvidu/kms-crashes/core_%e_%p_%u_%t" | tee /proc/sys/kernel/core_pattern > /dev/null

Let's prove that crash reporting is properly working. Execute the followings commands:

docker container kill --signal=SIGSEGV $(docker ps --format "{{.Names}}" | grep kms | head -1)
ls -l /opt/openvidu/kms-crashes

If you see something like this ...

-rw------- 1 root root 227282944 abr 17 19:06 core_kurento-media-s_1_0_1587143183
-rw------- 1 root root   3911680 abr 17 19:06 core_kurento-media-s_65_0_1587143183
-rw------- 1 root root 227233792 abr 17 19:06 core_kurento-media-s_66_0_1587143183

... then everything is working as expected. Delete this test report and restart OpenVidu:

rm -rf /opt/openvidu/kms-crashes/*
cd /opt/openvidu
./openvidu restart

2) Replicate the error 🔗

Now is the moment to replicate the KMS error. Use your OpenVidu application until the error appears, and then we'll be ready to collect the crash report.

3) Collect the KMS crash report 🔗

Once the error has occurred, compress the crash report in a core_dumps.tar.gz file and download it. You can do so from your computer with the following SSH commands:

ssh USER@OPENVIDU_IP "sudo tar zcvfP ~/core_dumps.tar.gz /opt/openvidu/kms-crashes/*"
scp USER@OPENVIDU_IP:~/core_dumps.tar.gz core_dumps.tar.gz

Replace USER with a user of your server with root permissions and OPENVIDU_IP with the server's IP address. File core_dumps.tar.gz will be downloaded to your PC and it will be ready to be sent to us.

4) Clean the KMS crash report 🔗

So as not to consume too much hard drive, remember to delete the crash reports once you have sent it to us. IMPORTANT: obviously, do NOT do this before zipping and sending the report.

ssh USER@OPENVIDU_IP "sudo rm /opt/openvidu/kms-crashes* && sudo rm ~/core_dumps.tar.gz"

Replace USER with a user of your server with root permissions and OPENVIDU_IP with the server's IP address.