=========================================================
Queue-Tip
Copyright (c) 2008 Jayson Vaughn (vaughn.jayson@gmail.com)
Distributed under the terms of the GNU General Public License.
==========================================================

About
-----
Queue-Tip is an Asterisk Queue Monitoring and reporting tool
using ruby_ami and designed with the Ruby on Rails framework.

Features include:
  - Real-time, live view, of Asterisk queues updated seamlessly using Javascript 
  - Queue stats are collected in real-time using an AMI and DRb "proxy"
  - Load Asterisk's queue_log file into a database (local or from URI)
  - Run reports on agent and queue stats.  
  - Partition agents in to "groups" for reporting needs..
  - Export reports in csv format
  - Support for HA/failover setups containing multiple Asterisk servers


Requirements 
------------
In order to run Queue-Tip you will need:
  - ruby (>= 2.0) # 1.9.3 also works if you pin mime-types to 2.6.2
  - rubygems
  - rails (>= 4.1)
  - ruby_ami (>= 2.4.0)
  - fastercsv

If you want to load log files over something else than HTTP(S), you
can optionally install:
  - net-scp (>= 1.2.1)

Its uri/open-scp module will be loaded if it exists, which
transparently adds scp:// protocol support for log file locations.


Asterisk Manager Interface Setup
--------------------------------
Make sure that the Asterisk Manager Interface is enabled.
From the asterisk server:

  1) Open /etc/asterisk/manager.conf with an editor and set the following*:

      enabled = yes
      port = 5038   
      bindaddr = 192.168.1.25

    * Note: set bindaddr to the server's IP address.


  2) Create a user to access the Asterisk Manager Interface; insert toward the bottom of manager.conf*:

      [queuemanager]
      secret = secret420
      deny=0.0.0.0/0.0.0.0
      permit=192.168.1.0/255.255.255.0
      read = system,call,log,verbose,command,agent,user,config
      write = system,call,log,verbose,command,agent,user,config

    * Note: In the above example, 'queuemanager' is the username and 'secret420' is the password.


  3) You must reload the manager asterisk module by either restarting asterisk or 'module reload manager' from within the Asterisk CLI.  Refer to Asterisk documentation for further information.


Obtaining Queue-Tip
-------------------

You can obtain released packages of Queue-Tip from:

http://queue-tip.rubyforge.org

Git:
  
If you wish to obtain from github.com, run:

      $ git clone git://github.com/thedonvaughn/queue-tip.git

You can obtain the upstream source via git, run:
    
        $ git clone git://rubyists.com/gits/queue-tip.git
      

      
Installation
------------  
In order to have Queue-Tip load the queue_log file for reporting,
it's easiest to install Queue-Tip on the same server as Asterisk,
but you can also use scp (via the net-scp gem) or http to load the
log files.  This is the recommended approach if you have a multi-
server failover setup.

  1) Make sure you have the dependencies installed by running:
      
      $ bundle install (from within the Queue-Tip working directory) 
  
  2) Open up and edit bin/ami_proxy/config/asterisk.rb based on the Asterisk Manager Interface settings*: 

      AmiProxy::Asterisk.servers = [
        {
          :host => 'localhost',
          :port => 5038,
          :username => 'username',
          :password => 'secret',
          # If you want to override the default, put it here
          # :timeout => 10
          :queue_log_file => '/var/log/asterisk/queue_log'
          # :queue_log_file => 'http://pbx1.local/queue_log'
          # If the net-scp gem is installed, this works too:
          # :queue_log_file => 'scp://pbx1.local/var/log/asterisk/queue_log'
          # :queue_log_open_args => { :ssh => { :port => 2222 } }
        }
      ]


  3) Now you must start the Asterisk proxy; from within the Queue-Tip working directory issue

      $ bundle exec bin/ami_proxy.rb
        INFO: Registering Asterisk server localhost on port 5038
        INFO: Starting DRb server on druby://localhost:9050
 

  4) Next, like any Rails application, we need to create a database that Queue-Tip 
     can connect to and use.  In this setup, we will be using sqlite3* as our database.  
     This will require the ruby-sqlite3 rubygem.  To install ruby-sqlite3, run:

     $ sudo gem install -r ruby-sqlite3

     
     * Note: We can use mysql, postgresql, or oracle as our database.  
       Refer to the Ruby on Rails documentation for further information.

  
  5) Open up and edit config/database.yml to define the databases.  Here is our
     database definitons*.  Refer to Ruby on Rails documentation for more info.

      # SQLite version 3.x
      #   gem install sqlite3-ruby (not necessary on OS X Leopard)
      development:
        adapter: sqlite3
        database: db/development.sqlite3
        timeout: 5000

      # Warning: The database defined as "test" will be erased and
      # re-generated from your development database when you run "rake".
      # Do not set this db to the same as development or production.
      test:
        adapter: sqlite3
        database: db/test.sqlite3
        timeout: 5000

      production:
        adapter: sqlite3
        database: db/production.sqlite3
        timeout: 5000

  
  6) Create the database*, run:

      $ rake db:create

    * Note: By default in Ruby on Rails, you are in the 'development' environment.
            Refer to Ruby on Rails documentation for more info


  7) Populate the database*, run:

      $ rake db:migrate

    * Note:  By default you are in the development environment so this
             will populate the development database defined in 
             config/database.yml above.
  
  8) To start up Queue-Tip in development mode, run:
      
      $ bundle exec ./script/rails server

    This will start up Queue-Tip on port 3000.


  9) Open a web browser and connect to port 3000 of the server;  i.e.  http://192.168.1.25:3000. 
      Congratulations!  You are connected to Queue-Tip.

  10) To populate an initial database or reset the queue information,
      you can use the supplied rake task:

      $ bundle exec rake queue:reset

Support
-------
IRC: #queuetip on FreeNode
Forums/Bugs: http://rubyforge.org/projects/queue-tip/