Skip to content

Running the Runelite HTTP API Service

HERMETISM edited this page Jul 28, 2019 · 10 revisions

Why would I want to do this?

In order to work on the Runelite HTTP API and Service you're going to want to run a local copy on your machine so you can test the changes you make.

Installing Software

MySQL Server


We're going to need a copy of MySQL 5.7.22 installed on our dev machine to run the database the HTTP Service uses. Start by downloading the MySQL installer. Run the installer, agree to the license, and you should arrive at a screen like this:

The "Developer Default" preset includes more than we strictly need, but for the sake of simplicity we'll go with the default option. Click next, the installer may warn you if some of the subpackages require software you don't have installed. None of those should be things we need, so continue until you arrive at this screen (may look different if you downloaded the full installer instead of the smaller web installer):

Click "Execute" and the installer will begin downloading and installing the subpackages we have selected. Don't worry if some packages report there was an error, just wait for the others to finish installing and then click "Try again". Once everything is installed, click next until you arrive at this screen:

On this screen, we're going to choose the MySQL root password and create a user for Runelite to connect to the database with. The passwords can be whatever you like, just make sure to remember what you set them to. If you're planning to actually expose this server to the internet it's a good idea to follow the guide on securing the initial MySQL accounts in the official documentation. Once you've created the accounts, click next until the installer is finished.

Mac OS

Download version 5.7.22 of MySQL for Mac here. Follow the window on how to install, it's pretty simple to get it setup. When prompted set a password for this server, as this is just for testing purposes, I'd recommend just using a simple password for now.

If you didn't change the path of where to install MySQL then it will be located here /usr/local/. In this example, version 8.0.11 was installed and can be seen here:

$ /usr/local/mysql-8.0.11-macos10.13-x86_64

But for ease of mind, this is sym-linked to /usr/local/mysql.

To actually run MySQL you want to execute the following:

$ mysql -u root -p

Where you will be prompt to enter in the password you set up.

NB - If you get the command not found: mysql run the following:

$ echo PATH=${PATH}:/usr/local/mysql/bin >> ~/.bashrc

Once you're in MySQL, you want to then create another user for runelite.

mysql> CREATE USER 'runelite'@'localhost' IDENTIFIED BY 'another_password';
Query OK, 0 rows affected

Apache Tomcat 7


Next up is Tomcat, we'll install the Windows Service installer from the Tomcat project site. For this installer, just click next until it's finished.


You can download the .tar.gz file from the same website here. Once downloaded you can unpack it as such:

$ cd ~/Downloads ; tar xvf apache-tomcat-7.0.86.tar.gz ; mv apache-tomcat-7.0.86 ~/Applications

Once you've moved it in the ~/Applications folder, run the following to start up your apache tomcat, and head to localhost:8080 on your browser, and you should meet the following page (Once you've verified it's installed correctly stop the process as you'll configure it properly later).

$ ~/Applications/apache-tomcat-7.0.86/bin/ run

MySQL Connector/J

The JDBC driver that the HTTP Service will use to connect to our database. Download from the MySQL project website.

Theoretically this can be anywhere on the CLASSPATH environment variable but I had better luck simply putting it in C:\Program Files\Apache Software Foundation\Tomcat 7.0\lib\ (assuming a default Tomcat install).

Mac OS
When navigating to the above link, you want to select Platform Independent and download the .tar.gz version. Once downloaded, run the following:

$ cd ~/Downloads ; tar xvf mysql-connector-java-8.0.11.tar.gz ; mv mysql-connector-java-8.0.11 ~/ ; echo $CLASSPATH=${CLASSPATH}:/Users/richard/mysql-connector-java-8.0.11/mysql-connector-java-8.0.11.jar >> ~/.bashrc



Most of the MySQL configuration was taken care of in the installer, but there are a couple items left. Open up MySQL Workbench, create new databases named "runelite" and "runelite-cache", and make sure that the "runelite" user we created durning the install is able to modify it. The easiest way to do this is by copying and pasting the following SQL statements into the SQL file in the center of the window and clicking the lightning bolt to execute them. Make sure you substitute the password you chose earlier during the install.

create database runelite;
create database `runelite-cache2`;
create database `runelite-tracker`;
grant all on runelite.* to 'runelite'@'localhost' identified by '<PASSWORD_GOES_HERE>';
grant all on `runelite-cache2`.* to 'runelite'@'localhost' identified by '<PASSWORD_GOES_HERE>';
grant all on `runelite-tracker`.* to 'runelite'@'localhost' identified by '<PASSWORD_GOES_HERE>';
flush privileges;

We're done with MySQL until it's time to verify the database connection is working.


To start off, we'll be editing some configuration files located in the Tomcat installation directory.

Since these files are in C:\Program Files\ you'll need to launch your text editor with administrator permissions to modify the files, the installer defaults to C:\Program Files\Apache Software Foundation\Tomcat 7.0\conf\.

Mac OS
If following the above installation instructions, this will be located at

$ ~/Applications/apache-tomcat-7.0.86/conf

First up is context.xml, copy and paste the following into the <context><context/> tags. Don't forget to substitute your MySQL database user password!

