bill-auger
/
wt


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423
							<!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. It is
organized in 3 sections:

<ul>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#build">Building and installing</a> the library</li>
<li><a href="#examples">Trying the examples</a> (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. It also allows you to use WebSockets.</p>

<p>
The FastCGI based solution can be more convenient for deployment behind another
web server.</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> (preferably
  version 1.46.1 or higher), with or without thread support. 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. <br/>
  Older versions of boost, up until 1.36 are also supported, but some
  features will be disabled that depend on the revised versions of
  spirit, namely JSON parsing and improved SQL parsing (for Wt::Dbo).
</li>
<li>Optionally, <a href="http://www.openssl.org">OpenSSL</a>, which is
used to support the HTTPS protocol in the web client, and the HTTPS
protocol in the built-in wthttpd connector.</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>
<li>Optionally, <a href="http://www.posgresql.org/">PostgreSQL</a>,
for the PostgreSQL backend for Wt::Dbo (Dbo::backend::Postgres).</li>
<li>Optionally, <a href="http://www.firebirdsql.org/">Firebird</a>,
for the Firebird backend for Wt::Dbo (Dbo::backend::Firebird).</li>
<li>Optionally, <a href="http://www.pango.org/">Pango</a>, for
improved font support in the WPdfImage and WRasterImage paint
devices.</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><a href="http://www.fastcgi.com/">FCGI library</a>, including C++
bindings (libfcgi++)</li>
<li>A suitable plugin for your web server.</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, zlib (libz), for compression over HTTP.</li>
<li>Optionally, OpenSSL (libopenssl), for HTTPS.</li>
</ul>

<h3>2 Additional and optional requirements for some of the examples</h3>
<ul>
<li>Qt, for the libwtwithqt interopability 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 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>
or
<pre>
    $ cmake-gui ../
</pre>

<p>The GUI lists all variables that are configurable in Wt's build process.
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 (there are many more visible in the GUI):

<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>

<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>