== link:index.html[Index] -> link:cookbook.html[Cookbook]
///////////////////////////////////////////////////////////////////
Last checked:
* Cherokee: 1.2.0
* WordPress 3.0.5
* 2011/02/23
///////////////////////////////////////////////////////////////////

Cookbook: Setting up WordPress
------------------------------

Setting up link:http://wordpress.org/[WordPress] with Cherokee is
really easy. This recipe describes the WordPress 3.0.5 installation,
which is the latest release at the time of writing.

There are two ways of installing WordPress: it can either be installed
as a new virtual server or be installed inside a directory of some of
the virtual servers that already exist. We will be documenting the
first scenario, as it is the most widely used.

You will need PHP support correctly configured in Cherokee, and PHP
with the MySQL module installed. The default configuration already
provides a valid PHP configuration for Cherokee if you have php-cgi
installed, but you can follow the appropriate recipe about
link:cookbook_php.html[setting up PHP] in case you don't have it
available for some reason.

Under these conditions, you could start WordPress's installation and you
would already be able to have your site up and running.

However, we can add several refinements to Cherokee's setting. Mainly:

. Forward all requests for www.example.net (or whatever domain is resolved
  to our machine) to example.net

. Set up an appropriate url rewrite configuration for WordPress, so
  you can enable permalinks.

. Serve directly as static content some specific file types and
  directories, avoiding any other file requests and eliminating this
  way any security risk related to vulnerable archives.


[[cherokee_vserver]]
Setting up WordPress as a new Virtual Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Default virtual server
^^^^^^^^^^^^^^^^^^^^^^

We're assuming we have the default configuration initially provided by
Cherokee Admin.

We will begin by cloning the default virtual server, just to keep the
default PHP configuration. Create a clone named `example.net`.

Then, we'll delete every erasable rule in the default virtual server
since we are going to use it to redirect every petition not matched by
the example.net virtual server. We will set the remaining one to be
managed by the `Redirection` handler, like this:


[cols="30%,30%,40%",options="header"]
|=====================================================
|Type     | Regular Expression | Redirection
|External | ^(.*)$             | http://example.net/$1
|=====================================================

This clears the first milestone. The remaining ones will be
accomplished by tweaking the `example.net` virtual server.


example.net
^^^^^^^^^^^

Remember to set up the `Document root` to `/var/www/wordpress`.

.Custom document root
image::media/images/cookbook_wp_example1.png[WP example.net]

Delete all the rules except `php` and `Default`. We're heading right
to the second milestone now.

As previously, we will manage the `Default` rule with the redirection
handler.

.Redirection handler
[cols="30%,30%,40%",options="header"]
|=====================================================
|Type     | Regular Expression | Redirection
|Internal | ^/(.*)$            | /index.php
|=====================================================

.Redirection handler
image::media/images/cookbook_wp_example2.png[WP example.net]

After this, most of the redirections will work. We'll set some more
rules to fine tune the rest of WordPress' features. Those will be
`Directory` type rules for the following directories: `wp-includes`,
`wp-content` and `wp-admin`. These are to be managed with the `List &
Send` handler.

The third milestone, directly serving static files, is an easy task to
accomplish. This step is not required by WordPress, but we will be
treating as static the contents of a couple of directories and the
sitemap files generated by our Google XML Sitemaps plugin of choice.

To do this, we will be creating `Directory` type rules for the
`images` and `static` directory, and a `Regular Expression` type rule
for the sitemap.

[cols="40%,60%",options="header"]
|=====================================================
|Type               | Value
|Directory          | /images
|Directory          | /static
|Regular Expression | /sitemap.xml.*
|=====================================================

Remeber to manage them with a handler that can serve files: `Static
content` and `List & Send`.

Almost any evaluation order of your rules will suffice, as long as the
one that handles the PHP files is the first one.

.Rule list
image::media/images/cookbook_wp_example3.png[WP example.net]


WARNING
^^^^^^^
Beware of the long time WordPress can need to get through the
installation. It doesn't seem to be an issue currently, but in the
past it has been known to exceed the timeout that Cherokee uses as
default, and while this will still sometimes allow for a complete
installation, it will most probably cause a failure while delivering
the last page of the process.

