As with all 500 status codes, the 503 code is an error code but it signifies a temporary error. The client should try again later (in fact you can specify how much later using the Retry-After header).

A 200 code tells the client everything is normal and OK. So the user gets your nice maintenance page telling them of a temporary outage, whereas their browser gets told that everything is fine. Now this might not be a problem for a user, but if the client is a search engine or a caching proxy then it will assume the maintenance page is the new valid content for the request.

If the Google crawler hits your site when you have the maintenance page up, it will update its search index with your “we’re down for now” message, rather than your cash prizes blog content. Your page rank will drop, your fat Adsense cheque will diminish and you’ll have to go back to your regular nine to five job in the city with people you don’t like in clothes you hate wearing.

So, as you can see, it’s important to return the correct status code. Here’s how to do it with Lighty and mod_magnet:

Mod_magnet

Mod_magnet allows you to control request handling in Lighttpd using the Lua programming language (it replaces mod_cml and adds some bells and whistles). Here’s how to do a maintenance page with it:

Ensure the module is loaded:

server.modules += ("mod_magnet")

Tell it where to find your Lua script:

magnet.attract-physical-path-to = (server.docroot + "/magnet.lua")

Write a lua script to check for the maintenance page file and display it instead of the usual content if it exists.

if (lighty.stat(lighty.env["physical.doc-root"] .. "/maintenance-live.html")) then
                lighty.content = { { filename = lighty.env["physical.doc-root"] .. "/maintenance-live.html" } }
                lighty.header["Content-Type"] = "text/html"
        return 503
end

Create your maintenance page as maintenance.html in your document root. When you want it displayed, symlink it to maintenance-live.html and it will automatically be displayed.

I find it useful to be able to switch back and forth easily without restarts in and around the actual maintenance period but don’t need it day to day. So if you worry about the extra file stat operation (and the Lua) overhead during normal periods then just comment the Lua code out when you’re done with the maintenance feature for a while. mod_magnet will detect that you modified the Lua script and recompile it automatically.

You’ll notice that the return 503 actually returns a pre-generated HTML page as well as setting the status code. This extra bit of html gets tagged onto the end of your nice maintenance page, making it a bit ugly. You’ll just have to put up with this for now. I see this as a bug in Lighty which needs addressing. There should be some way to set a status code with Lua without returning the pre-generated html too.

Debug access

It might be convenient to disable the maintenance page for certain client IP addresses: if you’re upgrading the site, you’ll want to test it’s working yourself before disabling the maintenance page, right? I couldn’t figure out how to get the source address from within the Lua script, so I did it as a conditional in the Lighty config:

  $HTTP["remoteip"] != "10.0.0.1" {
    magnet.attract-physical-path-to = ( server.document-root + "/magnet.lua" )
  }

Using mod_magnet might be overkill for just this task, but if you’re already using it for other request processing stuff, then it’s ideal for this. Or maybe its convenience will be enough to sway you. Just remember to get the status code right!

See nixCraft for another example using PHP.

To speed up WordPress I usually just enable the MySQL query cache and install the eaccelerator PHP opcode cacher. On one particular box, an Intel 1.3Ghgz PIII this increased performance from around 3 requests per second to around 10.

Recently I came across the WP-Cache plugin for WordPress. This takes the finished output from any given wordpress request and caches it to disk, serving directly from the static cache for the next hour (configurable). Any new posts or comments in the mean time immediately mark the cached version stale, so you don’t need to wait around for an hour.

On the same hardware and blog, this increases performance from 10 requests per second to over 250. A 2500% increase in speed.

Lighttpd cache meta language

With WP-Cache, each request still has to incur the penalty of a PHP script execution, even though it’s much shorter one than the usual WordPress path. Lighttpd now has a mod_cml plugin which allows you to script caching decisions in a language called Lua, directly in the web server.

One should be able to implement enough WP-Cache logic with Lua so that Lighttpd can serve the cached static html directly, only executing PHP when the cache is stale.

Looking at the WP-Cache code, all that’s needed is a md5sum hash of the request url and a file modification time check, which seems to be possible in Lua in mod_cml.

The only thing that can’t be done is reading cache files for users with login or comment name cookies, as mod_cml doesn’t seem to provide access to cookies. This would still increase the performance for the majority of requests though.

I’ve not had time to write and test a Lua script yet though.

Apache Bench results

Before WP-Cache

This is ApacheBench, Version 2.0.41-dev
Server Software:        lighttpd/1.4.11
Server Hostname:        geekz.co.uk
Document Path:          /lovesraymond/archive/terrorismistic
Document Length:        16004 bytes
Concurrency Level:      3
Time taken for tests:   4.861144 seconds
Complete requests:      50
Total transferred:      818266 bytes
HTML transferred:       808270 bytes
Requests per second:    10.29 [#/sec] (mean)
Time per request:       291.669 [ms] (mean)
Time per request:       97.223 [ms] (mean, across all)
Transfer rate:          164.36 [Kbytes/sec] received

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    0   0.0      0       0
Processing:    92  118  91.1     94     649
Waiting:       67   84  54.6     69     393
Total:         92  118  91.1     94     649

Percentage of the requests served within a certain time (ms)
  50%     94
  66%     95
  75%     97
  80%     98
  90%    155
  95%    217
  98%    649
  99%    649
 100%    649 (longest request)

After WP-Cache

I had to run the test for longer else it was too quick for reliable results (and higher concurrency too)

This is ApacheBench, Version 2.0.41-dev
Server Software:        lighttpd/1.4.11
Server Hostname:        geekz.co.uk
Document Path:          /lovesraymond/archive/terrorismistic
Document Length:        16098 bytes
Concurrency Level:      5
Time taken for tests:   3.79451 seconds
Complete requests:      800
Total transferred:      13059990 bytes
HTML transferred:       12942792 bytes
Requests per second:    259.79 [#/sec] (mean)
Time per request:       19.247 [ms] (mean)
Time per request:       3.849 [ms] (mean, across all)
Transfer rate:          4141.32 [Kbytes/sec] received

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    6   5.0      7      22
Processing:     4   11   6.5     11      67
Waiting:        0    7   6.2      7      61
Total:         16   18   4.1     18      80

Percentage of the requests served within a certain time (ms)
  50%     18
  66%     18
  75%     18
  80%     18
  90%     19
  95%     19
  98%     24
  99%     34
 100%     80 (longest request)

WP-Cache and PHP 5.1 bug workaround

Just a quick note, I use PHP 5.1 and came across a bug in WP-Cache that displayed blank pages on first load. It’s an easy one line fix once you know how.