q3stats/README.rst

Q3Stats
=======

Stats for your CPMA server.

About
-----

Q3Stats is a Web application that allows you to import and analyze stats
generated by CPMA mod for Quake 3: Arena.

Features
--------

* Import game stats from XML files generated by CPMA,
* View dashboard with stats of the last session and the current month,
* View detailed session stats,
* View detailed stats of player's performance in a game,
* View aggregated player stats for sessions and maps.

Requirements
------------

* Unix-like OS (tested on OS X and Debian 8),
* PostgreSQL 9.5+,
* Development environment (compilers, headers, etc),
* Python 2.7 or 3.5+ with development headers,
* lxml2 with development headers,
* libxslt with development headers,
* libpq with development headers,
* SASS and Compass,
* imagemagick, wget and unzip for icons extraction script.

Project setup
-------------

To set up Q3Stats for please follow the guide below:

#. Install system requirements
#. Create a virtualenv: ``$ virtualenv q3stats``
#. Enter the virtualenv: ``$ cd q3stats && source bin/activate``
#. Clone the repository:
   ``(q3stats)$ git clone https://git.bthlabs.pl/tomekwojcik/q3stats.git``
#. Create the Alembic configuration file:
   ``(q3stats)$ cp q3stats/skel/alembic.ini .``
#. Edit the Alembic configuration file to suit your needs
#. Install the backend app requirements:
   ``(q3stats)$ pip install -r requirements-dev.txt``
#. Set up the frontend app: ``(q3stats)$ cd frontend && npm install``

**Extracting icons for items, weapons and powerups from CPMA resources**

To extract icons from CPMA PK3 file, use the following command:

.. sourcecode:: shell

  (q3stats)$ python utils/extract_icons.py <path_to_z-cpma-pak148.pk3>

If you omit the argument, the script will download CPMA and use the downloaded
file to extract required icons.

The extracted icons will be converted to PNG and placed in proper paths.

Developing Q3Stats
------------------

To set up Q3Stats for development please follow the additional steps:

#. Create the backend app configuration file:
   ``(q3stats)$ cp q3stats/skel/example.cfg development.cfg``
#. Create the testing configuration file:
   ``(q3stats)$ cp q3stats/skel/example.cfg testing.cfg``
#. Edit the configuration files to suit your needs
#. Run the database migrations: ``(q3stats)$ alembic upgrade head``

**Working with backend app**

You can develop the backend app like any other Flask Web app. To start the
development server, use the following command:

.. sourcecode:: shell

  (q3stats)$ python run_web_server.py

To run the test suite, use the following command:

.. sourcecode:: shell

  (q3stats)$ nosetests

**Working with frontend app**

The frontend app uses Grunt for building and development.

Use the following command to build development version of the app:

.. sourcecode:: shell

  (q3stats)frontend$ grunt dev

The built assets won't be minified and will contain proper source maps.

In development, it's handy to watch source files for changes. Q3Stats' build
system supports watching two classes of sources - JavaScript and SASS.

To start watching JavaScript sources for changes, use the following command:

.. sourcecode:: shell

  (q3stats)frontend$ grunt watch:js

To start watching SASS sources for changes, use the following command:

.. sourcecode:: shell

  (q3stats)frontend$ grunt watch:js

Production setup
----------------

To set up Q3Stats for production use please follow the additional steps:

#. Build production version of frontend app:
   ``(q3stats)frontend$ grunt dist``
#. Build sdist package: ``(q3stats)$ python setup.py sdist``
#. Generate database migration script:
   ``(q3stats)$ alembic upgrade --sql head >./prod_migration.sql``
#. Transfer the sdist package and migration script to your server,
#. Set up environment on the server according to requirements and your needs,
#. Install the sdist package,
#. Migrate database using the migration script,
#. (Re)start the application.

**Configuration file in production**

In order for Q3Stats app to start up it needs the configuration file. You can
use ``Q3STATS_CONFIG_FILE`` environment variable to pass path to your
configuration file.

**Tips on migrating the production database**

Alembic's *upgrade* command can be used to generate migration script
either for empty database (like in the guide above) or for upgrade of existing
database.

To generate upgrade script, use the following command:

.. sourcecode:: shell

  (q3stats)$ alembic upgrade --sql <version_num>:head> >./prod_upgrade.sql

You can obtain the *version_num* by running the following query on the
production database:

.. sourcecode:: shell

  $ psql -t -c "select version_num from alembic_version;" <database> 

Author, License and Attributions
--------------------------------

Q3Stats has been created and is developed by
`Tomek Wójcik <https://www.bthlabs.pl/>`_.

Q3Stats is licensed under the MIT License.

Q3Stats uses the following 3rd party code and resources:

* Bootstrap by Twitter, Inc. and The Bootstrap Authors (MIT),
* classnames by Jed Watson (MIT),
* Highcharts,
* React and ReactDOM by Facebook (BSD),
* react-bootstrap by Stephen J. Collings, Matthew Honnibal, Pieter Vanderwerff
  (MIT),
* redux and react-redux by Dan Abramov (MIT),
* react-router by Ryan Florence, Michael Jackson (MIT),
* underscore by Jeremy Ashkenas, DocumentCloud and Investigative
  Reporters & Editors (MIT).

**NOTE**: Q3Stats uses Highcharts. Please make sure you understand the licesing
terms of this library and purchase license if needed.
`Learn more <https://shop.highsoft.com/highcharts/#non-com>`_.