vroom/templates/default/documentation.html.ep

% 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.
        It's based on several other softwares, most notably the excellent <a href="http://simplewebrtc.com/" target="_blank">SimpleWebRTC</a> lib.
      </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>



      <h1 id="features">
        Features
      </h1>
      <p>
        VROOM implements the following features:
        <ul>
          <li>Video/audio conversations (no limit on the number of peers)</li>
          <li>Text chat (and you can save history)</li>
          <li>Screen sharing</li>
          <li>Email invitations</li>
          <li>Email notification 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 translated in French and English. You're welcome to submit patches or pull requests to enhance localization, or add new ones.
      </p>



      <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 server, 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_ws)</li>
          <li>The following perl modules
            <ul>
              <li>Mojolicious::Plugin::Mail</li>
              <li>Mojolicious::Plugin::Database</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>URI</li>
              <li>Protocol::SocketIO::Handshake</li>
              <li>Protocol::SocketIO::Message</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-info">
        VROOM can probably 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-info">
        While VROOM should run on any distro, it's only tested on CentOS 7 x86_64, so it's the recommended platform.
        Also, I provide packages for all dependencies in my repository, so it'll be much easier to install it this way.
        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-info">
        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 follwoing 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(Email::Valid)' \\
           'perl(Config::Simple)' 'perl(Session::Token)' 'perl(URI)'</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-info">
        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 virtualhost 
              (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-info">
        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) must be protected by your web server.
        VROOM provides no authentication at all. In the sample configuration, the access is restriucted to localhost, 
        but you can change this to anything you want
      </div>
      <p>
        You also have to make sure the <strong>mod_proxy_ws</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_ws.conf</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_signaling">
       signaling
      </h3>
      <p>
        This section is where you define your signaling server settings.
        This is because VROOM was using a modified <a href="https://github.com/andyet/signalmaster">SignalMaster</a>
        as signaling server, which could run on a separate server. Now, the signaling server is directly included in VROOM daemon
        so this section might be removed in the future
        <ul>
          <li><strong>uri</strong>: The uri to reach VROOM (/socket.io will be added to reach the SocketIO server)</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 use STUN and most likely TURN too. 
        <ul>
          <li><strong>stun_server</strong>: The STUN server to use. For example <kbd>stun_server = 'stun:stun.l.google.com:19302'</kbd>. 
          This must be a 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 to use (for now you can only define one, it should be possible to define
          several). For example <kbd>turn_server = 'turns:my-turn-server.net:5349?transport=tcp'</kbd>.
          This must be a full STUN URI as defined by <a href="https://tools.ietf.org/html/rfc7065" target="_blank">rfc7065</a></li>
          <li><strong>turn_user</strong> and <strong>turn_password</strong>: To use your TURN server, you'll most likely require credentials.
          You can either enter them here. If you let this empty, VROOM assumes that you're using
          <a href="https://code.google.com/p/rfc5766-turn-server/" target="_blank">rfc5766-turn-server</a> and will generate one user and password
          for each room. See the Configure rfc5766-turn-server section</li>
          <li><strong>realm</strong>: If you use rfc5766-turn-server with dynamic credentials, you must set here the realm configured in
          <strong>/etc/turnserver/turnserver.conf</strong>
        </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 seconds 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'd 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>template</strong>. The default, 
          and only tempalte provided is called <strong>default</strong>. But you can copy it and customize it to your taste</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 allow to capture screen 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_cookie">
        cookie
      </h3>
      <p>
        This section controls the cookie used for VROOM sessions. The available settings are
        <ul>
          <li><strong>secret</strong>: A secret passphrase to sign cookies. Must be changed !!!
          <li><strong>name</strong>: The name of the cookie. Default is <strong>vroom</strong></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 peer 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_logs">
        log
      </h3>
      <p>
        This section controls logging of the VROOM daemon. The following settings are available
        <ul>
          <li><strong>level</strong>: Set the logging level. Can be one of debug, info, warn, error or fatal</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 domaine 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_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>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 rfc5766-turn-server
      </h1>
      <p>
        You can run any TURN server you want, but VROOM integrates well with <a href="https://code.google.com/p/rfc5766-turn-server/" target="_blank">rfc5766-turn-server</a>.
        To make use of it, follow those steps
      </p>


      <h2 id="turn_download">
        Download turnserver
      </h2>
      <p>
        Download the latest version from <a href="http://turnserver.open-sys.org/downloads/">here</a> and extract the archive
      </p>
      <div class="alert alert-info">
        Only the 3.x branch is supported
      </div>


      <h2 id="turn_install">
        Install the RPMS
      </h2>
      <p>
        You can now install the extracted RPMS
        <pre>
yum localinstall turnserver-*/*.rpm</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
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</pre>
      </p>
      <div class="alert alert-info">
        <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>
        </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-info">
        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="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-info">
          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'