<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Language" content="en-us" />
<meta name="ROBOTS" content="ALL" />
<meta http-equiv="imagetoolbar" content="no" />
<meta name="MSSmartTagsPreventParsing" content="true" />
<meta name="Keywords" content="cherokee web server httpd http" />
<meta name="Description" content="Cherokee is a flexible, very fast, lightweight Web server. It is implemented entirely in C, and has no dependencies beyond a standard C library. It is embeddable and extensible with plug-ins. It supports on-the-fly configuration by reading files or strings, TLS/SSL (via GNUTLS or OpenSSL), virtual hosts, authentication, cache friendly features, PHP, custom error management, and much more." />
<link href="media/css/cherokee_doc.css" rel="stylesheet" type="text/css" media="all" />
</head>
<body>
<h2 id="_a_href_index_html_index_a_8594_a_href_cookbook_html_cookbook_a"><a href="index.html">Index</a> → <a href="cookbook.html">Cookbook</a></h2>
<div class="sectionbody">
</div>
<h2 id="_cookbook_setting_up_wordpress">Cookbook: Setting up WordPress</h2>
<div class="sectionbody">
<div class="paragraph"><p>Setting up <a href="http://wordpress.org/">WordPress</a> with Cherokee is
really easy. This recipe describes the WordPress 3.0.5 installation,
which is the latest release at the time of writing.</p></div>
<div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>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
<a href="cookbook_php.html">setting up PHP</a> in case you don’t have it
available for some reason.</p></div>
<div class="paragraph"><p>Under these conditions, you could start WordPress’s installation and you
would already be able to have your site up and running.</p></div>
<div class="paragraph"><p>However, we can add several refinements to Cherokee’s setting. Mainly:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Forward all requests for www.example.net (or whatever domain is resolved
to our machine) to example.net
</p>
</li>
<li>
<p>
Set up an appropriate url rewrite configuration for WordPress, so
you can enable permalinks.
</p>
</li>
<li>
<p>
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.
</p>
</li>
</ol></div>
<h3 id="cherokee_vserver">Setting up WordPress as a new Virtual Server</h3><div style="clear:left"></div>
<h4 id="_default_virtual_server">Default virtual server</h4>
<div class="paragraph"><p>We’re assuming we have the default configuration initially provided by
Cherokee Admin.</p></div>
<div class="paragraph"><p>We will begin by cloning the default virtual server, just to keep the
default PHP configuration. Create a clone named <tt>example.net</tt>.</p></div>
<div class="paragraph"><p>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 <tt>Redirection</tt> handler, like this:</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="30%" />
<col width="30%" />
<col width="40%" />
<thead>
<tr>
<th align="left" valign="top">Type </th>
<th align="left" valign="top"> Regular Expression </th>
<th align="left" valign="top"> Redirection</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">External</p></td>
<td align="left" valign="top"><p class="table">^(.*)$</p></td>
<td align="left" valign="top"><p class="table"><a href="http://example.net/$1">http://example.net/$1</a></p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>This clears the first milestone. The remaining ones will be
accomplished by tweaking the <tt>example.net</tt> virtual server.</p></div>
<h4 id="_example_net">example.net</h4>
<div class="paragraph"><p>Remember to set up the <tt>Document root</tt> to <tt>/var/www/wordpress</tt>.</p></div>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_wp_example1.png" alt="media/images/cookbook_wp_example1.png" />
</div>
<div class="image-title">Custom document root</div>
</div>
<div class="paragraph"><p>Delete all the rules except <tt>php</tt> and <tt>Default</tt>. We’re heading right
to the second milestone now.</p></div>
<div class="paragraph"><p>As previously, we will manage the <tt>Default</tt> rule with the redirection
handler.</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Redirection handler</caption>
<col width="30%" />
<col width="30%" />
<col width="40%" />
<thead>
<tr>
<th align="left" valign="top">Type </th>
<th align="left" valign="top"> Regular Expression </th>
<th align="left" valign="top"> Redirection</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">Internal</p></td>
<td align="left" valign="top"><p class="table">^/(.*)$</p></td>
<td align="left" valign="top"><p class="table">/index.php</p></td>
</tr>
</tbody>
</table>
</div>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_wp_example2.png" alt="media/images/cookbook_wp_example2.png" />
</div>
<div class="image-title">Redirection handler</div>
</div>
<div class="paragraph"><p>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
<tt>Directory</tt> type rules for the following directories: <tt>wp-includes</tt>,
<tt>wp-content</tt> and <tt>wp-admin</tt>. These are to be managed with the <tt>List &
Send</tt> handler.</p></div>
<div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>To do this, we will be creating <tt>Directory</tt> type rules for the
<tt>images</tt> and <tt>static</tt> directory, and a <tt>Regular Expression</tt> type rule
for the sitemap.</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="40%" />
<col width="60%" />
<thead>
<tr>
<th align="left" valign="top">Type </th>
<th align="left" valign="top"> Value</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">Directory</p></td>
<td align="left" valign="top"><p class="table">/images</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Directory</p></td>
<td align="left" valign="top"><p class="table">/static</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Regular Expression</p></td>
<td align="left" valign="top"><p class="table">/sitemap.xml.*</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>Remeber to manage them with a handler that can serve files: <tt>Static
content</tt> and <tt>List & Send</tt>.</p></div>
<div class="paragraph"><p>Almost any evaluation order of your rules will suffice, as long as the
one that handles the PHP files is the first one.</p></div>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_wp_example3.png" alt="media/images/cookbook_wp_example3.png" />
</div>
<div class="image-title">Rule list</div>
</div>
<h4 id="_warning">WARNING</h4>
<div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>If you encounter this problem and absolutely need to see the last
screen, please increase your server’s <tt>timeout</tt> value, under the
<tt>Basic Behavior</tt> paragraph of the <tt>General</tt> tab, and start over.</p></div>
<div class="paragraph"><p>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 <a href="cookbook_wordpress.html#setting_up_wordpress">Setting up
WordPress</a>.</p></div>
<h4 id="_warning_2">WARNING</h4>
<div class="paragraph"><p>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 <tt>Error
500</tt>. Having a broken MTA on a production server is a very unlikely
scenario, but double check your MTA in case you receive this error.</p></div>
<h3 id="wordpress">Setting up WordPress</h3><div style="clear:left"></div>
<div class="paragraph"><p>First download and uncompress the distributed WordPress release into
<tt>/var/www/wordpress</tt>, and create a database suitable for the installation.</p></div>
<div class="paragraph"><p>Log in to MySQL:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>mysql -u root -p</tt></pre>
</div></div>
<div class="paragraph"><p>And create the database for WordPress. We will be using the name
<em>wp</em>, the user <em>wpuser</em> and the password <em>wppassword</em>, but
you should set up your own.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>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;</tt></pre>
</div></div>
<div class="paragraph"><p>Then point your web browser to <tt>http://localhost</tt> and follow the
instructions provided by the installer.</p></div>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_wp1.png" alt="media/images/cookbook_wp1.png" />
</div>
<div class="image-title">WordPress installation site info</div>
</div>
<div class="paragraph"><p>And the installation will be automatic. Just fill up the
requested values and you will obtain the following results once your
are through.</p></div>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_wp2.png" alt="media/images/cookbook_wp2.png" />
</div>
<div class="image-title">WordPress installation administrator info</div>
</div>
<div class="paragraph"><p>With that, you are done installing. Let’s log in and make the last
adjustments.</p></div>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_wp3.png" alt="media/images/cookbook_wp3.png" />
</div>
<div class="image-title">WordPress login</div>
</div>
<div class="paragraph"><p>Once we’re logged, we can configure the way <tt>permalinks</tt> are
displayed. Just use the <tt>Settings</tt>→<tt>Permalinks</tt> menu, and adjust the
way the links are to be rewritten.</p></div>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_wp4.png" alt="media/images/cookbook_wp4.png" />
</div>
<div class="image-title">Permalinks</div>
</div>
<div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>And voilà! You have a WordPress installation working flawlessly with
Cherokee.</p></div>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_wp5.png" alt="media/images/cookbook_wp5.png" />
</div>
<div class="image-title">WordPress in action</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
</div>
</div>
</body>
</html>
