Switching to Nginx from Cherokee: Techincal Guide

This is a follow up to a previous post on Switching to Nginx from Cherokee. Read that in case you’re here and haven’t already.

All information here on a server level is related to RHEL 6. You will need to change some instructions for Debian based systems. CentOS should be fine and needs only a minor URL change in the repo configuration.

  1. Edit /etc/yum.repos.d/nginx.repo and add this:

    name=nginx repo
  2. Run yum install nginx to install Nginx.

  3. Start rebuilding your configuration files in Ngnix format. I achieved this by starting cherokee-admin (the Cherokee GUI interface) and stepping through the configuration one server, and one behaviour at a time until I was finished. Refer to Configuration changeover below for helpful hints and configuration matching.

    This will take you some time. It took me 2 days for about 15 servers, which isn’t bad considering! I think it’s a testament to how similar the configuration between the two happens to be.

  4. Stop Cherokee and start Ngnix once your configuration is ready:

    service cherokee stop
    service nginx start

Configuration changeover

Note that the following is a rough mapping of what you can use to convert Cherokee configuration to Ngnix. In the interests of not reproducing information that’s already on Ngnix’s site, I’ve just linked to their wiki. Keep in mind this list isn’t complete as it’s just what I used for converting my configuration. Your requirements may be more complex. The good news is that most things have a counter-part in both applications.

It’s worth remembering that a lot of these aspects, whilst locking in place within Cherokee, don’t have to be configured at the same level within Ngnix. For instance, whils Cherokee requires you to specify ports to listen to at the server-configuration level (top), Nginx applies this at a server level.

Also keep in mind that everything in Ngnix is inherited based upon the nesting of the various http, server, location blocks within the configuration. This is particularly nice and helps reduce duplication that you might have had originally with Cherokee. So, if you find yourself doing something like gzip on within Ngnix everywhere, maybe just enable it server-wide or http-wide at that level, and just use gzip off wherever you need it turned off. Easy.

Some things like listen might seem a little more verbose to start, since you may find yourself repeating it a few times, but once you realise how it all works, it’s a lot more flexible across multiple host names or IP addresses.

If you’ve got more to add to this, feel free to fork my blog on GitHub and submit a pull request.


Cherokee option Nginx option
Ports to listen listen
Timeout client_body_timeout, client_header_timeout, other *_connect_timeout or *_read_timeout options
Server Tokens server_tokens
User user
Mime Types Refer to /etc/ngnix/mime.types


Virtual server option Nginx option
Virtual Server server block
Virtual Server nickname server_name
Document Root root
Directory Indexes index
Match nickname server_name
Virtual Server matching server_name (Use \~ to specify regex)
Error logging error_log
Access Logging access_log
SSL Certificate ssl_certificate
SSL Certificate key ssl_certificate_key


Behaviour option Nginx option
Behaviour location block, if condition
Matching rule

Depends. location is a good start for matching URI strings, regex, directory names and paths. Watch out for if statements within location.

Try and simplify rules down. Odds are your rules aren’t complicated and don’t need to be. Avoid unnecessary regular expressions and use strings only if possible. Note that location blocks in Ngnix will match on initial substrings by default.

Many things that you might have had to use conditional if, and, not and or in Cherokee can be done either by using regex instead or using built-in logic in Ngnix. For instance, use a dedicated server blocks to handle HTTP and HTTPS differently and avoid needing tonnes of if statements.


Configuration (typically) within location. May move to server block if appropriate.

  • None: {} (empty brackets)
  • List & Send: alias or root
  • Static Content: alias or root
  • Only Listing: Unknown.
  • Redirection: return or rewrite
  • FastCGI: fastcgi_pass and fastcgi options
  • SCGI: scgi_pass and scgi options
  • uWSGI: uwsgi_pass and uwsgi options
  • HTTP Reverse Proxy: proxy_pass and proxy options
  • Upload Reporting: Unknown
  • CGI: Not directly supported. Use uWSGI to wrap.
  • Server Side Includes: ssi
  • Hidden Downloads: See 3rd party modules.
  • Server Info: Unknown.
  • MySQL Bridge: Not applicable.
  • HTTP Error: return
  • Remote Administration: Not applicable.
  • 1x1 Transparent GIF: empty_gif
  • Drop Connection: return 444 (special code)
Transforms gzip, gzip_comp_level (more options here!)
Caching expires, various _cache directives
Security allow, deny
Restrictions client_body_timeout, client_header_timeout, other *_connect_timeout or *_read_timeout options

That’s about it. It’s mostly a manual process to step through the configuration and sort each rule out. It’s not quick so bring a cut lunch. The good news though is that most things map almost exactly. Even regex.

Go Top
comments powered by Disqus