406 lines
14 KiB
HTML
406 lines
14 KiB
HTML
|
<!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 3.0.0.
|
||
|
|
It is organized in 3 sections:
|
||
|
|
<ul>
|
||
|
|
<li>Requirements</li>
|
||
|
|
<li>Building and installing the library</li>
|
||
|
|
<li>Trying the examples (or your own Wt application)</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<a name="requirements"></a><h2>Requirements</h2>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The library provides two ways for deploying applications: either using
|
||
|
|
the FastCGI protocol, in conjunction with a webserver (like apache),
|
||
|
|
or using a built-in web server (wthttpd). You only need one of these,
|
||
|
|
but you can have both of them.</p>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The built-in web server is more convenient during development and is
|
||
|
|
easier to setup.</p>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The FastCGI based solution provides more flexibility for deployment of
|
||
|
|
the application. The built-in web server runs all sessions in a single
|
||
|
|
process, while the FastCGI based solution allows different deployment
|
||
|
|
schemes including dedicated processes per sessions.</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>
|
||
|
|
|
||
|
|
<h3>1 Wt requirements</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Compiler: gcc-3.3.4 or higher, or gcc-4.1.x or higher, or other
|
||
|
|
Ansi C++ compiler that can deal with boost-like C++ code.</li>
|
||
|
|
<li><a href="http://www.cmake.org/">CMake cross-platform build
|
||
|
|
system</a>:
|
||
|
|
<div>Preferably CMake 2.6, which comes with a usable script for
|
||
|
|
finding boost libraries, but CMake 2.4 is still supported using
|
||
|
|
Wt's own boost find script.
|
||
|
|
</div>
|
||
|
|
</li>
|
||
|
|
<li><a href="http://www.boost.org/">C++ boost library</a> (version
|
||
|
|
1.36 or higher), preferably with thread support enabled. You can
|
||
|
|
verify you have a thread-enabled boost installation by locating the
|
||
|
|
libboost_thread library. Thread support is not essential: Wt
|
||
|
|
functionality is not affected except for exotic things like server
|
||
|
|
push and reentrant event loops. Most importantly, even without
|
||
|
|
thread support Wt can handle multiple concurrent sessions.</li>
|
||
|
|
<li>Optionally, <a href="http://libharu.org/">Haru Free PDF Library</a>, which is used to provide support for painting to PDF (WPdfImage).</li>
|
||
|
|
<li>Optionally, <a href="http://www.graphicsmagick.org/">GraphicsMagick</a>, for supporting painting to raster images (PNG, GIF, ...) (WRasterImage).</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h4>1a Using FastCGI</h4>
|
||
|
|
|
||
|
|
<p>When using FastCGI, Wt requires a webserver (like apache, lighttpd or
|
||
|
|
nginx) which supports the FastCGI protocol.</p>
|
||
|
|
|
||
|
|
<p>Given that Apache is still the most popular webserver, below are
|
||
|
|
the requirements for apache, for other web servers the list is
|
||
|
|
similar:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>FCGI library, including C++ bindings (libfcgi++)</li>
|
||
|
|
<li>Fastcgi or mod_fcgi plugin for Apache.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h4>1b Using wthttpd</h4>
|
||
|
|
|
||
|
|
When using the built-in webserver, two more libraries may be installed
|
||
|
|
to enable optional features (you can also build without them), but
|
||
|
|
otherwise no extra dependencies are required.
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Optionally, libz, for compression over HTTP.</li>
|
||
|
|
<li>Optionally, openssl, for supporting HTTPS.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>2 Additional and optional requirements for some of the examples</h3>
|
||
|
|
<ul>
|
||
|
|
<li>libmysql++-2.x (hangman)</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 seperate build
|
||
|
|
directory, for example within the top-level of the Wt package:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
$ cd wt-x.xx
|
||
|
|
$ 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/kdforc0/project/wt/build
|
||
|
|
</pre></p>
|
||
|
|
|
||
|
|
<p>To build a multi-threaded version of Wt, which uses multiple
|
||
|
|
threads for handling concurrent requests, you need a thread-enabled
|
||
|
|
boost library. By default, CMake 2.6 will only search for a
|
||
|
|
thread-enabled boost installation, while CMake 2.4 will fall-back to a
|
||
|
|
non-multithreaded boost library, reporting:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
...
|
||
|
|
-- Looking for pthread_create in pthread - found
|
||
|
|
** Disabling multi threading.
|
||
|
|
...
|
||
|
|
</pre></p>
|
||
|
|
|
||
|
|
<p>Most linux distributions provide multi-threaded boost libraries by
|
||
|
|
default now.</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:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
$ ccmake .
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>Variables that you may set to configure Wt's built-in boost finding
|
||
|
|
method:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>BOOST_COMPILER</strong></dt>
|
||
|
|
<dd>The boost compiler signature. For a library
|
||
|
|
libboost_regex-gcc41-mt-1_37.so, this is 'gcc41'</dd>
|
||
|
|
<dt><strong>BOOST_VERSION</strong></dt>
|
||
|
|
<dd>The boost compiler signature. For a library
|
||
|
|
libboost_regex-gcc41-mt-1_37.so, this is '1_37'</dd>
|
||
|
|
<dt><strong>BOOST_DIR</strong></dt>
|
||
|
|
<dd>The boost installation directory. This is the directory where lib/
|
||
|
|
and include/ are located for your boost installation.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
Other variables specify several build and configuration aspects of Wt, of which
|
||
|
|
the most relevant ones are:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<dt><strong>HTTP_WITH_SSL</strong></dt>
|
||
|
|
<dd>Compile with support for SSL, for secure HTTP (HTTPS). This requires an OpenSSL library.</dd>
|
||
|
|
<dt><strong>HTTP_WITH_ZLIB</strong></dt>
|
||
|
|
<dd>Compile with support for compression over HTTP. This requires the
|
||
|
|
libz library.</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>
|
||
|
|
|
||
|
|
<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 third-party JavaScript libraries (ExtJS or TinyMCE).
|
||
|
|
<ul>
|
||
|
|
<li>Download ExtJS
|
||
|
|
from <a href="http://yogurtearl.com/ext-2.0.2.zip">http://yogurtearl.com/ext-2.0.2.zip</a>,
|
||
|
|
and install it according to these instructions:
|
||
|
|
<a href="http://www.webtoolkit.eu/wt/doc/reference/html/group__ext.html">http://www.webtoolkit.eu/wt/doc/reference/html/group__ext.html</a>
|
||
|
|
</li>
|
||
|
|
<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>ext/</tt> or
|
||
|
|
<tt>resources/tiny_mce/</tt> if you are missing these JavaScript
|
||
|
|
libraries.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<a name="examples-fastcgi"></a></a><h3>A. 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>
|
||
|
|
|
||
|
|
<a name="examples-wthttpd"></a><h3>B. 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-address 0.0.0.0 --http-port 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 (=10) number of threads
|
||
|
|
--servername arg (=vierwerf) servername (IP address or DNS name)
|
||
|
|
--docroot arg document root for static files
|
||
|
|
--errroot arg root for error pages
|
||
|
|
--accesslog arg access log file (defaults to stdout)
|
||
|
|
--no-compression do not compress dynamic text/html and text/plai
|
||
|
|
n responses
|
||
|
|
--deploy-path arg (=/) location for deployment
|
||
|
|
--session-id-prefix arg prefix for session-id's (overrides wt_config.xm
|
||
|
|
l setting)
|
||
|
|
-p [ --pid-file ] arg path to pid file (optional)
|
||
|
|
-c [ --config ] arg location of wt_config.xml. If unspecified,
|
||
|
|
WT_CONFIG_XML is searched in the environment,
|
||
|
|
if it does not exist then the compiled-in
|
||
|
|
default (/etc/wt/wt_config.xml) is tried. If
|
||
|
|
the default does not exist, we revert to
|
||
|
|
default values for all parameters.
|
||
|
|
--max-request-size arg Maximum size of a HTTP request. This also
|
||
|
|
limits POST requests, so this is an upper limit
|
||
|
|
for file uploads. Default is 40MB.
|
||
|
|
--max-memory-request-size arg Requests are usually read in memory before
|
||
|
|
being processed. To avoid DOS attacks where
|
||
|
|
large requests take up all RAM, use this
|
||
|
|
parameter to force requests that are larger
|
||
|
|
than the specified size to be spooled to disk.
|
||
|
|
This will also spool file uploads to disk.
|
||
|
|
--gdb do not shutdown when receiving Ctrl-C (and let
|
||
|
|
gdb break instead)
|
||
|
|
|
||
|
|
HTTP server options:
|
||
|
|
--http-address arg IPv4 (e.g. 0.0.0.0) or IPv6 Address (e.g. 0::0)
|
||
|
|
--http-port arg (=80) HTTP port (e.g. 80)
|
||
|
|
|
||
|
|
HTTPS server options:
|
||
|
|
--https-address arg IPv4 (e.g. 0.0.0.0) or IPv6 Address (e.g. 0::0)
|
||
|
|
--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"
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|