Introduction

VROOM (short for Video ROOM) is a simple to use, web-based and opensource (MIT licence) video conferencing application.

VROOM uses the latest WebRTC technologies to allow video conferencing through a web browser without any plugin. There are several more or less similar hosted solutions available (like talky.io , appear.in , vLine.com for example). Most of them are more polished than VROOM, but I've found none entirely opensource, so I started this project.

You can get the source, and follow the development of VROOM on the github page of the project.

Features

VROOM implements the following features:

  • P2P Audio/Video conversations (no limit on the number of peers per room)
  • P2P text chat
  • Screen or single windows sharing
  • Send invitations by email
  • Be notified when someone joins one of your rooms
  • Persistent/reserved rooms
  • Chairman functionnalities (mute/pause/kick other peers)
  • Grant chairman role to other peers
  • Password protected rooms (different passwords for access and chairman)
  • Music on hold (when you're alone in a room)
  • Can be optionaly integrated with Etherpad-Lite

VROOM is available in french and english. You're welcome to submit patches or pull requests to enhance existing localizations, or add new ones.

How it works

WebRTC allows browsers to browsers direct connections. This provides the best latency as it avoids round trip through a server, which is important with real time communications. But it also ensures the privacy of your communications. VROOM takes advantage of those new technologies, and does the following:

  • When a client joins a room, it establishes a websocket connection to VROOM server. This is called the signaling channel. With this, all peers are able to exchange small messages with each other. But messages sent through this channels are routed through VROOM server, so it's not peer to peer yet
  • When a second peer joins the same room, he gets informations about how to connect directly to the other one(s) through this signaling channel.
  • Now, both peer exchange their video and audio stream directly
  • The signaling channel stays open and is used to transmit non sensitive informations (peer colors synchronization, notification of muting/kicking etc...)
  • Everything else (audio/video/text chat) is sent directly between peers through data channels

As long as possible, data channels and audio/video streams are established directly between peers, but in some situations, this is not possible (NAT, restrictive firewalls etc...). In those cases data streams are relayed through a TURN server

Technologies

VROOM is composed of two distincts
  • The client side: written in Javascript, it's the code executed on the browsers. This is where webcam streams are captured and sent to other peers. The biggest part is SimpleWebRTC
  • The server side: mainly written in Perl using the fabulous Mojolicious framework. This is where room are created and their configuration stored, and where permissions are managed. The backend uses an SQL (MySQL is the only supported engine for now) to store configurations

Install your own VROOM instance

The following guide will help you installing VROOM on your own server

Requirements

If you want to run your own VROOM instance, you'll need the following components

  • A MySQL compatible server (MySQL or MariaDB)
  • A webserver supporting HTTPS and reverse proxying, including websocket reverse proxying (Apache can do this with mod_proxy_wstunnel)
  • The following perl modules
    • DBI
    • DBD::mysql
    • Mojolicious
    • Mojolicious::Plugin::I18N
    • Mojolicious::Plugin::Mail
    • Mojolicious::Plugin::Database
    • Mojolicious::Plugin::StaticCompressor
    • Mojo::Redis2
    • Crypt::SaltedHash
    • MIME::Base64
    • Session::Token
    • Config::Simple
    • Email::Valid
    • Protocol::SocketIO::Handshake
    • Protocol::SocketIO::Message
    • Data::Dumper
    • DateTime
    • Array::Diff
    • Locale::Maketext::Lexicon
  • The following perl modules are optional
    • For Etherpad-Lite support:
      • Etherpad
    • To export events in a XLSX file
      • Mojolicious::Plugin::RenderFile
      • File::Temp
      • Excel::Writer::XLSX
It's also advised to run VROOM on a systemd powered distribution (simply because that's what I use and I include service units for VROOM). For the same reasons, I recommend running Apache as webserver (others like Nginx probably work too, but I provide configuration sample only for Apache)

VROOM can probably work with other database engines (like PostgreSQL) with minor modifications. If you're interrested in adding support, you're welcome to help
While VROOM should run on any distro, it's only tested on CentOS 7 x86_64, so it's the recommended platform. Also, all dependencies are available as RPM in Firewall Services' repository, so installation will be easier on CentOS 7. If you have it running on another system, please send me your notes so I can update this documentation.

Install on CentOS 7 x86_64

