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
   connectory 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.
     * CMake cross-platform build system (www.cmake.org):
       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.
     * 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.

    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

     * libgd2 (style, mandelbrot)
     * 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

   DEPLOYROOT
          Path to deploy examples into -- if you want that.

   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 [1]http://yogurtearl.com/ext-2.0.2.zip, and
       install it according to these instructions:
       [2]http://www.webtoolkit.eu/wt/doc/reference/html/group__ext.html
     * Download TinyMCE from [3]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 X

    $ cd examples/X
    $ ./deploy.sh

    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. Run the example X

   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 (unless you
   use the ./deploy.sh script to deploy everything in a dedicated
   deployment directory). A similar argument goes for icons and the
   setting of the --docroot variable.
    $ cd ../examples/X # source directory for example X
    $ ln -s ../../resources . # include standard Wt resource files
    $ ../../build/examples/X/X.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 [4]http://127.0.0.1:8080/

   To make sure the web server has all auxiliary files (like images, CSS
   style sheets, and perhaps other things) in place for the web
   application, you could use the ./deploy.sh script to copy everything
   into a directory (see the cmake DEPLOYROOT variable)

   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/plain
                               responses
  --deploy-path arg (=/)       location for deployment
  --session-id-prefix arg      prefix for session-id's (overrides wt_config.xml
                               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.

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://yogurtearl.com/ext-2.0.2.zip
   2. http://www.webtoolkit.eu/wt/doc/reference/html/group__ext.html
   3. http://tinymce.moxiecode.com/
   4. http://127.0.0.1:8080/