If you encounter this problem and absolutely need to see the last
screen, please increase your server's `timeout` value, under the
`Basic Behavior` paragraph of the `General` tab, and start over.

If you are going to attempt to make an installation as is, with no
reconfiguration of Cherokee whatsoever, you can skip right to the
section link:cookbook_wordpress.html#setting_up_wordpress[Setting up
WordPress].

WARNING
^^^^^^^
Beware of another possible break point. The last step in the
installation of WordPress used to involve mailing the details of the
new account to the provided email. Normally the process will be
painless: if the system is running an MTA, this report will be
sent. If not, it will simply skip this step. In both cases the
information will also be displayed on screen. However, there is a
corner case that might make your installation fail with old WordPress
versions: if the server is running a broken MTA, this could make PHP
fail when trying to deliver the email, in turn resulting in a failure
during the installation, and making Cherokee report an `Error
500`. Having a broken MTA on a production server is a very unlikely
scenario, but double check your MTA in case you receive this error.

[[wordpress]]
Setting up WordPress
~~~~~~~~~~~~~~~~~~~~

First download and uncompress the distributed WordPress release into
`/var/www/wordpress`, and create a database suitable for the installation.

Log in to MySQL:

----------------
mysql -u root -p
----------------

And create the database for WordPress. We will be using the name
'wp', the user 'wpuser' and the password 'wppassword', but
you should set up your own.

------------------------------------------------------------------------
CREATE DATABASE wp;
GRANT ALL PRIVILEGES ON wp.* TO wpuser@localhost IDENTIFIED BY 'wppassword';
GRANT ALL PRIVILEGES ON wp.* TO wpuser@localhost.localdomain IDENTIFIED BY 'wppassword';
FLUSH PRIVILEGES;
quit;
------------------------------------------------------------------------

Then point your web browser to `http://localhost` and follow the
instructions provided by the installer.

.WordPress installation site info
image::media/images/cookbook_wp1.png[WP installation]

And the installation will be automatic. Just fill up the
requested values and you will obtain the following results once your
are through.

.WordPress installation administrator info
image::media/images/cookbook_wp2.png[WP installation]

With that, you are done installing. Let's log in and make the last
adjustments.

.WordPress login
image::media/images/cookbook_wp3.png[WP admin]

Once we're logged, we can configure the way `permalinks` are
displayed. Just use the `Settings`->`Permalinks` menu, and adjust the
way the links are to be rewritten.

.Permalinks
image::media/images/cookbook_wp4.png[WP admin]

Remember to set up the plugins that are of interest for you, such as
the sitemap generator, in a fashion compatible with what you
configured in Cherokee.

And voilà! You have a WordPress installation working flawlessly with
Cherokee.

.WordPress in action
image::media/images/cookbook_wp5.png[WP in action]

////////////////////////////////////////////////////////////////////////
# Snippet under subdirectory
# 2010/09

vserver!1000!rule!1060!encoder!gzip = 1
vserver!1000!rule!1060!handler = fcgi
vserver!1000!rule!1060!handler!balancer = round_robin
vserver!1000!rule!1060!handler!balancer!source!1 = 1
vserver!1000!rule!1060!handler!error_handler = 1
vserver!1000!rule!1060!match = extensions
vserver!1000!rule!1060!match!extensions = php
vserver!1000!rule!1060!match!final = 0
vserver!1000!rule!1060!timeout = 30
vserver!1000!rule!1050!handler = redir
vserver!1000!rule!1050!handler!rewrite!1!regex = (.*)/
vserver!1000!rule!1050!handler!rewrite!1!show = 0
vserver!1000!rule!1050!handler!rewrite!1!substring = $1/index.php
vserver!1000!rule!1050!match = fullpath
vserver!1000!rule!1050!match!fullpath!1 = /blog/wp-admin/
vserver!1000!rule!1040!document_root = /var/www/wordpress
vserver!1000!rule!1040!match = directory
vserver!1000!rule!1040!match!directory = /blog
vserver!1000!rule!1040!match!final = 0
vserver!1000!rule!1030!handler = file
vserver!1000!rule!1030!handler!iocache = 1
vserver!1000!rule!1030!match = and
vserver!1000!rule!1030!match!final = 1
vserver!1000!rule!1030!match!left = directory
vserver!1000!rule!1030!match!left!directory = /blog
vserver!1000!rule!1030!match!right = exists
vserver!1000!rule!1030!match!right!iocache = 1
vserver!1000!rule!1030!match!right!match_any = 1
vserver!1000!rule!1030!match!right!match_index_files = 0
vserver!1000!rule!1030!match!right!match_only_files = 1
vserver!1000!rule!1020!handler = redir
vserver!1000!rule!1020!handler!rewrite!1!show = 0
vserver!1000!rule!1020!handler!rewrite!1!substring = /blog/index.php?/$1
vserver!1000!rule!1020!match = request
vserver!1000!rule!1020!match!request = /blog/(.+)