This guide assumes that you have installed a minimal CentOS 7 x86_64 system
For now, VROOM requires SELinux to be disabled, or permissive. You can set this in /etc/selinux/config

Configure the required repositories

You need to configure both EPEL and FWS repo

cat <<'_EOF' > /etc/yum.repos.d/fws.repo
[fws]
enabled=1
baseurl=http://repo.firewall-services.com/centos/$releasever/
name=Firewall Services
gpgcheck=1
gpgkey=http://repo.firewall-services.com/RPM-GPG-KEY
enablegroups=0
 
[fws-testing]
enabled=0
baseurl=http://repo.firewall-services.com/centos-testing/$releasever/
name=Firewall Services Testing
gpgcheck=1
gpgkey=http://repo.firewall-services.com/RPM-GPG-KEY
enablegroups=0
_EOF
yum install epel-release

Install dependencies

The following command will install everything required to run VROOM

yum install git tar wget httpd mod_ssl openssl mariadb-server redis \
            'perl(DBI)' \
            'perl(DBD::mysql)' \
            'perl(Array::Diff)' \
            'perl(Mojolicious)' \
            'perl(Mojolicious::Plugin::I18N)' \
            'perl(Mojolicious::Plugin::Mail)' \
            'perl(Mojolicious::Plugin::Database)' \
            'perl(Mojolicious::Plugin::StaticCompressor)' \
            'perl(Mojolicious::Plugin::RenderFile)' \
            'perl(Protocol::SocketIO)' \
            'perl(Mojo::Redis2)' \
            'perl(Crypt::SaltedHash)' \
            'perl(Etherpad)' \
            'perl(Sesion::Token)' \
            'perl(Digest::HMAC)' \
            'perl(Digest::SHA1)' \
            'perl(Email::Valid)' \
            'perl(File::Temp)' \
            'perl(Excel::Writer::XLSX)' \
            'perl(Locale::Maketext::Lexicon)' \
            'perl(Config::Simple)' \
            'perl(Session::Token)' \
            'perl(DateTime)' \
            'perl(Data::Dumper)'

Clone the repository

Lets install VROOM in /opt/vroom

cd /opt
git clone https://github.com/dani/vroom.git

Database

A database will be used to store rooms configuration, you must enable the server.

systemctl enable mariadb.service
systemctl start mariadb.service
Now, create a new database for VROOM
mysql -uroot
CREATE DATABASE `vroom` CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON `vroom`.* TO 'vroom'@'localhost' IDENTIFIED BY 'MySuperPassw0rd';
FLUSH PRIVILEGES;

It's better to generate a long, random password here. Just write it somewhere, you'll need it later

Now that we have our MySQL database, we can create the tables

mysql -uroot vroom < /opt/vroom/docs/database/schema.mysql

Setup Redis

Redis is used to share data between the various workers (when running with hypnotoad) and pass messages between peers connected on different workers. It doesn't require very specific settings. You can use this sample configuration:

cp -a /etc/redis.conf /etc/redis.conf.default
cat <<'_EOF' > /etc/redis.conf
daemonize no
bind 127.0.0.1
timeout 0
loglevel notice
logfile ""
databases 16
save 900 1
save 300 10
save 60 10000
dir /var/lib/redis/
_EOF
systemctl start redis
systemctl enable redis

Setup Apache

Two sample apache configurations are provided in the doc/httpd directory

  • httpd_alias.conf should work out of the box, VROOM will be available at https://yourservername/vroom
  • httpd_vhost.conf is an alternative which you can use if you prefer working with named virtualhosts (but will require additional config adjustments, especially in ssl.conf, which is out of scope for this guide)
Copy the config you want in /etc/httpd/conf.d/

In either case, you might want to adjust the apache configuration
The admin interface of VROOM will be available on /vroom/admin (alias) or /admin (vhost) and must be protected by your web server. VROOM provides no authentication at all. In the sample configuration, the access is restricted to localhost, but you can change this to anything you want

You also have to make sure the mod_proxy_wstunnel module is enabled, which is not the case by default on CentOS 7

echo "LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so" \
 > /etc/httpd/conf.modules.d/00-proxy_wstunnel.conf

Set permissions on the cache and tmp directories

The data directory must be writeable for the user running the VROOM daemon, which is vroom in the provided systemd unit

useradd -r -d /dev/null -s /sbin/nologin vroom
chown -R vroom ./data/
chmod 700 ./data/

Setup systemd units

