search

opentok / opentok-rtc

OpenTok demo application
Other
106 stars 108 forks source link
javascript nodejs opentok screensharing sip tokbox webrtc

readme

OpenTokRTC

Tokbox is now known as Vonage

Build Status codecov

OpenTokRTC is your private web-based video conferencing solution. It is based on the OpenTok platform (now the Vonage Video API) and uses the OpenTok SDKs and API. You can deploy the app on your servers to get your own video conferencing app running on WebRTC.

This repository contains a Node.js server and a web client application.

Table of Contents

Installation

If you want to install OpenTokRTC on your own server, read on. If you want to deploy OpenTokRTC to Heroku, see INSTALL-heroku.md.

Requirements

You will need to install these dependencies on your machine:

You will also need these an OpenTok API key and secret. You can obtain these by signing up with OpenTok/Vonage Video API.

Installing dependencies

First, install the dependencies for the server.

If you use nvm, have it use the correct version of Node (v8):

$ nvm use

Then install the Node module dependencies:

$ npm install

Note: You will need to run these commands as a non-root user, else bower will refuse to execute.

Basic configuration

Once all the dependencies are in place, you will need to set some configuration options and install the application's dependencies. At a minimum, you need to set options for the OpenTok API key and secret to be used by the app. You can obtain these from your OpenTok account.

Other features of the app are enabled and configured using more configuration options, described in this README.

There are two ways to set configuration options for the application:

Using a config.json file

First create create a config.json file in the config folder.

$ cd <path-to-opentok-rtc>
$ cp config/example.json config/config.json

Edit the config.json file with the following, and replace <key> and <secret> with your OpenTok API key and the corresponding API secret:

{
    "OpenTok": {
        "apiKey": "<key>"
        "apiSecret": "<secret>"
    }
}

The config/example.json file includes settings for other options, which are described in the Configuration options section below.

Setting environment variables

You can set the TB_API_KEY and TB_API_SECRET to your OpenTok API key and secret. For example, the following shell commands export these values for use by the app (replace <key> and <secret> with your OpenTok API key and the corresponding API secret):

export TB_API_KEY=<key>
export TB_API_SECRET=<secret>

You can set other environment variables to enable and configure other options, which are described in the Configuration options section.

Running the app

Ensure that Redis server is running on localhost. In a terminal, run:

redis-server

Then start the application in foreground by running:

$ node server

This will start the application on port 8123 by default.

To specify a custom port number, use the -p flag when calling node server. For example, to run the application on port 8080, run:

$ node server -p 8080

Additionally, you can start the application as a daemon by passing -d flag, which starts the application and keeps it running in the background so that your terminal is not blocked:

$ node server -d

To start the server with HTTPS enabled, pass -S flag to launch a secure server along with -C <dir> flag to specify a directory that holds SSL certificate files. To quickly start a secure server, run:

$ node server -S -C sampleCerts

The server expects SSL certificate file to be named serverCert.pem and an SSL private key file to be named serverKey.pem. There is a pre-generated, self-signed SSL certificate pair in the ./sampleCerts directory.

For detailed information on available options, run $ node server -h.

Configuration options

You can enable and configure UI settings and other options using a config JSON file or by setting environment variables.

Environment variable settings overwrite any value set with the config JSON file.

The default config JSON file location is config/config.json. This path can be overwritten by setting the DEFAULT_JSON_CONFIG_PATH environment variable.

OpenTok configuration

The required configuration settings for the OpenTok API key and secret are described in the basic configuration section, earlier in this README.

There are other OpenTok configuration settings (each of which are optional):

The config.json setting is mediaMode. The environment variable name is MEDIA_MODE.

Config.json example:

{
    "OpenTok": {
      "apiKey": "<key>",
      "apiSecret": "<secret>",
      "publisherResolution": "1280x720",
      "jsUrl": "https://static.opentok.com/v2/js/opentok.min.js",
      "maxSessionAge": 7
    },
    "mediaMode": "routed"
}

Environment variable example:

export PUBLISHER_RESOLUTION="1280x720";
export TB_JS_URL="https://static.opentok.com/v2/js/opentok.min.js";
export TB_MAX_SESSION_AGE="7";

