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
• 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/RuleGame/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	     

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

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.