-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathserver-setup.html
More file actions
291 lines (248 loc) · 14.2 KB
/
server-setup.html
File metadata and controls
291 lines (248 loc) · 14.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="author" content="Bastien Brunnenstein">
<link rel="icon" href="favicon.png">
<title>MwIssues - Server setup</title>
<!-- Bootstrap core CSS -->
<link href="css/bootstrap.min.css" rel="stylesheet">
<!-- Bootstrap theme -->
<link href="css/bootstrap-theme.min.css" rel="stylesheet">
<link href="css/mwissues.css" rel="stylesheet">
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body>
<!-- Fixed navbar -->
<nav class="navbar navbar-inverse navbar-static-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html"><i class="mwissues-logo"></i>MwIssues</a>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li><a href="index.html">Home</a></li>
<li class="dropdown active">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Documentation <span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="user-guide.html">User guide</a></li>
<li class="active"><a href="#">Server setup guide</a></li>
<li><a href="client-setup.html">Client setup guide</a></li>
<li><a href="troubleshooting.html">Troubleshooting</a></li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav navbar-right">
<li><a href="https://www.assetstore.unity3d.com/#!/content/62545">Asset store</a></li>
<li><a href="contact.html">Contact</a></li>
</ul>
</div><!--/.nav-collapse -->
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-3 col-md-push-9">
<h2>Navigation</h2>
<ul class="nav">
<li><a href="#setup-linux">Setup on Linux</a></li>
<li><a href="#setup-windows">Setup on Windows</a></li>
<li><a href="#testing">Testing</a></li>
<li><a href="#server-config">Server configuration</a></li>
<li><a href="#security">Increasing security</a></li>
</ul>
</div>
<div class="col-md-9 col-md-pull-3">
<div class="page-header">
<h1>Server setup guide</h1>
</div>
<p>
This page will guide you into running a server for MwIssues.<br>
The server code is free and open source, and can be found <a href="https://github.com/InfiniteRam/mwissues-nodejs-server">here on GitHub</a>.<br>
You can install the server before purchasing the editor extension.
</p>
<h3 id="setup-linux">Setup on Linux</h3>
<p>
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.<br>
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.
</p>
<p>
First, download and install the dependencies.<br>
If you didn't have MySql before, you will have to enter a password for the root account.
</p>
<pre>sudo apt-get update
sudo apt-get install git mysql-server mysql-client nodejs npm</pre>
<p>
Download the <a href="https://github.com/InfiniteRam/mwissues-nodejs-server">mwissues-nodejs-server</a> package from GitHub.<br>
</p>
<pre>git clone https://github.com/InfiniteRam/mwissues-nodejs-server.git
cd mwissues-nodejs-server</pre>
<p>
Now, run the installation script.<br>
Your MySql root account password will be asked. A new MySql user with a generated password will be created.
</p>
<pre>tools/install.sh</pre>
<p>
A service will be installed, the server will start automatically when the machine is turned on.<br>
<b>Important!</b> Take the time to consult the <a href="#server-config">Server configuration</a> section below.<br>
When you want to customize the configuration, edit the file <code>config.json</code> with your favorite text editor, then run the following command to restart the server.
</p>
<pre>sudo service mwissues restart</pre>
<h3 id="setup-windows">Setup on Windows</h3>
<p>
In this section, you will learn how to install MwIssues NodeJs server on a Windows machine.<br>
First, we have to manually download and install MySql and NodeJs.
</p>
<p>
Before installing any dependency, download the <a href="https://github.com/InfiniteRam/mwissues-nodejs-server">MwIssues server from Github</a>.<br>
You can either clone it using Git or download it as a Zip file.
</p>
<p>
For MySql, it is recommended to use the <a href="http://dev.mysql.com/downloads/installer/">MySql Installer</a>.
<ul>
<li>The only required component is MySql Server, but installing MySql Workbench is also recommended.</li>
<li>Choose a strong root password and store it in a secure place.</li>
<li>You should enable "Start the MySql Server at System Startup".</li>
</ul>
</p>
<p>
Once MySql is installed, we can create the database and the user.
</p>
<ul>
<li>Click on the <code>Create a new schema</code> button in the toolbar.</li>
<li>Enter the name <code>mwissues</code> and hit <code>Apply</code>.</li>
<li>Click on <code>File > Run Sql Script</code> and select the file <code>mwissues-nodejs-server/tools/issues-mysql.sql</code>.</li>
<li>Select <code>mwissues</code> in <code>Default Schema Name</code> and hit <code>Run</code>.</li>
</ul>
<p>
Now the database is ready, but we will also create a new MySql user that will only have access to the issues.
</p>
<ul>
<li>Select <code>Users and Privileges</code> in the sidebar and click <code>Add Account</code>.</li>
<li>Enter <code>mwissues</code> for the login name and <code>localhost</code> for <code>Limits to Hosts Matching</code>.</li>
<li>Choose a strong password different from the root password, and store it.</li>
<li>In the <code>Schema Privileges</code> tab, use <code>Add Entry</code> and select <code>mwissues</code> schema, then click on <code>Select ALL</code></li>
<li>Hit <code>Apply</code> to save your new user.</li>
</ul>
<p>
NodeJs is easy to install, download and run the Windows installer on the <a href="https://nodejs.org">NodeJs website</a>.<br>
You can choose either the latest or the LTS version.
</p>
<p>
With your preferred text editor, open <code>mwissues-nodejs-server/config.json</code> and enter the password of the MySql user <code>mwissues</code> in the <code>password</code> field.<br>
<b>Important!</b> Take the time to consult the <a href="#server-config">Server configuration</a> section below.
</p>
<p>
Open a command prompt in the folder <code>mwissues-nodejs-server</code> (you can shift + right click in the folder and choose <code>Open command window here</code>).<br>
Run the following command to download the dependencies.
</p>
<pre>npm update</pre>
<p>
Now the server is finally ready. You can start it using the following command.
</p>
<pre>node index.js</pre>
<p>
To ease your life, yous should configure Windows to run the server on System Startup, but this is not covered by this guide.<br>
When updating the <code>config.json</code> configuration file, remember that you must restart the server.
</p>
<h3 id="testing">Testing</h3>
<p>
To test your server, try to access to the web interface and login using a valid user name and API key.<br>
Enter the URL corresponding to your server in your browser:
</p>
<pre>http://server-address:port/
Example for local server: http://localhost:3000/</pre>
<p>
You should also try to access the server from a different machine to make sure that the server is accessible by your team members.
</p>
<h3 id="server-config">Server configuration</h3>
<p>
The server configuration can be modified by editing the <code>config.json</code> file. You have to restart the server after modifying this file.<br>
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.
</p>
<h4>Global options</h4>
<p>
<ul>
<li><code>port</code>: The port number the server is listening on. Default: 3000</li>
<li><code>maxScreenshotSize</code>: The maximum size of a single screenshot. Default: 5242880 (5MB)</li>
<li><code>deleteResolvedIssuesAfterDays</code>: Number of days after which resolved issues are automatically deleted. Default: 15. Set to -1 to disable</li>
</ul>
</p>
<h4>Database</h4>
<p>
For now, only the <code>mysql</code> database is supported. The MySql configuration is controlled by the <code>mysqlParams</code> table.
<ul>
<li><code>host</code>: The address of the MySql server. Default: "locahost"</li>
<li><code>port</code>: The port of the MySql server. Default: 3306</li>
<li><code>database</code>: The database that will be used. Default: "mwissues"</li>
<li><code>user</code>: The MySql user that will be used. Default: "mwissues"</li>
<li><code>password</code>: The password associated to this user.</li>
</ul>
For more MySql options, please consult the <a href="https://github.com/felixge/node-mysql">node-mysql</a> web page.
</p>
<h4>Authentication models</h4>
<p>
For now, only the <code>apikey</code> model is supported.<br>
The API key authenticator use the <code>apikeys</code> table to control the access.
</p>
<p>
In this table, keys are API keys (example: <code>facc74b2418cf6c5</code>) and values are permissions.<br>
Permissions are described by a table of strings (example: <code>["view", "create", "update"]</code>).<br>
Possible values are:
<ul>
<li><code>admin</code>: Administrator access. Administrators have all rights.</li>
<li><code>view</code>: Allowed to view the issue list and individual issues.</li>
<li><code>create</code>: Allowed to create new issues.</li>
<li><code>update</code>: Allowed to update existing issues.</li>
<li><code>delete</code>: Allowed to delete existing issues.</li>
</ul>
</p>
<p>
The special key <code>anonymous</code> can be used to give some permissions to anonymous users.
</p>
<p>
<b>Important!</b> 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.
</p>
<p>
You can configure API keys the way that suits you the best.<br>
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.
</p>
<h3 id="security">Increasing security</h3>
<p>
MwIssues aim to only be used internally by small teams, and so does not have a high level of security by default.<br>
If you need increased security, you can enable TLS to access the server through Https instead of Http.<br>
This is not supported by default, and explaining TLS is beyond the scope of this document, but the file <code>index.js</code> can easily be modified to use TLS. You can learn more by reading <a href="http://expressjs.com/en/advanced/best-practice-security.html">Express JS Security Best Practices</a>.
</p>
</div>
</div>
<hr>
<footer>
<p>Copyright © 2016 Bastien Brunnenstein</p>
</footer>
</div>
<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<!-- Include all compiled plugins (below), or include individual files as needed -->
<script src="js/bootstrap.min.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-77539542-2', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>