Navigation

Server setup guide

This page will guide you into running a server for MwIssues.
The server code is free and open source, and can be found here on GitHub.
You can install the server before purchasing the editor extension.

Setup on Linux

In this section, you will learn how to install MwIssues NodeJs server the easy way. I used a RaspberryPi with Debian, but it should be very similar for any other Linux distribution.
This is a very basic installation. You can also install everything yourself if you want more control, read the scripts to see the steps that have to be done.

First, download and install the dependencies.
If you didn't have MySql before, you will have to enter a password for the root account. 

sudo apt-get update
sudo apt-get install git mysql-server mysql-client nodejs npm

Download the mwissues-nodejs-server package from GitHub.

git clone https://github.com/InfiniteRam/mwissues-nodejs-server.git
cd mwissues-nodejs-server

Now, run the installation script.
Your MySql root account password will be asked. A new MySql user with a generated password will be created. 

tools/install.sh

A service will be installed, the server will start automatically when the machine is turned on.
Important! Take the time to consult the Server configuration section below.
When you want to customize the configuration, edit the file config.json with your favorite text editor, then run the following command to restart the server. 

sudo service mwissues restart

Setup on Windows

In this section, you will learn how to install MwIssues NodeJs server on a Windows machine.
First, we have to manually download and install MySql and NodeJs.

Before installing any dependency, download the MwIssues server from Github.
You can either clone it using Git or download it as a Zip file.

For MySql, it is recommended to use the MySql Installer.

  • The only required component is MySql Server, but installing MySql Workbench is also recommended.
  • Choose a strong root password and store it in a secure place.
  • You should enable "Start the MySql Server at System Startup".

Once MySql is installed, we can create the database and the user.

  • Click on the Create a new schema button in the toolbar.
  • Enter the name mwissues and hit Apply.
  • Click on File > Run Sql Script and select the file mwissues-nodejs-server/tools/issues-mysql.sql.
  • Select mwissues in Default Schema Name and hit Run.

Now the database is ready, but we will also create a new MySql user that will only have access to the issues.

  • Select Users and Privileges in the sidebar and click Add Account.
  • Enter mwissues for the login name and localhost for Limits to Hosts Matching.
  • Choose a strong password different from the root password, and store it.
  • In the Schema Privileges tab, use Add Entry and select mwissues schema, then click on Select ALL
  • Hit Apply to save your new user.

NodeJs is easy to install, download and run the Windows installer on the NodeJs website.
You can choose either the latest or the LTS version.

With your preferred text editor, open mwissues-nodejs-server/config.json and enter the password of the MySql user mwissues in the password field.
Important! Take the time to consult the Server configuration section below.

Open a command prompt in the folder mwissues-nodejs-server (you can shift + right click in the folder and choose Open command window here).
Run the following command to download the dependencies. 

npm update

Now the server is finally ready. You can start it using the following command. 

node index.js

To ease your life, yous should configure Windows to run the server on System Startup, but this is not covered by this guide.
When updating the config.json configuration file, remember that you must restart the server.

Testing

To test your server, try to access to the web interface and login using a valid user name and API key.
Enter the URL corresponding to your server in your browser: 

http://server-address:port/
Example for local server: http://localhost:3000/

You should also try to access the server from a different machine to make sure that the server is accessible by your team members.

Server configuration

The server configuration can be modified by editing the config.json file. You have to restart the server after modifying this file.
When installing a new server, the most important part is to edit the authentication parameters, you should never use the default API keys. Authentication models will be explained in this section.

Global options

  • port: The port number the server is listening on. Default: 3000
  • maxScreenshotSize: The maximum size of a single screenshot. Default: 5242880 (5MB)
  • deleteResolvedIssuesAfterDays: Number of days after which resolved issues are automatically deleted. Default: 15. Set to -1 to disable

Database

For now, only the mysql database is supported. The MySql configuration is controlled by the mysqlParams table.

  • host: The address of the MySql server. Default: "locahost"
  • port: The port of the MySql server. Default: 3306
  • database: The database that will be used. Default: "mwissues"
  • user: The MySql user that will be used. Default: "mwissues"
  • password: The password associated to this user.
For more MySql options, please consult the node-mysql web page.

Authentication models

For now, only the apikey model is supported.
The API key authenticator use the apikeys table to control the access.

In this table, keys are API keys (example: facc74b2418cf6c5) and values are permissions.
Permissions are described by a table of strings (example: ["view", "create", "update"]).
Possible values are:

  • admin: Administrator access. Administrators have all rights.
  • view: Allowed to view the issue list and individual issues.
  • create: Allowed to create new issues.
  • update: Allowed to update existing issues.
  • delete: Allowed to delete existing issues.

The special key anonymous can be used to give some permissions to anonymous users.

Important! API keys are not passwords, and as such they are not automatically encrypted. API keys should be generated and should not be re-used for another purpose. You should never use the default API keys either.

You can configure API keys the way that suits you the best.
For example, you can use one administrator key, one key shared by the development team with view, create and update access, and one key for the in-game reporter that can only create issues.

Increasing security

MwIssues aim to only be used internally by small teams, and so does not have a high level of security by default.
If you need increased security, you can enable TLS to access the server through Https instead of Http.
This is not supported by default, and explaining TLS is beyond the scope of this document, but the file index.js can easily be modified to use TLS. You can learn more by reading Express JS Security Best Practices.