Poker Server Documentation

Poker Server Documentation and FAQ

The pokerserver software can be used in two different ways, as a client to connect to the benchmark server and play against the 2006 AAAI competitors, or as a server to run your bots in matches and tournaments of your own design. This documentation will cover both and be expanded in the future. If you want the quick version of how to get the server running, see Quickstart

Requirements

Windows XP
  • Java JDK 1.5 Download from Sun
  • cygwin (if you need to use tar files, or to run your own server/tournament, not to use the benchmark server)
Linux
  • Java JDK 1.5
Gentoo: emerge virtual/jdk
Ubuntu: apt-get install sun-java5-jdk
Other: Download from Sun and install

Testing your java installation
If java is installed properly, from a command prompt or cygwin terminal the command:

$ javac -version

should output javac 1.5.0_06(or similar) followed by the java compiler usage (your version of java may differ, but at least 1.5 is required). If it reports 1.4 you will need to update your java installation. If you get something like "Command not found" then see the troubleshooting section below for help setting your PATH environment variable so your system can find the java compiler.

QuickStart

Run your bot against randomclient or bots of your design (Windows)

  1. Install the Java SDK and cygwin 
  2. Download the poker server package from the competition website
  3. Expand the zip file to a directory
  4. Run compile.bat from within the directory you unzipped in step 3
  5. Place your bot in the directory bots/ and add an entry in windowslocal.prf for your bot (see below)
  6. Execute run.bat ( to capture the output in cygwin run: $./run.bat > output.txt 2> error.txt &)
  7. Cardfiles can be found in data/cards, results in data/results, logs in data/logs

Run your bot against randomclient or bots of your design (Linux)

  1. Install the Java SDK 1.5 or greater if not installed
  2. Download the poker server package from the competition website
  3. Unzip the file with $ unzip pokerserver2.x.y.zip
  4. Run compile.sh from within the directory you unzipped in step 3
  5. Place your bot in the directory bots/ and add an entry in linuxlocal.prf for your bot (see below).
  6. Execute run.sh
  7. Cardfiles can be found in data/cards, results in data/results, logs in data/logs

Run your bot against last years competitors (Benchmark Server), Windows

  1. Install the Java SDK and cygwin if you need to use tar files
  2. Download the poker server package from the competition website
  3. Expand the zip file to a directory
  4. Run compile.bat from within the directory you unzipped in step 3
  5. Place your bot in the directory bots/ and add an entry in graphicalalienclient.prf for your bot
  6. ./runGraphical.bat
  7. Create Matches and retrieve your results from the competition web server

Run your bot against last years competitors(Benchmark Server), Linux

  1. Install the Java SDK 1.5 or greater if not installed
  2. Download the poker server package from the competition website
  3. Unzip the file with $ unzip pokerserver2.x.y.zip
  4. Run compile.sh
  5. Under linux the example profile for the benchmark server is alienlinuxclient.prf. Edit this file for your system, changing YOURPATH to the path of your bots and expansion directories
  6. Run ./runGraphical.sh for the graphical applet or if you want to run from a command line:

    java -cp dist/pokerserver.jar ca.ualberta.cs.poker.free.alien.CLAlienClient alienlinuxclient.prf

    and follow the usage guide

    Note: if you are running from the command line you will need to specify the matches in alienlinuxclient.prf
  7. Create Matches and retrieve your results from the competition web server 
If compile.bat or compile.sh reports: Permission denied, run $ chmod a+x compile.sh to fix the permissions. The newest version has the right permissions but older copies may still have the wrong permissions.

$ ./runGraphical.bat will launch a java app that will connect to the server, allow you to login with your username and password, and create matches of the bots on your local machine, and bots from last year's competition. If you would like to use the poker server to run your own tournaments, against you own bots, see the next section. For help using the graphical client to create matches, see Help -> Help in the applications menu.


Running your own matches or tournament

On a single machine

If you wish to run single matches between bots, or a full fledged tournament, you need to define the matches you want to be run in the profile or connect to the server and create matches. The matches defined in a profile will run once the server starts, if you wish to create matches individually you will want to remove the tournament definition from the profile and connect to the server through a client and create the matches.

Profiles for running a tournament or series of matches are included with the software, and by default is setup to run matches between two randomclients.
Windows
The profile you will want to modify to your needs is: windowslocal.prf

