Switching to Nginx from Cherokee: Techincal Guide

// under Nginx Cherokee web web servers

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.

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

[nginx]
name=nginx repo
baseurl=http://nginx.org/packages/rhel/$releasever/$basearch/
gpgcheck=0
enabled=1

Run yum install nginx to install Nginx.
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.
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.

Server-level

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`

vServer-level

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-level

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. Directory: location Extensions: location Regular Expression: location Header: if (in server or location) Exists: try_files or if HTTP Method: if against $request_method_ Incoming IP/Port: None. Use correct server block SSL/TLS: Use specific server block (fastest), or if against $server_port_ Full Path: location Connected from: if against $remote_addr_ URL Argument: location or if against $args_ GeoIP: See geo module 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.
Handler	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