====== VROOM ======
{{odt>template:template_fws.odt}}

<note important>This page is obsolete. Please see the new documentation page instead here: https://vroom.fws.fr/documentation</note>

===== Intro =====

VROOM (short for **V**ideo **ROOM**) is a simple to use and opensource (MIT licence) video conferencing application. It's based on several other softwares, most notably the super [[http://simplewebrtc.com/|SimpleWebRTC]] lib.

===== Description =====

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 [[https://talky.io/|talky.io]], [[https://appear.in/|appear.in]], [[https://vline.com/|vLine.com]], most of them are even quite better and more polished than VROOM, but I've found none entirely opensource, so I started this project.

The two main goals of VROOM are:
  * Make a complete opensource solution so anyone can install their own instance
  * Use peer to peer to transfer sensible data when possible

<note important>
I'm in no way a developper. VROOM is the first lines of HTML/CSS/JS I ever wrote, so you might see horrors in it's code. In such a case, please, send a pull request :-)
</note>
===== Features =====

VROOM implements the following features:
  * Video/audio conversations
  * Text chat (and you can save history)
  * Screen sharing ((only available in Google Chrome for now))
  * Send email invitations
  * Make room persistent
  * Chairman functionnalities (mute/pause/kick other peers)
  * Multiple chairman per room
  * Password protected rooms (different passwords for access and chairman)
  * Music on hold
  * Be notified when someone join one of your room
  * Integrate with Etherpad-liste

VROOM is translated in french and english (but my english is approximative :-))
===== Demo =====

Better than a few screenshots, you can try it: https://vroom.fws.fr/ (no registration needed). The administration page isn't accessible on the demo, so here are a few screenshots:

{{ :projets:vroom_admin_list.png |The admin page lists all existing rooms}}

{{ :projets:vroom_admin_conf.png |For each room, you can adjust configuration, reset passwords etc...}}

{{ :projets:vroom_admin_del.png |You can also manually delete rooms}}
===== Compatibility/Requirement =====

No plugin needed, you just need a modern web browser which implements WebRTC. Mozilla Firefox (tested on Linux, Windows and Android), Google Chrome (tested on Linux, Windows and Android) or Opera (only tested on Windows) should work.

Google Chrome is for now the one which will provide the best experience (and the only one able to share your screen), but Mozilla Firefox also works great (and so does Opera as it uses the same engine as Google Chrome), so just use the one you prefer

===== Known issues =====

  * VROOM appearence isn't very polished. Please, contribute if you can
  * <del>Google Chrome is the only browser able to share your screen.</del>
  * Not all browsers are supported, including Internet Explorer and Safari. You'll have to wait for them to add WebRTC support
  * iOS won't work, because Apple hasn't implemented WebRTC support and forbid alternative web engine on their market
  * <del>You need recent versions (at least Firefox 28 or Google Chrome 33)</del> (this is not really an issue is it ? :-))
  * <del>Firefox on GNU/Linux sometime do not connect to other peers if they run on Windows (no matter which browser the other peers use). It seems to be a codec negociation issue. Firefox on Windows doesn't have this problem</del>
  * Screen sharing doesn't appear on the other peers screen from time to time. If it happens, just stop sharing and share again your screen, it should work
  * <del>Some notifications might be received twice when a peer share its screen (for example, when someone lock the room)</del>
  * <del>Text chat uses dataChannels to send message peer to peer. While this is good for privacy, it might not work with some browsers which doesn't handle dataChannels correctly (at least the current Firefox ESR, which is 24 doesn't establish dataChannels correctly)</del>
  * <del>Video is mandatory. Idealy, it should fallback to audio only if no webcam available, with a default image displayed instead of the video stream</del>

