README.md

   1 # XonStatDB
   2
   3 This is the source for the database underlying [XonStat][xonstat], the statistics application for the arena-style FPS [Xonotic][xonotic].
   4 All code herein is intended for the PostgreSQL database management server.
   5
   6 ## Clone
   7
   8 ```
   9 git clone git@gitlab.com:xonotic/xonstatdb.git
  10 ```
  11
  12 ## Prepare
  13
  14 Prepare the database by first creating the user that will own all of the objects in the database.
  15 You must run this as an administrator user in your cluster.
  16 See your operating system's guidelines for how this is set up on your system.
  17
  18     create user xonstat with password 'xonstat';
  19
  20    *Note: please change this password*
  21
  22 Or from the commandline:
  23
  24     # su - postgres  (as root)
  25     postgres$ createuser -P xonstat  (this will prompt you for the users password)
  26
  27 Next, create the database itself:
  28
  29     $ psql
  30     postgres=#
  31
  32     CREATE DATABASE xonstatdb
  33       WITH ENCODING='UTF8'
  34         OWNER=xonstat
  35         CONNECTION LIMIT=-1;
  36
  37 If you intend to use the `drop_and_load.shl` script in the scripts folder, you may want to give
  38 the application user superuser within the database. To do that you can use the following command:
  39
  40     postgres=# alter user xonstat with superuser;
  41
  42 When done, exit the psql prompt:
  43
  44     postgres=# \q
  45
  46 Next, as your regular system user, log into the newly created database
  47 using the user account you just created.
  48 Do this from the root directory of your project checkout.
  49
  50     $ psql -U xonstat xonstatdb
  51
  52 You might need to force postgres to not use ident, if you get an error
  53 like *Peer authentication failed for user "xonstat"*:
  54
  55     $ psql -h localhost -U xonstat xonstatdb
  56
  57
  58 Create the plpgsql language, if it doesn't exist:
  59
  60     CREATE LANGUAGE plpgsql;
  61
  62 ## Initialize
  63
  64 Initial schema setup and subsequent migrations for XonStatDB are handled using [goose][goose].
  65 You may want to familiarize yourself with that tool before proceeding.
  66 All migrations are located in the `migrations` directory of this repo, so a typical invocation will
  67 look like this:
  68
  69 ```
  70 goose -dir migrations postgres "user=xonstat host=localhost dbname=xonstatdb sslmode=disable password=$PASSWORD" up
  71 ```
  72
  73 That's it!
  74
  75 ## Maintenance Scripts
  76
  77 There are a few maintenance scripts that can be used
  78 once the database begins accumulating data. These can be found in
  79 the scripts subdirectory and are intended to be implemented as cron jobs.
  80
  81 A summary of what they do follows:
  82
  83 - refresh_*.sh: refreshes data in various materialized views
  84 - purge_anticheat_log.sh: prunes the anticheat signal data
  85
  86 An example crontab using these:
  87 ```
  88 # refresh the materialized views in xonstatdb
  89 00 07 * * * ~/bin/refresh_summary_stats.sh
  90 10 07 * * * ~/bin/refresh_active_players.sh
  91 15 07 * * * ~/bin/refresh_active_servers.sh
  92 20 07 * * * ~/bin/refresh_active_maps.sh
  93 25 07 * * * ~/bin/refresh_recent_game_stats.sh
  94
  95 # prune the anticheats
  96 20 08 * * * ~/bin/purge_anticheat_log.sh
  97 ```
  98
  99
 100
 101 [xonotic]: http://www.xonotic.org/
 102 [xonstat]: http://stats.xonotic.org/
 103 [goose]: https://github.com/pressly/goose
 104
 105 ----
 106
 107 Project is licensed GPLv3.