Here, we'll copy the sample vroom.service unit so that systemd picks it up

cp /opt/vroom/docs/systemd/vroom.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable vroom

Configure VROOM

Now, we just need to configure vroom itself. Just copy the sample conf file

cp /opt/vroom/conf/settings.ini.dist /opt/vroom/conf/settings.ini
And edit it to your need. settings.ini has plenty of comments, but here's an explanation of the different sections and settings

database

This section is where you define access to the database used by VROOM. The following settings are available

  • dsn: The Data Source Name for your database. For example dsn = 'DBI:mysql:database=vroom;host=localhost'. See perl DBI documentation if you want more information
  • user: This is the username for your database
  • password: The password for your database
  • redis: The URI to reach your redis server. Exemple redis://127.0.0.1:6379/0
  • Be sure to specify the loopback address as 127.0.0.1 and not localhost as perl(EV) has an issue when a host is defined for both IPv4 and IPv6 in /etc/hosts (which is the case by default)

turn

This section defines which STUN and TURN servers will be used by the ICE process. If you plan to use VROOM only on a local network, where each peer can connect to each others, you can just omit this part. But if you want VROOM to work from anywhere, you'll need to use STUN and most likely TURN too.

  • stun_server: The STUN server(s) to use. For example stun_server = 'stun:stun.l.google.com:19302','stun:vroom.example.net:3478'. This must be a comma separated list of full STUN URI as defined by rfc7064
  • turn_server: The TURN server(s) to use. For example turn_server = 'turns:vroom.example.net:5349','turns:vroom.example.net:5349?transport=tcp'. This must be a comma separated list of full STUN URI as defined by rfc7065
  • credentials: This defines what TURN credentials are sent to clients. It can take two values:
    • static: With this mode, you're using a single set of credentials (defined in turn_user and turn_password) and they will be used by every peer in every room
    • rest: In this mode, VROOM will generate TURN REST API compatible credentials for each room. Each credentials set will be valid only for 5 minutes. You must set secret_key to the same secret key set in your TURN server. This is of course the prefered method.
  • turn_user and turn_password: To use your TURN server, you'll most likely require credentials. If using static credentials, you must set this to the username and password the clients will use
  • secret_key: When using the rest credentials method, set this to the secret key shared with the turn server

video

This section is for video quality settings. the available settings are

  • frame_rate: Number of frames per second for webcam streams. A bigger number will provide a better quality stream but will also require more bandwidth and CPU on each peer. The default is 15 fps

email

