README.rst 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183
  1. Q3Stats
  2. =======
  3. Stats for your CPMA server.
  4. About
  5. -----
  6. Q3Stats is a Web application that allows you to import and analyze stats
  7. generated by CPMA mod for Quake 3: Arena.
  8. Features
  9. --------
  10. * Import game stats from XML files generated by CPMA,
  11. * View dashboard with stats of the last session and the current month,
  12. * View detailed session stats,
  13. * View detailed stats of player's performance in a game,
  14. * View aggregated player stats for sessions and maps.
  15. Requirements
  16. ------------
  17. * Unix-like OS (tested on OS X and Debian 8),
  18. * PostgreSQL 9.5+,
  19. * Development environment (compilers, headers, etc),
  20. * Python 2.7 or 3.5+ with development headers,
  21. * lxml2 with development headers,
  22. * libxslt with development headers,
  23. * libpq with development headers,
  24. * SASS and Compass,
  25. * imagemagick, wget and unzip for icons extraction script.
  26. Project setup
  27. -------------
  28. To set up Q3Stats for please follow the guide below:
  29. #. Install system requirements
  30. #. Create a virtualenv: ``$ virtualenv q3stats``
  31. #. Enter the virtualenv: ``$ cd q3stats && source bin/activate``
  32. #. Clone the repository:
  33. ``(q3stats)$ git clone https://git.bthlabs.pl/tomekwojcik/q3stats.git``
  34. #. Create the Alembic configuration file:
  35. ``(q3stats)$ cp q3stats/skel/alembic.ini .``
  36. #. Edit the Alembic configuration file to suit your needs
  37. #. Install the backend app requirements:
  38. ``(q3stats)$ pip install -r requirements-dev.txt``
  39. #. Set up the frontend app: ``(q3stats)$ cd frontend && npm install``
  40. **Extracting icons for items, weapons and powerups from CPMA resources**
  41. To extract icons from CPMA PK3 file, use the following command:
  42. .. sourcecode:: shell
  43. (q3stats)$ python utils/extract_icons.py <path_to_z-cpma-pak148.pk3>
  44. If you omit the argument, the script will download CPMA and use the downloaded
  45. file to extract required icons.
  46. The extracted icons will be converted to PNG and placed in proper paths.
  47. Developing Q3Stats
  48. ------------------
  49. To set up Q3Stats for development please follow the additional steps:
  50. #. Create the backend app configuration file:
  51. ``(q3stats)$ cp q3stats/skel/example.cfg development.cfg``
  52. #. Create the testing configuration file:
  53. ``(q3stats)$ cp q3stats/skel/example.cfg testing.cfg``
  54. #. Edit the configuration files to suit your needs
  55. #. Run the database migrations: ``(q3stats)$ alembic upgrade head``
  56. **Working with backend app**
  57. You can develop the backend app like any other Flask Web app. To start the
  58. development server, use the following command:
  59. .. sourcecode:: shell
  60. (q3stats)$ python run_web_server.py
  61. To run the test suite, use the following command:
  62. .. sourcecode:: shell
  63. (q3stats)$ nosetests
  64. **Working with frontend app**
  65. The frontend app uses Grunt for building and development.
  66. Use the following command to build development version of the app:
  67. .. sourcecode:: shell
  68. (q3stats)frontend$ grunt dev
  69. The built assets won't be minified and will contain proper source maps.
  70. In development, it's handy to watch source files for changes. Q3Stats' build
  71. system supports watching two classes of sources - JavaScript and SASS.
  72. To start watching JavaScript sources for changes, use the following command:
  73. .. sourcecode:: shell
  74. (q3stats)frontend$ grunt watch:js
  75. To start watching SASS sources for changes, use the following command:
  76. .. sourcecode:: shell
  77. (q3stats)frontend$ grunt watch:js
  78. Production setup
  79. ----------------
  80. To set up Q3Stats for production use please follow the additional steps:
  81. #. Build production version of frontend app:
  82. ``(q3stats)frontend$ grunt dist``
  83. #. Build sdist package: ``(q3stats)$ python setup.py sdist``
  84. #. Generate database migration script:
  85. ``(q3stats)$ alembic upgrade --sql head >./prod_migration.sql``
  86. #. Transfer the sdist package and migration script to your server,
  87. #. Set up environment on the server according to requirements and your needs,
  88. #. Install the sdist package,
  89. #. Migrate database using the migration script,
  90. #. (Re)start the application.
  91. **Configuration file in production**
  92. In order for Q3Stats app to start up it needs the configuration file. You can
  93. use ``Q3STATS_CONFIG_FILE`` environment variable to pass path to your
  94. configuration file.
  95. **Tips on migrating the production database**
  96. Alembic's *upgrade* command can be used to generate migration script
  97. either for empty database (like in the guide above) or for upgrade of existing
  98. database.
  99. To generate upgrade script, use the following command:
  100. .. sourcecode:: shell
  101. (q3stats)$ alembic upgrade --sql <version_num>:head> >./prod_upgrade.sql
  102. You can obtain the *version_num* by running the following query on the
  103. production database:
  104. .. sourcecode:: shell
  105. $ psql -t -c "select version_num from alembic_version;" <database>
  106. Author, License and Attributions
  107. --------------------------------
  108. Q3Stats has been created and is developed by
  109. `Tomek Wójcik <https://www.bthlabs.pl/>`_.
  110. Q3Stats is licensed under the MIT License.
  111. Q3Stats uses the following 3rd party code and resources:
  112. * Bootstrap by Twitter, Inc. and The Bootstrap Authors (MIT),
  113. * classnames by Jed Watson (MIT),
  114. * Highcharts,
  115. * React and ReactDOM by Facebook (BSD),
  116. * react-bootstrap by Stephen J. Collings, Matthew Honnibal, Pieter Vanderwerff
  117. (MIT),
  118. * redux and react-redux by Dan Abramov (MIT),
  119. * react-router by Ryan Florence, Michael Jackson (MIT),
  120. * underscore by Jeremy Ashkenas, DocumentCloud and Investigative
  121. Reporters & Editors (MIT).
  122. **NOTE**: Q3Stats uses Highcharts. Please make sure you understand the licesing
  123. terms of this library and purchase license if needed.
  124. `Learn more <https://shop.highsoft.com/highcharts/#non-com>`_.