Server Setup - adam-roth/matchbook GitHub Wiki
This page discusses how to configure and run your own matchbook server instance. Because everything is so much better when you have your own matchbook server instance.
Follow the instructions below to get your matchbook server up and running.
First, make sure you have the prerequisites installed for building and running the server:
- Java 6+
- Maven 2+
- MySQL 5+ (or any other database that JDBC supports)
Next, grab a copy of the code under '/match-server' and edit the 'pom.xml' file in the project root directory to configure your server options. At a minimum, you'll want to check the 'systemProperties' section, and the values of the following entries (note that if you have your own standalone Servlet container than you intend to deploy to, you can skip this step):
<au.com.suncoastpc.db.name>match_devel</au.com.suncoastpc.db.name>
<au.com.suncoastpc.server.hostname>localhost</au.com.suncoastpc.server.hostname>
<au.com.suncoastpc.server.port>8080</au.com.suncoastpc.server.port>The first option specifies the persistence unit, as defined in 'persistence.xml' that the server should use. More on that later.
The second option specifies the hostname that will be used for the server. For development purposes, 'localhost' is fine. Though obviously for an actual deployment you'll want to use your server's public hostname here.
And the third option specifies the port the server should run on. 8080 is the default value, though of course you can specify any port you wish.
Also check the 'properties' section that immediately follows the 'systemProperties' section, and ensure that the value of 'cargo.servlet.port' matches whatever value you have put for 'au.com.suncoastpc.server.port'.
The system properties defined in the default 'pom.xml' file are not the only options supported by matchbook. Here is a complete overview:
| Property Name | Description | Default Value |
|---|---|---|
| au.com.suncoastpc.db.name | The name of the persistence-unit that the server should use to access the database; persistence units are defined in 'persistence.xml'. | match_devel |
| au.com.suncoastpc.server.hostname | The hostname for this server; this is used when generating links in e-mails, etc. | localhost |
| au.com.suncoastpc.server.port | The port for this server; this is used when generating links in e-mails, and does not affect the port that the server actually binds to. | 8080 |
| au.com.suncoastpc.server.protocol | The protocol the server uses (HTTP, HTTPS, etc.); this is used when generating links in e-mails. | http |
| au.com.suncoastpc.server.email.local | A flag which indicates whether or not 'localhost' is a valid destination for outgoing SMTP messages (i.e. whether or not something like Postfix is running locally). | false |
| au.com.suncoastpc.server.email.admin | The e-mail address to use when sending outbound system e-mails. | [email protected] |
| au.com.suncoastpc.server.email.admin.name | The display name to use when sending outbound system e-mails. | Matchbook Admin |
| au.com.suncoastpc.profiling.enabled | A flag indicating whether or not performance information should be logged to the console. | true |
| au.com.suncoastpc.server.http.timeout | The HTTP session timeout to use, in minutes. | 120 |
Note that if you are using your own standalone servlet container, you will need to ensure that you set the desired values for the above system properties as part of your servlet container's startup scripts.
Once you have your system properties set up, you should confirm your database connection settings. To do this, open the 'src/webapp/WEB-INF/classes/META-INF/persistence.xml' file. This is where the persistence units are defined. There are two persistence units defined by default; 'match_prod' and 'match_devel'.
In any case, whether you use one of the predefined persistence units or add your own, you'll want to ensure that the dialect, driver class, and connection URL are all correct for your setup (the default settings assume a local MySQL database). You'll also want to update the database username and password as appropriate for your system.
Once you're happy with the settings in persistence XML, all you need to do is ensure a blank database exists with the specified name (so for MySQL, using the default database name, you simple need to run CREATE DATABASE matchmaking;).
Now you're ready to fire up the server! To do this simply run the provided 'startServer.sh' script (or 'startServer.bat' if you are on Windows). This will build the webapp, and deploy it to an embedded Tomcat instance using Cargo.
Alternately, if you are using a standalone servlet container, you can run 'mvn clean install' to build the webapp and then manually deploy the WAR file that is created under '/target' to your servlet container of choice.
Visit the running server in a web browser (by pointing your browser at http(s)://<hostname>:<port>; so http://localhost:8080 when using the default configuration options). Because this is the first visit to matchbook, you will be prompted to provide an admin password. Do so (and remember what password you pick, since you can't recover it if you lose it), and you will be logged in to the server.
Now all that's left to do is add a game so that you can get an API key to use in your mobile app(s). To do this, enter your application's identifier/bundle-id (i.e. something like 'com.<your company>.SuperAwesomeGame') and press the 'Add Game' button.
Your button-clicking skills will be rewarded with a private-key, which you can copy/paste into your native app(s), as discussed in the iOS and Android walkthroughs.