vroom/templates/default/documentation.html.ep

% title 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>
            P2P Audio/Video conversations (no limit on the number of peers per room)
          </li>
          <li>
            P2P text chat
          </li>
          <li>
            Screen or single windows sharing
          </li>
          <li>
            Send invitations by email
          </li>
          <li>
            Be notified 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>
        <a href="http://www.webrtc.org/"
           taget="_blank">
          WebRTC
        </a>
        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 peer to peer yet
          </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 directly between peers 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, restrictive 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="technologies">
        Technologies
      </h1>
      VROOM is composed of two distincts
      <ul>
        <li>
          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
            <a href="http://simplewebrtc.com/"
               target="_blank">
              SimpleWebRTC
            </a>
        </li>
        <li>
          The server side: mainly written in Perl using the fabulous
          <a href="http://mojolicio.us/"
             target="_blank">
            Mojolicious
          </a>
          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
        </li>
      </ul>

      <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 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>
                DBI
              </li>
              <li>
                DBD::mysql
              </li>
              <li>
                Mojolicious
              </li>
              <li>
                Mojolicious::Plugin::I18N
              </li>
              <li>
                Mojolicious::Plugin::Mail
              </li>
              <li>
                Mojolicious::Plugin::Database
              </li>
              <li>
                Mojolicious::Plugin::StaticCompressor
              </li>
              <li>
                Mojo::Redis2
              </li>
              <li>
                Crypt::SaltedHash
              </li>
              <li>
                MIME::Base64
              </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>
              <li>
                DateTime
              </li>
              <li>
                Array::Diff
              </li>
              <li>
                Locale::Maketext::Lexicon
              </li>
            </ul>
          </li>
          <li>
            The following perl modules are optional
            <ul>
              <li>
                For Etherpad-Lite support:
                <ul>
                  <li>
                    Etherpad
                  </li>
                </ul>
              </li>
              <li>
                To export events in a XLSX file
                <ul>
                  <li>
                    Mojolicious::Plugin::RenderFile
                  </li>
                  <li>
                    File::Temp
                  </li>
                  <li>
                    Excel::Writer::XLSX
                  </li>
                </ul>
              </li>
            </ul>
          </li>
        </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 reasons, 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 database engines (like PostgreSQL) with minor modifications.
        If you're interrested in adding support, 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 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(Email::Valid)' \\
            'perl(File::Temp)' \\
            'perl(Excel::Writer::XLSX)' \\
            'perl(Locale::Maketext::Lexicon)' \\
            'perl(Config::Simple)' \\
            'perl(Session::Token)' \\
            'perl(DateTime)' \\
            'perl(Data::Dumper)'</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_redis">
        Setup Redis
      </h3>
      <p>
        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:
        <pre>
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</pre>
      </p>

      <h3 id="c7_apache">
        Setup Apache
      </h3>
      <p>
        Two sample apache configurations are provided in the <strong>doc/httpd</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_dir_perm">
        Set permissions on the cache and tmp directories
      </h3>
      <p>
        The <strong>data</strong> directory must be writeable for the user running the VROOM daemon,
        which is <strong>vroom</strong> in the provided systemd unit
        <pre>
useradd -r -d /dev/null -s /sbin/nologin vroom
chown -R vroom ./data/
chmod 700 ./data/</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>
          <li>
            <strong>redis</strong>: The URI to reach your redis server. Exemple <kbd>redis://127.0.0.1:6379/0</kbd>
          </li>
          <div class="alert alert-danger">
            Be sure to specify the loopback address as <strong>127.0.0.1</strong> and not <strong>localhost</strong>
            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)
          </div>
        </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
                (defined in <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. This is of course the prefered method.
              </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
          </li>
        </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>
          <li>
            <strong>tmp</strong>: This is where VROOM will store temp data like XLSX files when exporting events
          </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 has only been tested with
        <a href="https://code.google.com/p/rfc5766-turn-server/"
           target="_blank">
          rfc5766-turn-server
        </a>
        and
        <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 templates.
        <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>


      <h1 id="admin_area">
        Admin area
      </h1>
      <p>
        The admin area is available on /vroom/admin or /admin
        (depending on how you have configured your web server). 
        <div class="alert alert-danger">
          Once again: There's no builtin auth mechanism, your web server must protect this URI
        </div>
        This page gives access to several sub menus to manage your VROOM instance
      </p>

      <h2 id="room_management">
        Room Management
      </h2>
      <p>
        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)
      </p>

      <h2 id="audit">
        Audit
      </h2>
      <p>
        This page is to consult audit logs. Every important event in VROOM is logged
        <ul>
          <li>
            On stdout (ideally captured by systemd's Journal or similar)
          </li>
          <li>
            In the audit table
          </li>
        </ul>
        Each event is composed of the following:
        <ul>
          <li>
            <strong>ID</strong>: It's just a unique ID for each event
          </li>
          <li>
            <strong>Date</strong>: the date and time of the event
          </li>
          <li>
            <strong>IP Address</strong>: The IP address of the user
          </li>
          <li>
            <strong>Event</strong>: The type of event (see below)
          </li>
          <li>
            <strong>User</strong>: The login of the user
          </li>
          <li>
            <strong>Message</strong>: A human readable information describing the event
          </li>
        </ul>
        <div class="alert alert-warning">
          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
        </div>

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

%= include 'js_common'
    <script>
      $(document).ready(function() {
        initDoc();
      });
    </script>
%= include 'footer'