<Resource name="jdbc/runelite" auth="Container" type="javax.sql.DataSource"
        maxTotal="50" maxIdle="30" maxWaitMillis="10000"
        username="runelite" password="<PASSWORD_GOES_HERE>"
        validationQuery="/* ping */"

<Resource name="jdbc/runelite-cache2" auth="Container" type="javax.sql.DataSource"
        maxTotal="50" maxIdle="30" maxWaitMillis="10000"
        username="runelite" password="<PASSWORD_GOES_HERE>"
        validationQuery="/* ping */"

<Resource name="jdbc/runelite-tracker" auth="Container" type="javax.sql.DataSource"
        maxTotal="50" maxIdle="30" maxWaitMillis="10000"
        username="runelite" password="<PASSWORD_GOES_HERE>"
        validationQuery="/* ping */"

<Environment name="oauth.client-id" value="moo" type="java.lang.String"/>
<Environment name="oauth.client-secret" value="moo" type="java.lang.String"/>
<Environment name="minio.endpoint" value="" type="java.lang.String"/>
<Environment name="minio.accesskey" value="AM54M27O4WZK65N6F8IP" type="java.lang.String"/>
<Environment name="minio.secretkey" value="/PZCxzmsJzwCHYlogcymuprniGCaaLUOET2n6yMP" type="java.lang.String"/>
<Environment name="minio.bucket" value="runelite" type="java.lang.String"/>
<Environment name="runelite.twitter.consumerkey" value="moo" type="java.lang.String"/>
<Environment name="runelite.twitter.secretkey" value="cow" type="java.lang.String"/>
<Environment name="runelite.twitter.listid" value="968949795153948673" type="java.lang.String"/>

Next up is tomcat-users.xml in the same folder. Copy and paste the following into the <tomcat-users><tomcat-users/> tags:

<user username="runelite" password="runelite" roles="manager-gui,admin-gui,manager-script"/>

Next, you'll want to start/restart the Tomcat service to reload its configuration. The easiest way to do this is by right-clicking on the Tomcat icon in the Taskbar. Once the service has been restarted you can navigate to http://localhost:8080 and you should see the Tomcat welcome page:

Click on the link to the "Manager app" and authenticate as "runelite" with password "runelite". This is the page that will allow you to deploy the HTTP Service .war file. Click on "Browse..." and select the .war file generated by compiling the http-service module (if you haven't done that yet you'll want to do that first):

Click deploy and if everything works correctly you should get a message saying so! If you get an error message, more troubleshooting data can be found in the Tomcat logs located in C:\Program Files\Apache Software Foundation\Tomcat 7.0\logs\.

You should be able to see the tables created in MySQL Workbench if you refresh the Schemas list and expand the runelite database:

You can also test making requests to your local instance with a request like http://localhost:8080/runelite-1.2.4-SNAPSHOT/hiscore?username=zezima (make sure you substitute the right version number for Runelite):

Configuring Runelite to use the local API

In order to test your changes to the HTTP Service module with the Runelite client, you'll need to change the base API URL. This is found in net.runelite.http.api.RuneliteAPI. For example:

Setting up OAuth support

In order to login to the client while using the local API you will need to create OAuth 2.0 credentials, add them to your Tomcat config, build and deploy the RuneLite OAuth Servlet, and update the http-service OAuth redirect url to reference localhost instead of

Creating OAuth 2.0 Credentials

Before we go any further we are going to create Google API credentials. See Setting up OAuth 2.0 or Using OAuth 2.0 to Access Google APIs for more information about OAuth 2.0.

Step 1) Visit and click the create credentials button

Step 2) Select the OAuth client ID option

Step 3) Select Web Application and add http://localhost:8080/oauth/ as a Redirect URI

Step 4) Create the credentials and copy the Client ID and Secret

Adding OAuth Credentials to Config

We need to edit the conf/context.xml file inside the folder you installed Tomcat Apache into. See Tomcat section for more information.

Once you are editing that file you need to replace the moo in both of these lines with the necessary values and save the file. Restart your server for the changes to take effect.

    <Environment name="oauth.client-id" value="moo" type="java.lang.String"/>
    <Environment name="oauth.client-secret" value="moo" type="java.lang.String"/>


    <Environment name="oauth.client-id" value="" type="java.lang.String"/>
    <Environment name="oauth.client-secret" value="sId2PfoPW4nJG9rv3Td5VI4P" type="java.lang.String"/>

Build and Deploy the OAuth Servlet

Download the RuneLite OAuth Servlet here:

Build the project using Maven with the install command line parameter set.

Deploy oauth.war if it wasn't automatically deployed. (Same method as deploying the snapshot.war file)

Update http-service OAuth Redirect URI

Navigate to the file inside the runelite project

Exact Path: http-service\src\main\java\net\runelite\http\service\account\

Update RL_OAUTH_URL to be http://localhost:8080/oauth/

Re-run maven on the project to rebuild the snapshot.war and then redeploy it to the server.

You should now be able to login to the client while running the local API.

Table of Contents

Clone this wiki locally
You can’t perform that action at this time.