% title $self->l('DOCUMENTATION');
%= include 'header'
%= include 'public_toolbar'
<div class="container-fluid">
<div class="row-fluid">
<div class="hidden-xs col-sm-3">
<div id="toc">
</div>
</div>
<div class="col-sm-9" id="doc-content">
<h1 id="intro">
Introduction
</h1>
<p>
VROOM (short for <strong>V</strong>ideo <strong>ROOM</strong>) is a simple to use, web-based and opensource (MIT licence) video conferencing application.
</p>
<p>
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
<a href="https://talky.io/" target="_blank">talky.io</a>,
<a href="https://appear.in/" target="_blank">appear.in</a>,
<a href="https://vline.com/" target="_blank">vLine.com</a> for example).
Most of them are more polished than VROOM, but I've found none entirely opensource, so I started this project.
</p>
<p>
You can get the source, and follow the development of VROOM on the <a href="https://github.com/dani/vroom" target="_blank">github page</a>
of the project.
</p>
<h1 id="features">
Features
</h1>
<p>
VROOM implements the following features:
<ul>
<li>Audio/Video conversations (no limit on the number of peers per room)</li>
<li>Text chat (with possibility to save the history)</li>
<li>Screen or single windows sharing sharing</li>
<li>Invite anyone by email</li>
<li>Be notified (by email) when someone joins one of your rooms</li>
<li>Persistent/reserved rooms</li>
<li>Chairman functionnalities (mute/pause/kick other peers)</li>
<li>Grant chairman role to other peers</li>
<li>Password protected rooms (different passwords for access and chairman)</li>
<li>Music on hold (when you're alone in a room)</li>
<li>Can be optionaly integrated with <a href="https://github.com/ether/etherpad-lite" target="_blank">Etherpad-Lite</a></li>
</ul>
</p>
<p>
VROOM is available in French and English. You're welcome to submit patches or pull requests to enhance existing localizations, or add new ones.
</p>
<h1 id="how_it_works">
How it works
</h1>
<p>
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:
<ul>
<li>When a client joins a room, it establishes a <a href="https://en.wikipedia.org/wiki/WebSocket" target="_blank">websocket</a> 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 yet peer to peer</li>
<li>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.</li>
<li>Now, both peer exchange their video and audio stream directly</li>
<li>The signaling channel stays open and is used to transmit non sensitive informations (peer colors synchronization, notification of muting/kicking etc...)</li>
<li>Everything else (audio/video/text chat) is sent through data channels</li>
</ul>
</p>
<div class="alert alert-warning">
As long as possible, data channels and audio/video streams are established directly between peers, but in some situations, this is not possible (NAT, firewalls etc...). In those cases
data streams are relayed through a <a href="https://en.wikipedia.org/wiki/Traversal_Using_Relays_around_NAT" target="_blank">TURN</a> server
</div>
<h1 id="install_your_own">
Install your own VROOM instance
</h1>
The following guide will help you installing VROOM on your own server
<h2 id="requirements">
Requirements
</h2>
<p>
If you want to run your own VROOM instance, you'll need the following components
<ul>
<li><a href="http://mojolicio.us" target="_blank">Mojolicious</a> 5 or better</li>
<li>A MySQL compatible server (MySQL or MariaDB)</li>
<li>A webserver supporting HTTPS and reverse proxying, including websocket reverse proxying (Apache can do this with mod_proxy_wstunnel)</li>
<li>The following perl modules
<ul>
<li>Mojolicious::Plugin::Mail</li>
<li>Mojolicious::Plugin::Database</li>
<li>Mojolicious::Plugin::StaticCompressor</li>
<li>Crypt::SaltedHash</li>
<li>MIME::Base64</li>
<li>Etherpad::API</li>
<li>Session::Token</li>
<li>Config::Simple</li>
<li>Email::Valid</li>
<li>Protocol::SocketIO::Handshake</li>
<li>Protocol::SocketIO::Message</li>
<li>Data::Dumper</li>
</ul>
</ul>
</ul>
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 reason, I recommend running Apache as webserver (others like Nginx probably work too, but I provide configuration sample only for Apache)
</p>
<div class="alert alert-warning">
VROOM can probably work with other DB engine (like PostgreSQL) with minor modifications.
If you're interrested in adding support for other engines, you're welcome to help
</div>
<div class="alert alert-warning">
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 <a href="http://repo.firewall-services.com/centos/" target="_blank">Firewall Services'</a>
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.
</div>
<h2 id="install_on_c7">
Install on CentOS 7 x86_64
</h2>
<div class="alert alert-warning">
This guide assumes that you have installed a minimal CentOS 7 x86_64 system
</div>
<div class="alert alert-danger">
For now, VROOM requires SELinux to be disabled, or permissive. You can set this in <strong>/etc/selinux/config</strong>
</div>
<h3 id="c7_repo">
Configure the required repositories
</h3>
<p>
You need to configure both EPEL and FWS repo<br>
<pre>
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</pre>
</p>
<h3 id="c7_dependencies">
Install dependencies
</h3>
<p>
The following command will install everything required to run VROOM
<pre>
yum install git tar wget httpd mod_ssl openssl mariadb-server \\
'perl(Mojolicious)' 'perl(Mojolicious::Plugin::I18N)' 'perl(Mojolicious::Plugin::Mail)' \\
'perl(Crypt::SaltedHash)' 'perl(Etherpad::API)' 'perl(LWP::Protocol::https)' \\
'perl(Sesion::Token)' 'perl(Mojolicious::Plugin::Database)' \\
'perl(Mojolicious::Plugin::StaticCompressor' 'perl(Email::Valid)' \\
'perl(Config::Simple)' 'perl(Session::Token)'</pre>
</p>
<h3 id="c7_clone_git">
Clone the repository
</h3>
<p>
Lets install VROOM in <strong>/opt/vroom</strong>
<pre>
cd /opt
git clone https://github.com/dani/vroom.git</pre>
</p>
<h3 id="c7_database">
Database
</h3>
<p>
A database will be used to store rooms configuration, you must enable the server.
<pre>
systemctl enable mariadb.service
systemctl start mariadb.service</pre>
Now, create a new database for VROOM
<pre>
mysql -uroot</pre>
<pre>
CREATE DATABASE `vroom` CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON `vroom`.* TO 'vroom'@'localhost' IDENTIFIED BY 'MySuperPassw0rd';
FLUSH PRIVILEGES;</pre>
</p>
<div class="alert alert-warning">
It's better to generate a long, random password here. Just write it somewhere, you'll need it later
</div>
<p>
Now that we have our MySQL database, we can create the tables
<pre>
mysql -uroot vroom < /opt/vroom/docs/database/schema.mysql</pre>
</p>
<h3 id="c7_apache">
Setup Apache
</h3>
<p>
Two sample apache configurations are provided in the <strong>conf</strong> directory
<ul>
<li><strong>httpd_alias.conf</strong> should work out of the box, VROOM will be available at <em>https://yourservername/vroom</em></li>
<li><strong>httpd_vhost.conf</strong> 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)</li>
</ul>
Copy the config you want in /etc/httpd/conf.d/
</p>
<div class="alert alert-warning">
In either case, you might want to adjust the apache configuration
</div>
<div class="alert alert-danger">
The admin interface of VROOM will be available on /vroom/admin (alias) or /admin (vhost) and <strong>must</strong> be protected by your web server.
VROOM provides <strong>no authentication at all</strong>. In the sample configuration, the access is restricted to localhost,
but you can change this to anything you want
</div>
<p>
You also have to make sure the <strong>mod_proxy_wstunnel</strong> module is enabled, which is not the case by default on CentOS 7
<pre>
echo "LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so" \\
> /etc/httpd/conf.modules.d/00-proxy_wstunnel.conf</pre>
</p>
<h3 id="c7_cache_dir_perm">
Set permissions on the cache directory
</h3>
<p>
The <strong>cache</strong> directory must be writeable for the user running the VROOM daemon, which is apache in the provided systemd unit
<pre>
chown -R apache ./cache
chmod 700 ./cache</pre>
</p>
<h3 id="c7_systemd_unit">
Setup systemd units
</h3>
<p>
Here, we'll copy the sample vroom.service unit so that systemd picks it up
<pre>
cp /opt/vroom/docs/systemd/vroom.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable vroom</pre>
</p>
<h2 id="config_vroom">
Configure VROOM
</h2>
<p>
Now, we just need to configure vroom itself. Just copy the sample conf file
<pre>
cp /opt/vroom/conf/settings.ini.dist /opt/vroom/conf/settings.ini</pre>
And edit it to your need. settings.ini has plenty of comments, but here's an explanation of the different sections and settings
</p>
<h3 id="settings_database">
database
</h3>
<p>
This section is where you define access to the database used by VROOM. The following settings are available
<ul>
<li><strong>dsn</strong>: The <strong>D</strong>ata <strong>S</strong>ource <strong>N</strong>ame for your database.
For example <kbd>dsn = 'DBI:mysql:database=vroom;host=localhost'</kbd>. See perl DBI documentation if you want more information</li>
<li><strong>user</strong>: This is the username for your database</li>
<li><strong>password</strong>: The password for your database</li>
</ul>
</p>
<h3 id="settings_turn">
turn
</h3>
<p>
This section defines which <a href="http://en.wikipedia.org/wiki/STUN" target="_blank">STUN</a> and
<a href="http://en.wikipedia.org/wiki/Traversal_Using_Relays_around_NAT" target="_blank">TURN</a> servers
will be used by the <a href="http://en.wikipedia.org/wiki/Interactive_Connectivity_Establishment" target="_blank">ICE</a> 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.
<ul>
<li><strong>stun_server</strong>: The STUN server(s) to use. For example
<kbd>stun_server = 'stun:stun.l.google.com:19302','stun:vroom.example.net:3478'</kbd>.
This must be a comma separated list of full STUN URI as defined by <a href="https://tools.ietf.org/html/rfc7064" target="_blank">rfc7064</a></li>
<li><strong>turn_server</strong>: The TURN server(s) to use. For example
<kbd>turn_server = 'turns:vroom.example.net:5349','turns:vroom.example.net:5349?transport=tcp'</kbd>.
This must be a comma separated list of full STUN URI as defined by <a href="https://tools.ietf.org/html/rfc7065" target="_blank">rfc7065</a></li>
<li><strong>credentials</strong>: This defines what TURN credentials are sent to clients. It can take two values:
<ul>
<li><strong>static</strong>: With this mode, you're using a single set of credentials (set with <strong>turn_user</strong> and
<strong>turn_password</strong>) and they will be used by every peer in every room</li>
<li><strong>rest</strong>: In this mode, VROOM will generate <a href="https://tools.ietf.org/html/draft-uberti-rtcweb-turn-rest-00" target="_blank">TURN REST API</a>
compatible credentials for each room. Each credentials set will be valid only for 5 minutes. You must set <strong>secret_key</strong> to the same secret key
set in your TURN server</li>
</ul>
</li>
<li><strong>turn_user</strong> and <strong>turn_password</strong>: 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</li>
<li><strong>secret_key</strong>: When using the <strong>rest</strong> credentials method, set this to the secret key shared with the turn server</li>
</ul>
</p>
<h3 id="settings_video">
video
</h3>
<p>
This section is for video quality settings. the available settings are
<ul>
<li><strong>frame_rate</strong>: 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
</ul>
</p>
<h3 id="settings_email">
email
</h3>
<p>
This section is for emails sent by VROOM (invitations, notifications, feedback form etc...). The available settings are
<ul>
<li><strong>from</strong>: The address used in the From field of emails sent by VROOM.</li>
<li><strong>contact</strong>: The email address which will get feedback form submissions.</li>
<li><strong>sendmail</strong>: The path to the sendmail compatible binary to use (default is /usr/bin/sendmail and will probably won't need to be changed)</li>
</ul>
</p>
<h3 id="settings_interface">
interface
</h3>
<p>
This section controls the web interface. The available settings are
<ul>
<li><strong>powered_by</strong>: will be displayed in the footer. You can put HTML code here.</li>
<li><strong>template</strong>: The name of the template to use. Must be a directory under <strong>templates</strong>. The default,
and only template provided is called <strong>default</strong>. But you can copy it and customize it to your needs</li>
<li><strong>chrome_extension_id</strong>: 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 <a href="https://vroom.im" target="_blank">https://vroom.im</a>.
You can create your own extension which will only work for your site, and submit it to Google Chrome Store if you want.</li>
<li><strong>demo</strong>: If enabled, a few more pages and elements will be displayed, like the documentation you're reading right now.</li>
</ul>
</p>
<h3 id="settings_rooms">
rooms
</h3>
<p>
This section controls rooms behavior. The available settings are
<ul>
<li><strong>inactivity_timeout</strong>: The time (in minutes) after which a room without activity will be deleted</li>
<li><strong>reserved_inactivity_timeout</strong>: 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</li>
<li><strong>common_names</strong>: 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</li>
<li><strong>max_members</strong>: 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.</li>
</ul>
</p>
<h3 id="settings_ertherpad">
etherpad
</h3>
<p>
Controls <a href="https://github.com/ether/etherpad-lite" target="_blank">Etherpad-Lite</a> integration. The following settings are available
<ul>
<li><strong>uri</strong>: 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)</li>
<li><strong>api_key</strong>: The API key of your Etherpad-Lite instance. You can find it in the file <strong>APIKEY.txt</strong> at the root
of your Etherpad Lite installation</li>
<li><strong>base_domain</strong>: 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 <kbd>base_domain = 'example.net'</kbd> here</li>
</ul>
</p>
<h3 id="settings_directories">
directories
</h3>
<p>
Controls where to find some specific directories
<ul>
<li><strong>cache</strong>: This is where VROOM will store its cache (including auto generated and compressed assets like JS and CSS bundles)</li>
</ul>
</p>
<h3 id="settings_daemon">
daemon
</h3>
<p>
Controls how VROOM daemon behaves. The following settings are available
<ul>
<li><strong>listen_ip</strong>: This is the IP the daemon will listen on. Most of the time, you'll let <strong>127.0.0.1</strong> here as VROOM will
be accessed through a reverse proxy</li>
<li><strong>listen_port</strong>: The port VROOM daemon will bind to. Default is <strong>8090</strong>. Just be sure to adjust your reverse proxy
configuration if you change this.</li>
<li><strong>backend</strong>: The backend used to run VROOM. Can be either
<a href="http://mojolicio.us/perldoc/Mojo/Server/Morbo" target="_blank"><strong>morbo</strong></a> (recommended for developments) or
<a href="http://mojolicio.us/perldoc/Mojo/Server/Hypnotoad" target="_blank"><strong>hypnotoad</strong></a> (recommanded for production).</li>
<li><strong>log_level</strong>: Set the logging level. Can be one of <strong>debug</strong>, <strong>info</strong>, <strong>warn</strong>,
<strong>error</strong> or <strong>fatal</strong></li>
<li><strong>pid_file</strong>: Where to store the PID file of VROOM daemon (has no effect when using the morbo backend)</li>
</ul>
</p>
<h1 id="turn_server">
Setup coturn or rfc5766-turn-server
</h1>
<p>
You can run any TURN server you want, but VROOM is mainly tested <a href="https://code.google.com/p/rfc5766-turn-server/" target="_blank">rfc5766-turn-server</a>
or <a href="https://code.google.com/p/coturn/" target="_blank">coturn</a> (which are very similar). The reference instance https://vroom.im is using coturn.
To make use of it, follow those steps
</p>
<h2 id="turn_install">
Install the RPMS
</h2>
<p>
You can now install the extracted RPMS
<pre>
yum --enablerepo=fws install turnserver turnserver-utils</pre>
</p>
<h2 id="turn_configure">
Configure turnserver
</h2>
<p>
Here's a sample configuration:
<pre>
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</pre>
</p>
<div class="alert alert-warning">
<ul>
<li>An SSL certificate is needed for everything to work correctly and securely (<strong>/etc/turnserver/cert.pem</strong> and <strong>/etc/turnserver/key.pem</strong> in this example)</li>
<li>Both key and certificate must be readable by turnserver user and/or group</li>
<li>You can comment no-tcp, no-udp and alt-tls-listening-port if you want to test without encryption</li>
<li>If you have intermediate(s) CA, you have to put them in the cert.pem file, but after your certificate</li>
<li>In this example, the turn server will use TURN REST API compatible authentication, so you must set
<kbd>credentials='rest'</kbd> and <kbd>secret_key='SuperSecretPassword'</kbd> in the <strong>turn</strong> section of VROOM's <strong>settings.ini</strong>
</li>
</ul>
</div>
<h2 id="turn_start">
Enable and start turnserver
</h2>
<p>
You can now start and enable turnserver
<pre>
systemctl enable turnserver
systemctl start turnserver</pre>
</p>
<p>
You can check it's working with
<pre>
journalctl -fl -u turnserver.service</pre>
</p>
<div class="alert alert-warning">
Configuration of your firewall is out of scope for this doc, but you have to ensure the following ports are open:
<ul>
<li>TCP 3478, 3479, 5349, 5350 and 49152 to 65535</li>
<li>UDP 3478, 3479, 5349, 5350 and 49152 to 65535</li>
</ul>
If you use <strong>firewalld</strong> you can open the correct ports with the following commands
<pre>
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</pre>
</div>
<h1 id="etherpad">
Etherpad-Lite integration
</h1>
<p>
If you want to integrate VROOM with Etherpad-Lite, you'll have to get your instance running. First, install the dependencies
<pre>
yum groupinstall "Development Tools"</pre>
Then, Create a user, clone the repository and prepare the config
<pre>
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</pre>
</p>
<div class="alert alert-warning">
Adapt /opt/etherpad-lite/settings.json to your need. The important settings are
<ul>
<li><kbd>"requireSession" : true</kbd></li>
<li><kbd>"editOnly" : true</kbd></li>
<li><kbd>"requireAuthentication": false</kbd></li>
</ul>
</div>
<p>
Now, create a systemd unit
<pre>
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</pre>
And uncomment the corresponding lines in your httpd configuration (/etc/httpd/conf.d/vroom_alias.conf or /etc/httpd/conf.d/vroom_vhost.conf)
</p>
<h1 id="customize">
Customize
</h1>
<h2 id="moh">
Music on hold
</h2>
<p>
VROOM includes 5 different songs available as music on hold. If you want to add more,
just drop your files in <strong>public/snd/moh</strong>. When joining a room, VROOM will
randomly choose one file from this directory
</p>
<h2 id="appearence">
Appearence
</h2>
<p>
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
<pre>
cp -a /opt/vroom/templates/default /opt/vroom/templates/my_template</pre>
Then edit <strong>/opt/vroom/conf/settings.ini</strong> and set <kbd>template = 'my_template'</kbd>
Restart VROOM so the configuration change is applied
<pre>
systemctl restart vroom.service</pre>
And you can start modifying your template.
<div class="alert alert-danger">
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
</div>
<div class="alert alert-warning">
While working on your new template, it's recommanded to switch to the <strong>morbo</strong> backend as templates will be
reloaded automatically after each modification
</div>
</p>
</div>
</div>
</div>
%= include 'js_common'
<script>
$(document).ready(function() {
initDoc();
});
</script>
%= include 'footer'
