This repository has been archived on 2025-02-12. You can view files and clone it, but cannot push or open issues or pull requests.
tinjac/wt-3.1.7a/INSTALL
2010-12-29 16:01:33 +00:00

336 lines
13 KiB
Text

Wt Installation instructions on Unix-like systems
This page lists the instructions for building and installing Wt 3.0.0.
It is organized in 3 sections:
* Requirements
* Building and installing the library
* Trying the examples (or your own Wt application)
Requirements
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.
The built-in web server is more convenient during development and is
easier to setup.
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.
Each of these two choices correspond to a library, a so-called
connector library. Below it is outlined how to configure the build
process of Wt to build either or both libraries (libwthttp and
libfcgi).
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.
1 Wt requirements
* 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.
* [1]CMake cross-platform build system:
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.
* [2]C++ boost library (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.
* Optionally, [3]Haru Free PDF Library, which is used to provide
support for painting to PDF (WPdfImage).
* Optionally, [4]GraphicsMagick, for supporting painting to raster
images (PNG, GIF, ...) (WRasterImage).
1a Using FastCGI
When using FastCGI, Wt requires a webserver (like apache, lighttpd or
nginx) which supports the FastCGI protocol.
Given that Apache is still the most popular webserver, below are the
requirements for apache, for other web servers the list is similar:
* FCGI library, including C++ bindings (libfcgi++)
* Fastcgi or mod_fcgi plugin for Apache.
1b Using wthttpd
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.
* Optionally, libz, for compression over HTTP.
* Optionally, openssl, for supporting HTTPS.
2 Additional and optional requirements for some of the examples
* libmysql++-2.x (hangman)
__________________________________________________________________
Building and installing the Wt library
1. Create a build directory
The recommended way to build the library is in a seperate build
directory, for example within the top-level of the Wt package:
$ cd wt-x.xx
$ mkdir build
$ cd build
2. Configure the library
$ cmake ../
The latter command will try to locate the necessary libraries. If
everything is OK, then this should end with something like:
-- Generating done
-- Build files have been written to: /home/kdforc0/project/wt/build
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:
...
-- Looking for pthread_create in pthread - found
** Disabling multi threading.
...
Most linux distributions provide multi-threaded boost libraries by
default now.
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 -Dvar=value or
using the interactive program:
$ ccmake .
Variables that you may set to configure Wt's built-in boost finding
method:
BOOST_COMPILER
The boost compiler signature. For a library
libboost_regex-gcc41-mt-1_37.so, this is 'gcc41'
BOOST_VERSION
The boost compiler signature. For a library
libboost_regex-gcc41-mt-1_37.so, this is '1_37'
BOOST_DIR
The boost installation directory. This is the directory where
lib/ and include/ are located for your boost installation.
Other variables specify several build and configuration aspects of Wt,
of which the most relevant ones are:
CMAKE_INSTALL_PREFIX
Installation prefix for the library and include files)
CONFIGDIR
Path for configuration files (default is /etc/wt/)
CONNECTOR_FCGI
Build the FastCGI connector (libwtfcgi) ?
CONNECTOR_HTTP
Build the stand-alone httpd connector (libwthttp) ?
EXAMPLES_CONNECTOR
Which connector library to use for the examples? (wthttp or
wtfcgi)
MULTI_THREADED
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.
The following variables apply to the FastCGI connector:
RUNDIR
Default location for Wt runtime session management (can be
overridden in the Configuration file)
WEBUSER
Webserver username: used to assign permissions to RUNDIR
WEBGROUP
Webserver groupname: used to assign permissions to RUNDIR
The following variables apply to the wthttpd connector:
WTHTTP_CONFIGURATION
Location of the wthttpd configuration file (default is
/etc/wt/wthttpd)
HTTP_WITH_SSL
Compile with support for SSL, for secure HTTP (HTTPS). This
requires an OpenSSL library.
HTTP_WITH_ZLIB
Compile with support for compression over HTTP. This requires
the libz library.
To change any entry, use [Enter]. To save and quit, do [c] followed by
[g].
3. Build the library
$ make
4. Install the library (as user with sufficient permissions):
$ make install
5. Get your LD_LIBRARY_PATH ok, if needed (mostly for FastCGI).
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).
Fix it by (as user with sufficient permissions):
$ ln -s /your/path/to/lib/libwt.so /usr/lib
$ ln -s /your/path/to/lib/libwtfcgi.so /usr/lib
__________________________________________________________________
Trying the examples (or your own Wt application)
Deploying an application is different when using FastCGI or the
built-in web server (wthttpd).
The examples that come with the library use the connector specified by
the build option EXAMPLES_CONNECTOR (see supra).
Some examples need third-party JavaScript libraries (ExtJS or TinyMCE).
* Download ExtJS from [5]http://yogurtearl.com/ext-2.0.2.zip, and
install it according to these instructions:
[6]http://www.webtoolkit.eu/wt/doc/reference/html/group__ext.html
* Download TinyMCE from [7]http://tinymce.moxiecode.com/ and install
its tiny_mce folder into the resources/ folder.
You will notice 404 File not Found errors for ext/ or
resources/tiny_mce/ if you are missing these JavaScript libraries.
A. Using FastCGI and apache
1. Build the examples
$ make -C examples
2. Deploy the example foobar
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).
$ export DESTINATION=/var/www/localhost/htdocs/wt-examples
$ mkdir -p $DESTINATION/foobar
$ cp -r examples/foobar/* resources/* build/examples/foobar/*.wt $DESTINATIO
N/foobar/
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.
3. Configure Apache
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.:
FastCgiServer /var/www/localhost/htdocs/wt-examples/composer/composer.wt
4. Restart apache
B. Using wthttpd
1. Build the examples
$ make -C examples
2. Running an example
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.
$ cd ../examples/foobar # source directory for example foobar
$ ln -s ../../resources . # include standard Wt resource files
$ ../../build/examples/foobar/foobar.wt --docroot . --http-address 0.0.0.0 -
-http-port 8080
This will start a httpd server listening on all local interfaces, on
port 8080, and you may browse the example at [8]http://127.0.0.1:8080/
You will notice 404 File not Found errors for resources/ files if you
are missing the resources files.
These are all the command-line options that are available:
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"
References
1. http://www.cmake.org/
2. http://www.boost.org/
3. http://libharu.org/
4. http://www.graphicsmagick.org/
5. http://yogurtearl.com/ext-2.0.2.zip
6. http://www.webtoolkit.eu/wt/doc/reference/html/group__ext.html
7. http://tinymce.moxiecode.com/
8. http://127.0.0.1:8080/