336 lines
13 KiB
Text
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/
|