# Standard Operating Procedures: Building and deploying the Game Server

Updated 2021-04-02.

Note: in this document, sections of importance for experiment designers (Aria, Ellise, Gary...) are in yellow. The rest is primarily of importance only to those who work with the server code.

## Maintaining and deploying server code and server data

The Game Server source code (including documentation web pages) and the experiment control files (read-only data) (CSV files which control the experiments) are handled as outlined in the chart below:

The chart includes the following locations:

- 1. The GitHub repository for the code is the place where the "master copy" of the server code is stored. The location is as follows: Rule-Game-server. If you need access to this project, send your Github account name to Vladimir, and ask to add you to the list of contributors.
- 2. Your work directory, for working on server code, on your home of office computer. You can create and modify code and data files on any computer which is convenient for you to use, such as your home or office computer. For illustration, let's assume that the place where you work on this project is `~/w2020`.
- 3. Your work directory on `sapir`. `Sapir` is just a Linux machine, and is as good as any place to work on editing more files. However, your work directory on sapir (let's assume it's also `~/w2020`) is a particularly important place, since from there you can deploy code and data to the server directory.
- 4. "live" code. The "running" Web Rule Game server's code is located in `/opt/tomcat/webapps/w2020`. You don't touch this directory directly, but deploy code there using the procedure outlioned in (c) below.
- 5. The GitHub repository for the data is the place where the "master copy" of the server's read-only data, i.e. the experiment control files, is stored. The location is as follows: Rule-Game-game-data (To see this page, you must be an authorized user at Lupyan Lab, and you must be currently logged in to GitHub. Otherwise, you'll just see Error 404. If you need access to this project, send your Github account name to Kevin, and ask to add you to the list of contributors.)
- 6. Your work directory, for working on server data on any computer. You can create and modify code and data files on any computer which is convenient for you to use, such as your home or office computer, or sapir. For illustration, let's assume that the place where you work on this project is `~/w2020`.
- 7. "Live" data. The "running" Web Rule Game server reads its experiment control files (read-only data) from CSV, TXT, and SVG files that are located under `/opt/tomcat/game-data`. In order to ensure that your files don't just disappear after a subsequent deployment, you should not edit data files directly in this directory.

Staff who work with the server code may carry out the following procedures:

- (a) Check out code. Before you start working on the server code, either on your home computer (2) or on sapir (3), you need to get the current version of the project's files from the GitHub server. You can do it as follows:

        cd ~/w2020
        mkdir game
        cd game
        git init
        git remote add origin https://github.com/vmenkov/Rule-Game-server.git
        git pull origin master

  Later, you can update the files in your working directory from the Github repository every now and then as follows:

        cd ~/w2020/game
        git pull origin master

  This is something you may want to do every time when you think that other team members may have checked in their updates. This will ensure that their updates will propagate to your working version, and will reduce the chance of edit conflicts.

  Besides `git`, there are various other command-line and visual client applications that work with Github (e.g. `svn`). If you use one of those, modify the above commands as appropriate for your client.
  Various subdirectories of `game` containing the following materials:

  - `game-data` - read-only data files (rule sets, experiment plans, etc). See the Data Guide for more info). Don't use this subdirectory -- it's superseded by a new, separate repository!.
  - `web` - documentation
  - `src` - server source code
- (b) Check in code. Once you have done some work in your working directory (either on your home computer (2) or on sapir (3)), you may want to send your updated files to the Github repository, so that you or other contributors can continue working with them on other machines. Do it as follows:
  1. If you have created any new files or directories, make sure that they are tracked by the version control. For example, if you have created a new document named `foo.html`, you can "register" them with the version control with

           cd ~/w2020/game
           git add web/foo.html

  2. Send all new and updated files to the Github repository:

           cd ~/w2020/game
           git commit -a
           git push origin

- (c) Deploy code to production server. If you have modified the server code and want to deploy it to the "live" production server, you can do it as follows:
  1. Make sure that the directory `/opt/ant/bin` has been added to your PATH on sapir (edit your `.cshrc`, `.login`, or what have you).
  2. Make sure that the working directory on sapir contains the current version of the code (it is current because you have either just modified it right here, or have pulled the current version from Github, as per (a)).
  3. Execute the following commands:

           cd ~/w2020/game
           ant clean javadoc war
           cp ../w2020.war /opt/tomcat/webapps

     The `ant` command above compiles the source code, and packs the compiled code, along with the documentation and third-party libraries, into a large file in WAR format. The `sudo cp` command above copies that WAR file to a directory from which the Apache Tomcat server will automatically pick it and deploy it to the server web application directory, updating all necessary files in `/opt/tomcat/webapps/w2020`. Your applications will then be visible at the web server, at a URL such as `http://localhost:8080/w2020/` or `http://sapir.psych.wisc.edu:7150/w2020/` (depending on what host you are deploying it at, and what port the Tomcat server on that host is using).
     If the `cp` command above fails because you don't have the right permissions, see the permissions section below; or, if you are very impatient, just repeat the command with `sudo`, i.e.

         sudo cp ../w2020.war /opt/tomcat/webapps

  Note that the above only deploys the code, but not the data; to deploy the data, use (d) below instead.