===== Roadmap =====
Here's a list of things I'd like to add:
  * Enhance the general look'n'feel
  * <del>More robust text chat</del> (Looks like browsers have a better dataChannel support now, add no issue for some time)
  * <del>Find a way to send chat history to new peers (as it's totally peer to peer without any central storage, we need a way to elect one of the peer and ask him the history. Maybe the one having the longuest history ?)</del>
  * <del>Display a nice message for unsupported browser explaining why it will not work</del>
  * <del>Display a warning for unknown browsers</del>
  * File sharing (something like sharefest would be great)
  * Record session to file (will need browser support first)
  * <del>Download chat history as text (or PDF? or HTML?)</del>

For a more up to date list (or if you want to add suggestions), take a look [[https://github.com/dani/vroom/issues|here]]
===== I want to contribute! =====
And you're welcome to ;-)

Just fork VROOM on [[https://github.com/dani/vroom|Github]] and start hacking, then, send pull request as usual.

One area where you can easily contribute is translation. VROOM is only available in french and english for now. If you want to translate it in another language, look at the directory **lib/Vroom/I18N/**. You'll find one file per language. Copy one of them, eg:

<code bash>
cd lib/Vroom/I18N
cp -a en.pm it.pm
</code>

Then, translate all the strings, and send the resulting file (either make a PR on github, or open a bug with the new file attached)
===== Installation =====
Installation is not really straight forward for now, but this guide will help you doing so on a CentOS 7 x86_64 box. If you're using another system, you'll have to adapt the instructions.

<note important>
I haven't started work on SELinux policies. For now, you need to disable SELinux for VROOM to work correctly, so edit /etc/selinux/config and set SELINUX=permissive
</note>

==== Get dependencies ====

You'll need to configure our repo to get some dependencies
<code bash>
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
</code>

<code bash>
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(Email::Valid)' \
           'perl(Config::Simple)' 'perl(Session::Token)' 'perl(URI)'
</code>
==== Clone the repo ====

VROOM will be installed in /opt/vroom, so, let's go

<code bash>
cd /opt
git clone https://github.com/dani/vroom.git
</code>

==== Configure ====

=== Setup MySQL/MariaDB ===

A database will be used to store rooms configuration, we must enable the server.
<code bash>
systemctl enable mariadb.service
systemctl start mariadb.service
</code>

Now, lets create a new database for VROOM

<code bash>
mysql -uroot
</code>
<code sql>
CREATE DATABASE `vroom` CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON `vroom`.* TO 'vroom'@'localhost' IDENTIFIED BY 'MySuperPassw0rd';
FLUSH PRIVILEGES;
</code>

Now that we have our MySQL database (and the credentials needed to access it), lets create the tables:

<code bash>
mysql -uroot vroom < /opt/vroom/docs/database/schema.mysql
</code>

=== Setup rfc5766-turn-server ===
The [[https://code.google.com/p/rfc5766-turn-server/|rfc-5766-turn-server]] will be used both as a [[http://en.wikipedia.org/wiki/STUN|STUN]] and a [[http://en.wikipedia.org/wiki/Traversal_Using_Relays_around_NAT|TURN]] server. If you intend to use VROOM only from your internal network, you do not need this, but if you want your instance to be reachable (and working ;-)) from anywhere, no matter which crazy firewalls are between your peers, you need to install it.

  * Grab the latest version from [[http://turnserver.open-sys.org/downloads/|here]]. At the time of writing, it's 3.2.5.5

<code bash>
cd /tmp
wget http://turnserver.open-sys.org/downloads/v3.2.5.5/turnserver-3.2.5.5-CentOS7-x86_64.tar.gz
tar xvzf turnserver-3.2.5.5-CentOS7-x86_64.tar.gz
yum localinstall turnserver-*/turnserver-*.rpm
</code>

this turnserver will use our database to check client credentials, so lets go:

<code bash>
mv /etc/turnserver/turnserver.conf /etc/turnserver/turnserver.conf.default
cat <<'EOF' > /etc/turnserver/turnserver.conf
mysql-userdb "host=localhost dbname=vroom user=vroom password=MySuperPassw0rd connect_timeout=5"
verbose
syslog
fingerprint
lt-cred-mech
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
EOF
</code>

<note important>
  * 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
</note>

Now, lets start and enable it

<code bash>
systemctl enable turnserver
systemctl start turnserver
</code>

You can check it's working with

<code bash>
journalctl -fl -u turnserver.service
</code>

<note important>
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

A quick note on how to open the correct port with firewalld:

<code bash>
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
</code>
</note>


=== Setup Apache ===
Two sample apache config are provided in the conf 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 virtualhost (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/

<code bash>
cp /opt/vroom/conf/httpd_alias.conf /etc/httpd/conf.d/vroom.conf
</code>

<note important>You'll probably want to check this configuration and adapt it to your need</note>

We also need to enable mod_proxy_ws:
<code bash>
echo "LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so" \
 > /etc/httpd/conf.modules.d/00-proxy_ws.conf
</code>

Once everything is OK, you just have to enable and start apache:
<code bash>
systemctl enable httpd
systemctl start httpd
</code>

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

<code bash>
cp /opt/vroom/conf/settings.ini.dist /opt/vroom/conf/settings.ini
</code>

And adapt it to your need. This file is quite small and contains comments, so you should find your way ;-)

<note important>
The **realm** key in **[turn]** section of the config file must match the realm setting in **/etc/turnserver/turnserver.conf**
</note>

Then, enable and start vroom daemon

<code bash>
cp /opt/vroom/docs/systemd/vroom.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable vroom
systemctl start vroom
</code>
==== Admin Interface ====
The admin interface is available on /admin. There's no internal authentication: you must configure apache to restrict access to this location if you don't want everyone to be able to manage your rooms. The default sample configuration will just restrict it to localhost, without auth. You can, and should configure a basic auth or similar (I use LemonLDAP::NG for this on the demo instance)

==== Etherpad-Lite integration ====
You don't have to run etherpad-lite on the same server as VROOM itself. The only requirement is that vroom can reach etherpad API. Here're the steps needed if you want to deploy etherpad-lite on the same box:

<code bash>
yum groupinstall "Development Tools"
</code>
<code bash>
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
</code>

<note important>Adapt /opt/etherpad-lite/settings.jhson to your need</note>

<code bash>
mysql
</code>
<code sql>
CREATE DATABASE etherpad;
GRANT ALL PRIVILEGES ON etherpad.* TO 'etherpad'@'localhost' IDENTIFIED BY 'ThisIsMySQLPassw0rd';
FLUSH PRIVILEGES;
</code>

Then edit **/opt/etherpad-lite/settings.json** and adapt it to your need, especially the DB settings.

Now, create a systemd unit:
<code bash>
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
</code>

And uncomment the corresponding lines in your httpd configuration