This section is for emails sent by VROOM (invitations, notifications, feedback form etc...). The available settings are

  • from: The address used in the From field of emails sent by VROOM.
  • contact: The email address which will get feedback form submissions.
  • sendmail: The path to the sendmail compatible binary to use (default is /usr/bin/sendmail and will probably won't need to be changed)

interface

This section controls the web interface. The available settings are

  • powered_by: will be displayed in the footer. You can put HTML code here.
  • template: The name of the template to use. Must be a directory under templates. The default, and only template provided is called default. But you can copy it and customize it to your needs
  • chrome_extension_id: This is the ID of the Chrome extension proposed to clients when trying to share screen for the first time (obviously, only for Chrome users). The reason this is configurable is because the extension requires the allowed websites to be listed. Two extensions are provided, the default (ecicdpoejfllflombfanbhfpgcimjddn) will work everywhere but allows screen capture on any website, which can be a security risk. The other extension (lfkdfilifapafomlhaaihfdglamkmdme) only works on https://vroom.im . You can create your own extension which will only work for your site, and submit it to Google Chrome Store if you want.
  • demo: If enabled, a few more pages and elements will be displayed, like the documentation you're reading right now.

rooms

This section controls rooms behavior. The available settings are

  • inactivity_timeout: The time (in minutes) after which a room without activity will be deleted
  • reserved_inactivity_timeout: The same, but for rooms which have been reserved (owner password set). You can set it to 0 if you do not want reserved room to expire
  • common_names: a comma separated list of names you don't want anyone to be able to reserve. Rooms with those names can be created, but not reserved. This is to prevent cybersquatting
  • max_members: This is the maximum number of peers able to be in a room at the same time. You can define a limit per room if you want. But the limit set here cannot be exceeded.

etherpad

Controls Etherpad-Lite integration. The following settings are available

  • uri: The URI to reach your Etherpad Lite instance. This instance must share the same base domain as VROOM because of the way sessions are created (Etherpad Lite sessions are created by VROOM directly and sent as a cookie to the clients)
  • api_key: The API key of your Etherpad Lite instance. You can find it in the file APIKEY.txt at the root of your Etherpad Lite installation
  • base_domain: This is the common part of your domain between VROOM and Etherpad Lite. For example, if you have VROOM running on https://vroom.example.net/ and Etherpad-Lite as https://pads.example.net, you'd put base_domain = 'example.net' here

directories

Controls where to find some specific directories

  • cache: This is where VROOM will store its cache (including auto generated and compressed assets like JS and CSS bundles)
  • tmp: This is where VROOM will store temp data like XLSX files when exporting events

daemon

Controls how VROOM daemon behaves. The following settings are available

  • listen_ip: This is the IP the daemon will listen on. Most of the time, you'll let 127.0.0.1 here as VROOM will be accessed through a reverse proxy
  • listen_port: The port VROOM daemon will bind to. Default is 8090. Just be sure to adjust your reverse proxy configuration if you change this.
  • backend: The backend used to run VROOM. Can be either morbo (recommended for developments) or hypnotoad (recommanded for production).
  • log_level: Set the logging level. Can be one of debug, info, warn, error or fatal
  • pid_file: Where to store the PID file of VROOM daemon (has no effect when using the morbo backend)

Setup coturn or rfc5766-turn-server

You can run any TURN server you want, but VROOM has only been tested with rfc5766-turn-server and coturn (which are very similar). The reference instance https://vroom.im is using coturn. To make use of it, follow those steps

Install the RPMS

You can now install the extracted RPMS

yum --enablerepo=fws install turnserver turnserver-utils

Configure turnserver

Here's a sample configuration:

mv /etc/turnserver/turnserver.conf /etc/turnserver/turnserver.conf.default
cat <<'EOF' > /etc/turnserver/turnserver.conf
verbose
fingerprint
lt-cred-mech
syslog
no-sslv2
no-sslv3
no-tcp
no-udp
tls-listening-port 5349
alt-tls-listening-port 3478
no-loopback-peers
no-multicast-peers
realm vroom
cert /etc/turnserver/cert.pem
pkey /etc/turnserver/key.pem
proc-user turnserver
proc-group turnserver
use-auth-secret
static-auth-secret SuperSecretPassword
EOF

  • An SSL certificate is needed for everything to work correctly and securely (/etc/turnserver/cert.pem and /etc/turnserver/key.pem in this example)
  • Both key and certificate must be readable by turnserver user and/or group
  • You can comment no-tcp, no-udp and alt-tls-listening-port if you want to test without encryption
  • If you have intermediate(s) CA, you have to put them in the cert.pem file, but after your certificate
  • In this example, the turn server will use TURN REST API compatible authentication, so you must set credentials='rest' and secret_key='SuperSecretPassword' in the turn section of VROOM's settings.ini

Enable and start turnserver

You can now start and enable turnserver

systemctl enable turnserver
systemctl start turnserver

You can check it's working with

journalctl -fl -u turnserver.service

Configuration of your firewall is out of scope for this doc, but you have to ensure the following ports are open:
  • TCP 3478, 3479, 5349, 5350 and 49152 to 65535
  • UDP 3478, 3479, 5349, 5350 and 49152 to 65535
If you use firewalld you can open the correct ports with the following commands
firewall-cmd --add-port 80/tcp \
             --add-port 443/tcp \
             --add-port 3478/tcp \
             --add-port 3479/tcp \
             --add-port 5349/tcp \
             --add-port 5350/tcp \
             --add-port 49152-65535/tcp
firewall-cmd --add-port 3478/udp \
             --add-port 3479/udp \
             --add-port 5349/udp \
             --add-port 5350/udp \
             --add-port 49152-65535/udp
firewall-cmd --permanent \
             --add-port 80/tcp \
             --add-port 443/tcp \
             --add-port 3478/tcp \
             --add-port 3479/tcp \
             --add-port 5349/tcp \
             --add-port 5350/tcp \
             --add-port 49152-65535/tcp
firewall-cmd --permanent \
             --add-port 3478/udp \
             --add-port 3479/udp \
             --add-port 5349/udp \
             --add-port 5350/udp \
             --add-port 49152-65535/udp

Etherpad-Lite integration

If you want to integrate VROOM with Etherpad-Lite, you'll have to get your instance running. First, install the dependencies

yum install nodejs npm
yum groupinstall "Development Tools"
Then, Create a user, clone the repository and prepare the config
useradd etherpad
cd /opt
git clone https://github.com/ether/etherpad-lite.git
chown -R etherpad:etherpad ./etherpad-lite
cp -a etherpad-lite/settings.json.template etherpad-lite/settings.json

Adapt /opt/etherpad-lite/settings.json to your need. The important settings are
  • "requireSession" : true
  • "editOnly" : true
  • "requireAuthentication": false

You can start etherpad manually the first time and check all its dependencies get installed

sudo -u etherpad /opt/etherpad-lite/bin/run.sh
Once you know it's ok, stop it with ctrl+C and create a systemd unit
cat <<'_EOF' > /etc/systemd/system/etherpad.service
[Unit]
Description=Run Etherpad-lite, the collaborative editor.
After=syslog.target network.target
 
[Service]
Type=simple
ExecStart=/opt/etherpad-lite/bin/run.sh 2>$1 < /dev/null
Restart=on-failure
StandardOutput=syslog
SyslogIdentifier=Etherpad-Lite
User=etherpad
Group=etherpad
 
[Install]
WantedBy=multi-user.target
_EOF
systemctl daemon-reload
systemctl enable etherpad
systemctl start etherpad
And uncomment the corresponding lines in your httpd configuration (/etc/httpd/conf.d/vroom_alias.conf or /etc/httpd/conf.d/vroom_vhost.conf)

Customize

Music on hold

VROOM includes 5 different songs available as music on hold. If you want to add more, just drop your files in public/snd/moh. When joining a room, VROOM will randomly choose one file from this directory

Appearence

If you want to customize the look and feel of VROOM, you can create your own templates. To do so, just copy the existing ones

cp -a /opt/vroom/templates/default /opt/vroom/templates/my_template
Then edit /opt/vroom/conf/settings.ini and set template = 'my_template' Restart VROOM so the configuration change is applied
systemctl restart vroom.service
And you can start modifying your templates.
As VROOM is still in early development, you'll have to closely follow how the default templates evolve and merge the changes in your own template
While working on your new template, it's recommanded to switch to the morbo backend as templates will be reloaded automatically after each modification

Admin area

The admin area is available on /vroom/admin or /admin (depending on how you have configured your web server).

Once again: There's no builtin auth mechanism, your web server must protect this URI
This page gives access to several sub menus to manage your VROOM instance

Room Management

This page lists all the existing rooms wih some important informations (creation date, last activity, number of participants) and three buttons to manage each room (join, configure, delete)

Audit

This page is to consult audit logs. Every important event in VROOM is logged

  • On stdout (ideally captured by systemd's Journal or similar)
  • In the audit table
Each event is composed of the following:
  • ID: It's just a unique ID for each event
  • Date: the date and time of the event
  • IP Address: The IP address of the user
  • Event: The type of event (see below)
  • User: The login of the user
  • Message: A human readable information describing the event
As all other dates, event dates are stored in the database in UTC and converted in local time when displayed. If you access directly the database to check the events, you'll have to do the conversion yourself. The dates also are in UTC in the XLSX exports of events

Event types and their meanings

Event type Signification
session_create A new cookie based session is created
session_destroy A session is destroyed. Usually the user explicitely quit a room
room_create A new room is created
room_modify Room configuration is modified
peer_role The role of a peer is changing (after authentication or being promoted to an owner of a room)
room_expire A room is being deleted because it showed no activity for too long
room_delete A room is being deleted by a user action
email_notification_change The list of email being notified when someone joins a room has been updated
send_invitation An email invitation to join the room is being sent
invitation_response Response to an invitation received
invalidate_invitation An invitation has been used, so is marked as invalide (invitations are only usable once)
pad_create A pad (Etherpad-Lite) is created
admin_key An API Key aquires admin privileges. Usually this happens when a user access /admin for the first time with this session
peer_id_mismatch Connection to the signaling channel attempted with a wrong peer ID
no_role Someone tried to join a room but has no valid role, so access is denied
member_off_limit A peer is being denied because member limit is already reached
room_join A peer joins a room
room_leave A peer leaves a room
api_action_denied An API action has been denied
api_action_allowed An API action was allowed
join_notification An email notification was sent because someone joined a room