Phone dial-out

The app can dial out and add a phone-based end user to the OpenTok session, using the OpenTok SIP API. This app uses Nexmo as the SIP application that connects to OpenTok. (You can also use the OpenTok SIP API to connect to other SIP endpoints.)

To enable this feature:

  1. Sign up for a Nexmo/Vonage account.

  2. Edit options in the config/config.json file or set environment variables:

    • SIP.enabled (config.json) / SIP_ENABLED (environment variable) -- Set this to true.

    • SIP.username (config.json) / SIP_USERNAME (environment variable) -- Set this to the apiKey for the Nexmo account you created.

    • SIP.password (config.json) / SIP_PASSWORD (environment variable) -- Set this to the apiSecret for the Nexmo account you created.

    • SIP.requireGoogleAuth (config.json) / SIP_REQUIRE_GOOGLE_AUTH (environment variable) -- See Google Authentication for Phone dial-out for instructions on how to limit this functionality to users authenticated by their Google account.

Config.json example:

{
    "SIP": {
        "enabled" : true,
        "sipUsername" : "nexmoApiKey",
        "sipPassword" : "nexmoApiSecret",
        "requireGoogleAuth": false
    }
}

Environment variable example:

export SIP_ENABLED=true;
export SIP_USERNAME="nexmoApiKey";
export SIP_PASSWORD="nexmoApiSecret";
export SIP_REQUIRE_GOOGLE_AUTH=false;

Google Authentication for Phone dial-out

You can limit the ability to place outgoing calls to those authenticated by Google. To enable this feature:

  1. Create a Google API Console Project and client ID following the steps detailed here: https://developers.google.com/identity/sign-in/web/devconsole-project.

  2. Edit options in the config/config.json file or set environment variables:

    • Google.clientId (config.json) / GOOGLE_CLIENT_ID (environment variable) -- Set this to your client ID.

    • Google.hostedDomain (config.json) / GOOGLE_HOSTED_DOMAIN (environment variable) -- If you wish to limit sign in to accounts associated with a hosted domain, set the domain here.

    • Sip.requireGoogleAuth (config.json) / SIP_REQUIRE_GOOGLE_AUTH (environment variable) -- Set this totrue to require Google authentication for SIP dial-out as detailed in Phone dial-out.

Config.json example:

{
    "Google": {
        "clientId": "yourClientId.apps.googleusercontent.com",
        "hostedDomain": "yourhosteddomain.com"
    },
    "SIP" : {
        "sipUri" : "sip:phoneumber@sip.nexmo.com",
      "sipUsername" : "nexmoApiKey",
      "sipPassword" : "nexmoApiSecret",
      "requireGoogleAuth": true
    }
}

Environment variable example:

export GOOGLE_CLIENT_ID=yourClientId.apps.googleusercontent.com;
export GOOGLE_HOSTED_DOMAIN=yourhosteddomain.com;
export SIP_REQUIRE_GOOGLE_AUTH=true;

Archiving

To enable and configure archiving (recording), edit options in the config/config.json file or set environment variables:

Config.json example:

{
    "Archiving": {
        "enabled": true,
        "archiveAlways": true,
        "pollingInitialTimeout": 10000,
        "pollingTimeoutMultiplier": 1,
        "archiveManager": {
            "enabled": true,
        }
    }
}

Environment variable example:

export ENABLE_ARCHIVING=true;
export ARCHIVE_ALWAYS=true;
export ARCHIVE_TIMEOUT=10000;
export TIMEOUT_MULTIPLIER=1;
export ENABLE_ARCHIVE_MANAGER=true;

Screen sharing

To enable and configure screen sharing, edit options in the config/config.json file or set environment variables:

To learn more about how screen sharing works in OpenTok, see the guide on screen sharing.

Config.json example:

{
    "Screensharing": {
        "enabled": true,
        "chromeExtensionId": "cfhdojbkjhnklbpkdaibdccddilifddb",
        "annotations": {
            "enabled": true
        }
    } 
}

Environment variable example:

export ENABLE_SCREENSHARING=true;
export CHROME_EXTENSION_ID=cfhdojbkjhnklbpkdaibdccddilifddb;
export ENABLE_ANNOTATIONS=true;

