Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 325 lines (262 sloc) 12.428 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324
== 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
////////////////////////////////////////////////////////////////////////
Something went wrong with that request. Please try again.