-
Notifications
You must be signed in to change notification settings - Fork 365
/
INSTALL.html
467 lines (383 loc) · 19.4 KB
/
INSTALL.html
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
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
</head>
<title>Wt Installation</title>
<body>
<h1>Wt Installation instructions on Unix-like systems</h1>
This page lists the instructions for building and installing Wt on
Unix-like systems (Linux, macOS, BSD,…). It is
organized in 3 sections:
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#build">Building and installing the library</a></li>
<li><a href="#examples">Trying the examples (or your own Wt application)</a></li>
</ul>
<a name="overview"></a><h2>Overview</h2>
<p>
The library provides two ways for deploying applications: either with
the built-in web server (recommended), or using FastCGI (legacy, and soon to be deprecated).</p>
<p>
The built-in web server is a simple HTTP and WebSockets server. It supports
all of Wt's features, and is simple to setup. This is the recommended way of
deploying a Wt application.</p>
<p>
FastCGI is also supported if necessary, but it does not support WebSockets.</p>
<p>
Each of these two choices correspond to a library, a
so-called <i>connector</i> library. Below it is outlined how to
configure the build process of Wt to build either or both libraries
(libwthttp and libfcgi).</p>
<p>
Thus, to build a Wt library with built-in web server you need to
link against libwt and libwthttp. To build a Wt library which acts as
a FastCGI process, you need to link against libwt and libfcgi.
</p>
<p>
The naming convention of the library puts the <i>d</i> suffix at the end if the library is built in
<i>Debug</i> mode, which is regulated through <strong>CMAKE_BUILD_TYPE</strong>. So for example the
normal wt library <i>libwt</i> will be called <i>libwtd</i>.
</p>
<h4>1a. Using wthttpd</h4>
When using the built-in web server, two more libraries may be installed
to enable optional features (you can also build without them), but
otherwise no extra dependencies are required. See the <a href="#optdep">Optional Dependencies</a>
for more information.
<ul>
<li>Optionally, zlib (libz), for compression over HTTP and WebSockets.</li>
<li>Optionally, OpenSSL (libopenssl), for HTTPS.</li>
</ul>
<h4>1b. Using FastCGI</h4>
<strong>Using FastCGI is discouraged, and a strong preference is given to the built-in HTTP library.
The FCGI library is likely to be deprecated soon.</strong>
<p>When using FastCGI, Wt requires a webserver (like Apache or
NGINX) which supports the FastCGI protocol.</p>
<p>To build wtfcgi, you need:</p>
<ul>
<li><a href="http://www.fastcgi.com/">FCGI library</a>, including C++
bindings (libfcgi++)</li>
<li>A suitable plugin for your web server.</li>
</ul>
<h3>2 Additional and optional requirements for some of the examples</h3>
<ul>
<li>Qt, for the libwtwithqt interoperability layer</li>
</ul>
<hr />
<a name="build"></a><h2>Building and installing the Wt library</h2>
<h4>1. Create a build directory</h4>
<p>The recommended way to build the library is in a separate build
directory, for example within the top level of the Wt package:</p>
<pre>
$ cd wt-x.x.x
$ mkdir build
$ cd build
</pre>
<h4>2. Configure the library</h4>
<pre>
$ cmake ../
</pre>
<p>The latter command will try to locate the necessary libraries. If everything
is OK, then this should end with something like:
<pre>
-- Generating done
-- Build files have been written to: /home/{username}/project/wt/build
</pre></p>
<p>If CMake fails, because it cannot resolve all dependencies, then you
may help CMake by setting some variables to help CMake locate the libraries.
This may be done on the command-line using -D<i>var</i>=<i>value</i> or
using the interactive program:</p>
<pre>
$ ccmake ../
</pre>
or
<pre>
$ cmake-gui ../
</pre>
<p>The GUI lists all variables that are configurable in Wt's build process.</p>
<p>The section <a href="#coredep">Core Dependencies</a> lists the minimal requirements that are necessary
to make Wt build. If you require more functionality, and will also be using optional features, you
will need to take the <a href="#optdep">Optional Dependencies</a> into account as well.</p>
<p>
The variables specify several build and configuration aspects of Wt, of which
the most relevant ones are (there are many more visible in the GUI):</p>
<dl>
<dt><strong>CMAKE_INSTALL_PREFIX</strong></dt>
<dd>Installation prefix for the library and include files)</dd>
<dt><strong>CONFIGDIR</strong></dt>
<dd>Path for configuration files (default is /etc/wt/)</dd>
<dt><strong>CONNECTOR_FCGI</strong></dt>
<dd>Build the FastCGI connector (libwtfcgi) ?</dd>
<dt><strong>CONNECTOR_HTTP</strong></dt>
<dd>Build the stand-alone httpd connector (libwthttp) ?</dd>
<dt><strong>EXAMPLES_CONNECTOR</strong></dt>
<dd>Which connector library to use for the examples? (wthttp or wtfcgi)</dd>
<dt><strong>MULTI_THREADED</strong></dt>
<dd>Build a multi-threaded wthttpd? While on by default, and
recommended, you may want to disable this for example if you suspect
threading problems. Note that recursive event loops (most notably when
using Dialog::exec()) are not possible without thread support.</dd>
</dl>
The following variables apply to the FastCGI connector:
<dl>
<dt><strong>RUNDIR</strong></dt>
<dd>Default location for Wt runtime session management (can be overridden in the Configuration file)</dd>
<dt><strong>WEBUSER</strong></dt>
<dd>Webserver username: used to assign permissions to RUNDIR</dd>
<dt><strong>WEBGROUP</strong></dt>
<dd>Webserver groupname: used to assign permissions to RUNDIR</dd>
</dl>
The following variables apply to the wthttpd connector:
<dl>
<dt><strong>WTHTTP_CONFIGURATION</strong></dt>
<dd>Location of the wthttpd configuration file (default is /etc/wt/wthttpd)</dd>
</dl>
To change any entry, use [Enter]. To save and quit, do [c] followed by [g].
</p>
<h4>3. Build the library</h4>
<pre>
$ make
</pre>
If you want to speed up compilation, you may want to use multiple threads (e.g. 4):
<pre>
$ make -j4
</pre>
<h4>4. Install the library (as user with sufficient permissions):</h4>
<pre>
$ make install
</pre>
<h4>5. Get your LD_LIBRARY_PATH ok, if needed (mostly for FastCGI).</h4>
<p>
If you did not install Wt in a directory (CMAKE_INSTALL_PREFIX) included
in the default linker dynamic library search path, then the web server will
not be able to start Wt programs (such as the examples).</p>
<p>
Fix it by (as user with sufficient permissions):
<pre>
$ ln -s /your/path/to/lib/libwt.so /usr/lib
$ ln -s /your/path/to/lib/libwtfcgi.so /usr/lib
</pre>
</p>
<hr />
<a name="examples"></a><h2>Trying the examples (or your own Wt application)</h2>
<p>Deploying an application is different when using FastCGI or the
built-in web server (wthttpd).</p>
<p>The examples that come with the library use the connector specified
by the build option EXAMPLES_CONNECTOR (see supra).</p>
<p>Some examples need TinyMCE:
<ul>
<li>Download TinyMCE
from <a href="http://tinymce.moxiecode.com/">http://tinymce.moxiecode.com/</a>
and install its <tt>tiny_mce</tt> folder into the resources/ folder.
</li>
</ul>
You will notice 404 File not Found errors for
<tt>resources/tiny_mce/</tt> if you are missing this library.
</p>
<a name="examples-wthttpd"></a><h3>A. Using wthttpd</h3>
<h4>1. Build the examples</h4>
<pre>
$ make -C examples
</pre>
<h4>2. Running an example</h4>
<p>
Most examples use additional files, such as message resource bundles,
which are not indicated with absolute path names. Therefore the
working directory should be the source directory for the example. A
similar argument goes for icons and the setting of the --docroot
variable. Since Wt 3.1.4, you can use the "approot" property to move
the additional files that should not be available to browsers outside
of the docroot.
</p>
<pre>
$ cd ../examples/<i>foobar</i> # source directory for example <i>foobar</i>
$ ln -s ../../resources . # include standard Wt resource files
$ ../../build/examples/<i>foobar</i>/<i>foobar</i>.wt --docroot . --http-listen 0.0.0.0:8080
</pre>
<p>
This will start a httpd server listening on all local interfaces, on
port 8080, and you may browse the example at <a
href="http://127.0.0.1:8080/">http://127.0.0.1:8080/</a></p>
<p>
You will notice 404 File not Found errors for resources/ files if you are
missing the resources files.
</p>
<p>
These are all the command-line options that are available:
<pre>
General options:
-h [ --help ] produce help message
-t [ --threads ] arg (=-1) number of threads (-1 indicates that
num_threads from wt_config.xml is to be
used, which defaults to 10)
--servername arg servername (IP address or DNS name)
--docroot arg document root for static files,
optionally followed by a
comma-separated list of paths with
static files (even if they are within a
deployment path), after a ';'
e.g. --docroot=".;/favicon.ico,/resourc
es,/style"
--resources-dir arg path to the Wt resources folder. By
default, Wt will look for its resources
in the resources subfolder of the
docroot (see --docroot). If a file is
not found in that resources folder,
this folder will be checked instead as
a fallback. If this option is omitted,
then Wt will not use a fallback
resources folder.
--approot arg application root for private support
files; if unspecified, the value of the
environment variable $WT_APP_ROOT is
used, or else the current working
directory
--errroot arg root for error pages
--accesslog arg access log file (defaults to stdout),
to disable access logging completely,
use --accesslog=-
--no-compression do not use compression
--deploy-path arg (=/) location for deployment
--session-id-prefix arg prefix for session IDs (overrides
wt_config.xml setting)
-p [ --pid-file ] arg path to pid file (optional)
-c [ --config ] arg location of wt_config.xml; if
unspecified, the value of the
environment variable $WT_CONFIG_XML is
used, or else the built-in default
(/etc/wt/wt_config.xml) is tried, or else
built-in defaults are used
--max-memory-request-size arg (=131072)
threshold for request size (bytes), for
spooling the entire request to disk, to
avoid DoS
--gdb do not shutdown when receiving Ctrl-C
(and let gdb break instead)
--static-cache-control Cache-Control header value for static
files (defaults to max-age=3600)
HTTP/WebSocket server options:
--http-listen arg address/port pair to listen on. If no
port is specified, 80 is used as the
default, e.g. 127.0.0.1:8080 will cause
the server to listen on port 8080 of
127.0.0.1 (localhost). For IPv6, use
square brackets, e.g. [::1]:8080 will
cause the server to listen on port 8080
of [::1] (localhost). This argument can
be repeated, e.g. --http-listen
0.0.0.0:8080 --http-listen [0::0]:8080
will cause the server to listen on port
8080 of all interfaces using IPv4 and
IPv6. You must specify this option or
--https-listen at least once. The older
style --http-address and
--https-address can also be used for
backwards compatibility. If a hostname
is provided instead of an IP address,
the server will listen on all of the
addresses (IPv4 and IPv6) that this
hostname resolves to.
--http-address arg IPv4 (e.g. 0.0.0.0) or IPv6 Address
(e.g. 0::0). You must specify either
--http-listen, --https-listen,
--http-address, or --https-address.
--http-port arg (=80) HTTP port (e.g. 80)
HTTPS/Secure WebSocket server options:
--https-listen arg address/port pair to listen on. If no
port is specified, 80 is used as the
default, e.g. 127.0.0.1:8080 will cause
the server to listen on port 8080 of
127.0.0.1 (localhost). For IPv6, use
square brackets, e.g. [::1]:8080 will
cause the server to listen on port 8080
of [::1] (localhost). This argument can
be repeated, e.g. --https-listen
0.0.0.0:8080 --https-listen [0::0]:8080
will cause the server to listen on port
8080 of all interfaces using IPv4 and
IPv6. If a hostname is provided instead
of an IP address, the server will
listen on all of the addresses (IPv4
and IPv6) that this hostname resolves
to.
--https-address arg IPv4 (e.g. 0.0.0.0) or IPv6 Address
(e.g. 0::0). You must specify either
--http-listen, --https-listen,
--http-address, or --https-address.
--https-port arg (=443) HTTPS port (e.g. 443)
--ssl-certificate arg SSL server certificate chain file
e.g. "/etc/ssl/certs/vsign1.pem"
--ssl-private-key arg SSL server private key file
e.g. "/etc/ssl/private/company.pem"
--ssl-tmp-dh arg File for temporary Diffie-Hellman
parameters
e.g. "/etc/ssl/dh512.pem"
--ssl-enable-v3 Switch on SSLv3 support (not
recommended; disabled by default)
--ssl-client-verification arg (=none) The verification mode for client
certificates.
This is either 'none', 'optional' or
'required'. When 'none', the server
will not request a client certificate.
When 'optional', the server will
request a certificate, but the client
does not have to supply one. With
'required', the connection will be
terminated if the client does not
provide a valid certificate.
--ssl-verify-depth arg (=1) Specifies the maximum length of the
server certificate chain.
--ssl-ca-certificates arg Path to a file containing the
concatenated trusted CA certificates,
which can be used to authenticate the
client. The file should contains a a
number of PEM-encoded certificates.
--ssl-cipherlist arg List of acceptable ciphers for SSL.
This list is passed as-is to the SSL
layer, so see openssl for the proper
syntax. When empty, the default
acceptable cipher list will be used.
Example cipher list string:
"TLSv1+HIGH:!SSLv2"
--ssl-prefer-server-ciphers arg (=0) By default, the client's preference is
used for determining the cipher that is
choosen during a SSL or TLS handshake.
By enabling this option, the server's
preference will be used.
</pre>
</p>
<a name="examples-fastcgi"></a></a><h3>B. Using FastCGI and apache</h3>
<h4>1. Build the examples</h4>
<pre>
$ make -C examples
</pre>
<h4>2. Deploy the example <i>foobar</i></h4>
<p>
The easiest way to deploy the examples is by copying the binary (from
your build directory) and the source directory (which contains the
images) and the resources/ into the same destination directory
somewhere in your Apache server (we no longer generate a ./deploy.sh
script that took care of some of this).
</p>
<pre>
$ export DESTINATION=/var/www/localhost/htdocs/wt-examples
$ mkdir -p $DESTINATION/<i>foobar</i>
$ cp -r examples/<i>foobar</i>/* resources/* build/examples/<i>foobar</i>/*.wt $DESTINATION/<i>foobar</i>/
</pre>
<p>
This does however make public also files (such as message resources
bundles, data files, etc...) that do not need to be served by your web
server. The clean way to deploy your own applications is to use the
"approot" property to deploy those files to a directory outside the
webserver's doc root.
</p>
<h4>3. Configure Apache</h4>
<p>
Treat the example as a mod_fastcgi application, by adding a line to
20_mod_fastcgi.conf in your Apache configuration modules.d/ directory, e.g.:
</p>
<pre>
FastCgiServer /var/www/localhost/htdocs/wt-examples/composer/composer.wt
</pre>
<h4>4. Restart apache</h4>
</body>
</html>