source!1!env!PHP_FCGI_CHILDREN = 5
source!1!env!PHP_FCGI_MAX_REQUESTS = 490
source!1!host = 127.0.0.1:47990
source!1!interpreter = /usr/bin/php-cgi -b 127.0.0.1:47990
source!1!nick = PHP Interpreter
source!1!type = interpreter
////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////
# VServer snippet
# 2010/09

vserver!1020!directory_index = index.php,index.html
vserver!1020!document_root = /var/www/wordpress
vserver!1020!nick = example.net
vserver!1020!rule!50!encoder!gzip = 1
vserver!1020!rule!50!handler = fcgi
vserver!1020!rule!50!handler!balancer = round_robin
vserver!1020!rule!50!handler!balancer!source!1 = 1
vserver!1020!rule!50!handler!error_handler = 1
vserver!1020!rule!50!match = extensions
vserver!1020!rule!50!match!extensions = php
vserver!1020!rule!50!match!final = 0
vserver!1020!rule!50!timeout = 30
vserver!1020!rule!40!encoder!deflate = 0
vserver!1020!rule!40!encoder!gzip = 0
vserver!1020!rule!40!expiration = time
vserver!1020!rule!40!expiration!time = 1h
vserver!1020!rule!40!handler = file
vserver!1020!rule!40!handler!iocache = 1
vserver!1020!rule!40!match = fullpath
vserver!1020!rule!40!match!fullpath!1 = /favicon.ico
vserver!1020!rule!40!match!fullpath!2 = /robots.txt
vserver!1020!rule!40!match!fullpath!3 = /crossdomain.xml
vserver!1020!rule!30!handler = redir
vserver!1020!rule!30!handler!rewrite!1!regex = (.*)/
vserver!1020!rule!30!handler!rewrite!1!show = 0
vserver!1020!rule!30!handler!rewrite!1!substring = $1/index.php
vserver!1020!rule!30!match = fullpath
vserver!1020!rule!30!match!fullpath!1 = /
vserver!1020!rule!30!match!fullpath!2 = /wp-admin/
vserver!1020!rule!20!handler = file
vserver!1020!rule!20!handler!iocache = 1
vserver!1020!rule!20!match = exists
vserver!1020!rule!20!match!iocache = 1
vserver!1020!rule!20!match!match_any = 1
vserver!1020!rule!20!match!match_only_files = 1
vserver!1020!rule!10!handler = redir
vserver!1020!rule!10!handler!rewrite!1!regex = /(.+)
vserver!1020!rule!10!handler!rewrite!1!show = 0
vserver!1020!rule!10!handler!rewrite!1!substring = /index.php?/$1
vserver!1020!rule!10!match = default

source!1!env!PHP_FCGI_CHILDREN = 5
source!1!env!PHP_FCGI_MAX_REQUESTS = 490
source!1!host = 127.0.0.1:47990
source!1!interpreter = /usr/bin/php-cgi -b 127.0.0.1:47990
source!1!nick = PHP Interpreter
source!1!type = interpreter
////////////////////////////////////////////////////////////////////////