- (c') Deploy code to development server. Along with the main (production) web application, `w2020`, your Tomcat server can also run a development web applicatin, `w2020-dev`. To deploy your code as the development application, run `ant` with the target `war-dev`, rather than `war`. That will produce a differently-named WAR files, for you to install in the webapps directory:

        cd ~/w2020/game
        ant clean javadoc war-dev
        cp ../w2020-dev.war /opt/tomcat/webapps

Staff working with the experiment control files may carry out the following operations:

- (d) Check out the data. Before you start working on the server data, in the work directory (6), either on your home computer or on sapir, you need to get the current version of the project's files from the GitHub server. You can do it as follows:

        cd ~/w2020
        mkdir game-data
        cd game-data
        git init
        git remote add origin https://github.com/lupyanlab/Rule-Game-game-data.git
        git pull origin master

  Later, you can update the files in your working directory from the Github repository every now and then as follows:

        cd ~/w2020/game-data
        git pull origin master

  This is something you may want to do every time when you think that other team members may have checked in their updates. This will ensure that their updates will propagate to your working version, and will reduce the chance of edit conflicts.

  Besides `git`, there are various other command-line and visual client applications that work with Github (e.g. `svn`). If you use one of those, modify the above commands as appropriate for your client.
  Various subdirectories of `game-data` contain a variety of data files, as per the Data Guide.

- (e) Check in the data and automatically deploy them to the server. Once you have done some work in your working directory, you may want to send your updated files to the Github repository, so that you or other contributors can continue working with them on other machines. Do it as follows:
  1. If you have created any new files or directories, make sure that they are tracked by the version control. For example, if you have created a new experiment plan named `MyPlan` and the rule sets named `My-Rule-01.txt` thru `My-Rule-01.txt`, you can "register" them with the version control with

           cd ~/w2020/game-data
           git add trial-lists/MyPlan rules/My-Rule-*.txt

  2. Send all new and updated files to the Github repository:

           cd ~/w2020/game-data
           git commit -a
           git push origin

  Kevin has set up the repository in such a way when you check your local copy of the data (with `git push ...`), the data are immediately automatically deployed to the server. If you log in to sapir, go to `/opt/tomcat/game-data` and check the time stamp and ownership of a file you have recently added and pushed to the repository, you will see that it will have a recent time stamp, and will be owned by user `kmui`.

  If you have modified an existing trial list file or a rule set file that you have previously used in some episodes, you may want to clear the server tables, in order to force the Game Server to re-read and re-compile that file before you play with it again.

## Production server vs. development server

As discussed above ((c) vs. (c')), the two are implemented as two web apps within the same Tomcat server. Both presently (ver. 2.001) use the same data files and the same MySQL database. This normally should not cause problems, unless you make the kind of change (in dev vs prod) that requires a change in the database schema.

## File ownership and permissions

On a Linux system, every file and directory is owned by a specific user account, and is assigned to a specific UNIX user group. Most of the files under `/opt/tomcat/webapps` on sapir are owned by user `tomcat`, group `tomcat`, and it's a good idea to keep it this way, or as close to it as possible. Therefore, one of the two ways of copying your WAR file to that directory is encouraged.

### Being a member of group `tomcat`

Presently, most team members have been enrolled into the UNIX group `tomcat`. If you are one of those, then, when you log in to sapir, just type

    newgrp tomcat

and all your subsequent interactions with the system will be as a member of that group. So you should be able to copy files to `/opt/tomcat/webapps`, since that directory is group-writeable.

### Using `sudo`

If you have `sudo` rights, you of course can copy WAR files to the webapps directory using sudo. But if you do that, do a nice thing and change their ownership to `tomcat.tomcat` thereafter, so that they won't be in the way of other people:

    sudo cp ../w2020.war /opt/tomcat/webapps
    sudo chown tomcat.tomcat      /opt/tomcat/webapps/w2020.war

## Client code

The client (the TypeScript/React/JavaScript application that runs inside the web browser) has its own Github repository, Rule-Game. Kevin can provide more details on the deployment process.