Edit the line beginning with BotTarFile and change the definition to match that of your bot. The line above the definitions has descriptions of what each field represents. (lines beginning with # are ignored)
 

Unless you want two randomclient bots to play each other, you will want do add a definition for your own bot. Tar files and Jar files are supported. Make sure to properly specify <locationintarfile> to the directory which your startme.bat is in so the server can find your bot once it has expanded the archive.  

Eg. if your windows client,  compressed with tar into yourclient.tar, contains a directory yourclientV0.9/ then you will need to specify:

BotTarFile     yourclient   bots\yourclient.jar   yourclientV0.9\        WINDOWS           LOCALWINDOWS

Once you have the profile modified, the server can be started by running:  run.bat  from either the command line or through windows explorer. If you are using cygwin within windows you can redirect the output and error streams to files by:

[cygwin]$ ./run.bat > output.txt 2> error.txt &
Linux
The same applies to linux , the profile is linuxlocal.prf. The paths inside the profile should be absolute.
BotTarFile     yourclient   /usr/yourname/bots/yourclient.jar   yourclientV0.9/        LINUX           LOCALLINUX

The shell script: run.sh  will run the tournament specified in the profile. Including redirecting output an example command would be:

$ ./run.sh > output.txt 2> err.txt &

Distributed over many machines

Setting up your own tournament will allow you to use the server to run your matches in parallel on as many systems as you specify, or matches on your local machine if you don't have access to idle machines. The server has the capability to use remote machines, linux or windows, to run the matches for the tournament specified in a profile. The profile will list which machines can run certain bots, and a java class called the Forge will keep track of which machines are busy and will start the matches remotely. If you wish to use remote machines, the machine running the server must have password-less ssh keys setup so it can run commands on the remote machines without a password. This is not necessary if you plan on using on the local machine to run matches. The server has a notion of 'tokens', each token represents a match running at a given time, so if you computer can only handle running the server and one match (2 clients bots), then the token should be set to 1. It will then complete the match before starting new matches, and the machine will not be overwhelmed.

If you have access to computers to run clients for you, add a definition of each machine in the machine definition:
  
 # RemoteMachine <IP> <username> <expansionLocation> [WINDOWS|LINUX]

If the remote machine is running windows, you will need to install and setup a sshd server on the machine for the remote commands that launch the client to be accepted. An excellent tutorial on how to do this can be found here. Once that is done you will to have passwordless ssh access to each machine you wish to use. You will also want to make sure no firewall will block access to the server. Most modern firewall programs will allow you to specify a program which can open ports, you may have to specify the java binary as an application allowed to accept incoming connections. You will also need to open port 7000 if you use the port we have selected as the default port.

Example of a local machine:
LocalMachine 127.0.0.1 expansion\expansion1\ WINDOWS

Example of a remote windows machine
RemoteMachine 123.123.123.123 expansion\expansion1\ WINDOWS

Example of a remote linux machine
RemoteMachine 123.123.123.123 expansion\expansion2\ LINUX

To start the poker server you will run run.bat for windows, and run.sh for linux. Note that machines labeled as LOCALLINUX or LOCALWINDOWS will not be run remotely.


Bots

For the server to properly launch your bot, it must be launched from a script called startme.bat if it is a Windows bot, or a script called startme.sh if it is a Linux bot. To see example bots to modify look in trunk/examples in the poker server code.



Troubleshooting 

    I tried to login to the benchmark server but I do not have a username and password.

                    Refer to this page to find out how to get your login and password.


    Running compile.bat/compile.sh I get errors 

Windows
If your PATH does not contain the java compiler, you will get errors about the command javac not being found. This page explains how to edit the PATH variable in windows. Follow the direction and add C:\Program Files\jdk1.5.0_VERSION\bin,  (jdk1.5.0_X where X is the version of java you have installed, be sure to check) to your PATH,
and the compile should work properly once you relaunch your terminal/console application.
Cygwin
$ echo PATH =$PATH:/cygdrive/c/Program Files/Java/jdk1.5.0_VERSION\bin  >> ~/.bashrc
Linux
For linux you need to edit the file in your home directory called .bashrc, and add the directory containing the java executables to your path. For example, if your javac binary is /usr/bin/javac you would need to run: $ echo PATH =$PATH:/usr/bin  >> ~/.bashrc