Feedback

The app lets the developer POST feedback data to an endpoint on your HTTP server. To enable and configure this, edit options in the config/config.json file or set environment variables:

Config.json example:

{
    "Feedback": {
        "url": "https://my-app.com/feedback-endpoint/",
        "reportIssueLevel": 3
    }
}

Environment variable example:

export FEEDBACK_URL="https://my-app.com/feedback-endpoint/";
export REPORT_ISSUE_LEVEL=3;

Instead of posting feedback to an endpoint on your HTTP server, you can use Hotjar to collect feedback. Edit the following options in the config/config.json file or set environment variables:

Config.json example:

{
      "Feedback": {
          "hotjarId": "your-hotjar-id",
          "hotjarVersion": "your-hotjar-version",
          "enableFeedback": true,
      }
}

Environment variable example:

export HOTJAR_ID=your-hotjar-id;
export HOTJAR_VERSION=your-hotjar-version;
export ENABLE_FEEDBACK=true;

Pre-call test

Set the the TB_PRECALL_API_KEY and TB_PRECALL_API_SECRET environment variables to the the OpenTok API key and secret to use for the test session used by the precall-test. Or set these in the config.json file:

Config.json example:

{
    "precallTest": {
        "apiKey": "46049502",
        "apiSecret": "0f4a63f629cec64ebdc5552974fe2566d2eb2835"
    }
}

These are optional. If you do not set these, the pre-call test will use the same API key and secret that is used for the main OpenTok session used in the room.

You can disable the pre-call test by setting the ENABLE_PRECALL_TEST environment variable to false. Or you can disable it using the config file:

Config.json example:

{
    "precallTest": {
        "enabled": false
    }
}

Adobe Analytics

The app lets the developer configure Adobe Analytics to track user information. To configure this, edit options in the config/config.json file or set environment variables:

ICID tracking

You can set ICID query string values for the end (/thanks) page URLs with these settings:

Additional configuration options

Customizing the UI

For information on how to customize the OpenTokRTC UI, see CUSTOMIZING-UI.md.

Troubleshooting

"ServerPersistence: Timeout while connecting to the Persistence Provider! Is Redis running?

Ensure Redis server is running on localhost (run redis-server in the command line) and restart OpenTokRTC.

OpenTokRTC does not work when served over HTTP.

Browser security policies require HTTPS for WebRTC video communications. You will need to set up the app to be served over HTTPS. You can set up a secure reverse-proxy to your OpenTokRTC port using Nginx. For details, read this post.

UI looks broken

UI assets are compiled as part of the build process when installing application dependencies using npm install. If the web application UI still looks broken, run the following commands in the root directory of the application:

$ bower install
$ npm run clientBuild

We recommend that you run the application as a non-root user. However, if you are running the application as the root user, you will additionally need to tell bower to allow the root user to install dependencies, else bower will refuse to work:

$ bower install --allow-root

Health status check

There is a health status check endpoint at /server/health. You can load this URL to check whether the app is able to connect to all required external services. On success, this health check endpoint sends a response with the HTTP status code set to 200 and the JSON like the following:

{
  "name": "opentok-rtc",
  "version": "4.1.1",
  "gitHash": "312903cd043d5267bc11639718c47a9b313c1663",
  "opentok": true,
  "googleAuth": true,
  "status": "pass"
}

The JSON includes the following properties:

On failure, the health status check endpoint returns a response with the HTTP status code set 400 and JSON like the following:

{
  "name": "opentok-rtc",
  "version": "4.1.1",
  "git_hash": "312903cd043d5267bc11639718c47a9b313c1663",
  "opentok": false,
  "error": "OpenTok API server timeout exceeded.",
  "status": "fail"
}

Note that upon failure, the status property is set to "fail" and the error property is set to an error message. Also, the property for the failing test, such as opentok, will be set to false. If a test fails, the health check will not run subsequent tests.

Development and Contributing

Interested in contributing? We :heart: pull requests! See the Contribution guidelines.

Getting Help

We love to hear from you. If you have questions, comments or find a bug, let us know:

Further Reading

Check out the OpenTok documentation at https://tokbox.com/developer/.