Experiments with Linux


Install Cherokee Server On a Raspberry Pi

Submitted by Derwent Ready on Saturday, 01 December 2012

What is Cherokee

Cherokee is a web server but unlike Apache which is kind of slow and old fashioned in its design or Nginx which has minimal documentation and seems to be all file based on its configuration Cherokee claims to be at least C10K compliant (vs Apache, like Nginx) and comes with a nice web UI based configuration client (vs both)

Why Install Cherokee on a Pi?

I've been developing several large web projects and I wanted a web-accessible/always on low power  development server. Cherokee should be lighter, faster and easier to maintain on the Pis low specs than Apache.

Some Notes

  • I do not claim to be a security expert or anything so some of my techniques may leave you vulnerable, use at your own risk.
  • I assume you're running a fresh installation of Raspbian but it shouldn't be necessary to reinstall it if you've been fiddling. Debian used to have a package for Cherokee but the maintainer seems to have given up for the time being and while there has been talk of someone taking it over as far as I can tell as at the time of writing no one has.
  • I am writing this as if you have about a day's worth of Linux experience on a Raspberry Pi, you've got the basics like sshing in and maybe installed a package or two but otherwise don't know much.
  • I must admit to being a little confused by the documentation at times. Some things you'd want to know seem to be spread out over several pages that aren't really connected but could be merged into a single or at least a few pages but overall all the stuff you'd need to know are there and very informative when you find it.
  • Word of warning: This is going to be a mammoth post both in terms of reading and time to actually perform some of the actions.
  • Word of warning: Cherokee doesn't support .htaccess files and people often have trouble converting Apache redirection rules to Cherokee rewrite rules but the lack of an .htaccess file is suggested to be one of the biggest improvements in design over Apache as it doesn't have to be parsed for every single request.

About This Tutorial

EDIT: This article went out of date almost before I'd finished writing it. I've left it here for posterity. Check the blog for updated instructions on how to install Cherokee on a Raspberry Pi. Most of the steps in this article are still relevant but the changes made to Cherokee make installation a bit easier.

I'm going to show you how to build your own version of Cherokee given that the default packages are no longer maintained/available for Debian/Rasbian. These instructions are based on those found at: http://www.cherokee-project.com/doc/basics_installation_unix.html. If you want you can just use these, it's what I did but I'm going to go into a bit more detail, step by step of what I did to get it working. I assume that you're running the Pi headless and will be doing everything over SSH. See my remote x tutorial for how to setup remote x, it'll make your life easier if you're SSHing it. If you'd rather work on the Pi directly I will endeavour to make it so you can skip steps.

Step 1 – Visit the Cherokee site, see what you think:

Visit www.cherokee-project.com click on the link that reads Download Cherokee 1.2.101. This will take you to the download page where if you select Linux (it defaults to the OS you're visiting on which for me is usually Windows). This page gives you a list of ways of installing Cherokee using apt etc. For this tutorial I want you to download a mirrored copy of it. I'm in the UK so I chose the mirror at http://cherokee.hyperial.com. I would recommend this one as it's actually running on Cherokee and therefore feels more official :P.

Cherokee web server homepage

Step 1.2 – Download the source:

Now that you're on a mirror (preferably the Hyperial one) click the 1.2 folder then 1.2.101 (in the case of Hyperial dated 18-Oct-2011). Download the single tar.gz file that's in this directory.

Alternatively you could just wget the file from SSH to save having to FTP the file to the Pi later. The command for this would be:

cd Downloads

wget http://theurletcgoeshere

If you're working directly on the Pi you can ignore step 1.3.

Step 1.3 – SSH/SFTP:

Login to your Pi through your favourite SFTP client and copy the tar to somewhere. I chose: /home/pi/Downloads.

Login to your Pi with your favourite SSH client.

Putty connection settings

Step 1.4 – Extract the Source Files:

Go to your download location and extract the file. To navigate you can cd:

cd Downloads
or
cd /home/pi/Downloads

You can extract using the tar command line which I don't fully understand but I believe the command would be:
tar xfv cherokee-1.2.101.tar.gz

My preferred method would be to load pcmanfm from the command line (or just click the file manager link on the LXDE taskbar), go to your download location and run xarchiver on the file.

Step 2 – Getting Ready to Build:

Step 2.1 - Install gettext package:

We're just about ready to build. However one of the things it needs to install correctly is the gettext package. In the command line type: sudo apt-get install gettext

Go to the extracted folder: cd /home/pi/Downloads/cherokee-1.2.101

Step 2.2 - Configure:

In the terminal type: ./configure --localstatedir=/var     \
            --prefix=/usr            \
            --sysconfdir=/etc        \
            --with-wwwroot=[yourpreferredwebroot]

A couple of notes on the --with-wwwroot parameter.
The default wwwroot is /var/www but you can set a custom wwwroot, I did. If you put the www folder within your user home directory you won't have to use elevated privileges to maintain your web files. You can use something like /home/pi/www or similar.

Alternatively you can use /var/www and then symlink your /home/pi/www folder to your /var/www and if that's what you want to do go ahead and use /var/www as the value for that parameter and I will give you a step further down (after everything's setup that will let you do this.

A complete list of parameters can be found at: http://www.cherokee-project.com/doc/basics_installation_unix.html

Step 2.3 - Make:

Once configure has run its course you now type: make

This will take a while. You might want to go make a cup of tea or something.

Step 2.4 - Install:

Now Cherokee has been made, you need to install it. Type: sudo make install
This will take a little while too but shouldn't be anywhere near as long.

Done? Congratulations! Cherokee is now installed! However currently if you want to run it you'll have to type sudo cherokee in the terminal everytime you reboot the Pi. Let's fix this.

Step 3 – Getting Cherokee to Start on Boot:

I'll admit straight up that I've had a lot of trouble getting Cherokee to start at boot on the Pi but after a couple of installations I think I've worked out why.

You should still be in the extracted Cherokee folder, if not refer back to Step 2.

In essence what you need to do is copy the cherokee start up script to /etc/init.d but it seems like the default build doesn't make the cherokee script executable which it needs to be.

In the terminal type: chmod +x contrib/cherokee

Step 3.1 – Copy the script:

Type: sudo cp contrib/cherokee /etc/init.d/
Remember, because the target directory is outside of your home folder you need to provide elevated permissions to copy it.

Step 3.2 – Update the boot scripts:

You now need to update the boot sequence to include the cherokee script. In the terminal type:
sudo update-rc.d cherokee defaults

If you get an error about missing LSB flags then I'm pretty sure it's worked. If you get an error about the file not being a regular executable file it most likely hasn't worked. (In which case go back and try the chmod line again from above (end of step 3)).

Step 3.3- Reboot:

Reboot! :P In the terminal you could always type: sudo shutdown -r now

Is it back up and running yet?

Step 4 – Testing and Some Configuration:

Step 4.1 - Symlinking - Optional:

OK. So in the Cherokee config section (Step 2.2) I mentioned a thing you can do called symlinking. This is pretty useful as it means you can access files in your user-space that indirectly affect file locations that would normally be reserved for elevated permissions. It's a bit like Windows shortcuts where you can have one file/folder in multiple places on the filesystem without incurring a massive cost of duplication or the hassle of keeping them synchronised. In Linux it also saves a lot of time having to sudo all over the place.

eg. /var/www/bob will point to /home/bob/www such that bob can be seen to be editing /var/www/bob directly without realising he's doing so, without elevated privileges and without risk of breaking any crticial system files.

Another useful thing you can do with symlinking and is what I've mostly used it for is this: Say you want to give each person in your family their own user and web space for developing/test/running their own website. What you can do is have:

littlesusie, rascallyrob, gorgeousmary and handsomdave each with their own /home/[user]/www folder. Now you can symlink each of these /www folders into a subdirectory of /var/www or /home/pi/www (wherever your webroot is) and each user can happily tinker away with their own slice of Raspberry Pi web development without having to bother with sudo elevated privileges and without worrying that they might spoil someone else's perfectly crafted website.

OK. So how do we symlink? Quite simply you type: (sudo) ln -s /target/file /destination/file

This breaks down like so:

ln simply creates a link to a file.

-s means it's symbolic meaning the link can cross file system boundaries and can be a directory. A hard link (created with -l would have those limitations applied).

/target/file is the file you would like to link to somewhere else

/destination/file is the location where you would like to point the target file. When you navigate to this destination folder it will redirect you to the original (target) file.

A note on symlinking. As far as I can tell the destination folder must already exist or it will be created as a file. I'm sure If the destination folder doesn't exist you'll have to run: sudo mkdir /path/to/destination before you continue with your symlinking.

Right, so onto how to symlink your user-space www directory to your non user-space www directory. Type:

sudo ln -s /home/pi/www /var/www

Notice in this case we don't need to use a mkdir beforehand as /var/www was already created by the Cherokee installation.

Step 4.1 - Checking It:

Go to your favourite browser either on the pi or another computer on the network. If you're on the Pi you can just type: localhost into the address bar.

You should be greeted by a little cartoon Cherokee man and a description of the Cherokee web server.

The Cherokee server test page

If you're working over the network you will have to type: [ip_address] into the browser address bar where [ip_address] is the IP address of your Pi. To find this out pn the Pi type:

ifconfig

This will spew out some stuff like eth0 Link etc etc

What you're looking for is: inet addr:xxx.xxx.x.xxx where xxx is your IP address. For example mine is 192.168.1.10. Depending on whether you're running the pi wired or wirelessly you will have to look for this either under eth0 (wired) or wlan0 (wifi). This of course assumes you only have 1 wifi dongle or usb lan adapter installed otherwise it might be ethX or wlanX where X is the number of such adapters you'd have plugged in.

Again, you should be greeted by the same little cartoon Cherokee man.

Step 4.3 - Backup Test:

If you AREN'T greeted by a little Cherokee man don't despair just yet. Type:

sudo nano [yourwebroot]/index.html

This will bring up nano, a basic command line text editor and you can type any old HTML into it. For example:

≶h1&rg;This is My Pi≶/h1&rg;

Then hit: Ctrl+O to save the file and Ctrl+X to exit.

Navigate back to your localhost or ip address in your chosen web browser and HOPEFULLY you should now see a mostly blank page with the contents of your index.html file. If not, there is one other possible solution and that is that you already had another webserver like Apache installed which is taking over and loading before Cherokee. This is a bit fiddly to cope with in this tutorial. Tweet me if you would like me to make a post to try and deal with this problem.

Step 5 - Setting Up PHP and Mysql:

Most people want to run fancy CMS' with databases and stuff so I'll now show you how to install PHP, Mysql and PHPMyAdmin directly into Cherokee.

Note: We can install most of the packages we need in one command but so you know what you're getting I'm going to do it one or two packages at a time.

Step 5.1 - Installing PHP:

In the terminal type: sudo apt-get update to get the latest packages.

Then type: sudo apt-get install php5. This is the base package for PHP.

sudo apt-get install php5-fpm. This is the package that allows PHP to run with Cherokee. You can alternatively install php5-cgi but fpm is the package recommended by Cherokee.

Step 5.2 - Installing Mysql:

We're going to install Mysql next. This involves the two packages:

mysql-server-5.5

mysql-client-5.5

Type: sudo mysql-server-5.5 mysql-client-5.5

Step 5.3 - Installing Other PHP Packages:

For any of these packages type: sudo apt-get install [package name].

You could also list them on the one line as: sudo apt-get install [package name] [other package name] [another package name] [etc].

Packages in bold are ones I'd recommend.

php5-mysql

php5-curl

php5-mcrypt - this is needed for the next step

php5-gd - this allows you to make images procedurally from within PHP. It's also needed for the next step.

php-apc - This caches the PHP opcode which means files run faster as they miss out the compile step unless the code's been updated.

Step 5.4 - Installing PHPMyAdmin Through Cherokee Admin:

Cherokee-admin is a powerful browser based graphical configuration tool that is one of the key improvements over servers like Apache and even, I believe, Nginx.

EDIT: I have a slight confession to make, I started writing this post a while back, it took longer than I expected to finish and test all the steps and this was the last step I had to write before Cherokee went through some major changes. One of the features that Cherokee used to have was the app market that made installing various web applications such as phpmyadmin quick and simple, however due to developer strain they removed this feature not long after I started writing this post. I'm writing a follow up post for how to setup Cherokee using the new process so please have a look for that article for how to install Phpmyadmin for use with Cherokee.

If you'd rather follow this tutorial because you've come so far you can try these steps but I don't guarantee they'll work as they're from the older version of the Cherokee documentation and they're untested by me.

In the terminal type:

sudo apt-get install phpmyadmin


If the phpmyadmin installer asks you choose a web server, select any in the list as Cherokee isn't one of them.

According to this page on the Cherokee documentation if you point your browser to localhost/phpmyadmin (if you're working directly on the Pi) or [pi-ip]/phpmyadmin if you're working remotely you should now see the phpmyadmin login page.

Step 6 – Exposing it to the Web:

This part is going to be a little difficult to explain as it involves fiddling with router settings and those can vary quite a bit.

Step 6.1 - Signup with No-ip.com – It's free:

In order for your Pi to be accessible on the web you need it to go through a DNS service. Go to www.no-ip.com and signup for the free personal DNS service. At www.no-ip.com/personal just scroll right to the bottom and click the Sign Up Now button under No-IP Free (unless you want to find out more in which case click More).
On the signup page you need to give a username, password, email address and finally the hostname you want. You could try [yourname].no-ip.org. They also have serveral domain suffixes for you to choose but the default is no-ip.org.
Now, click Sign Up.

Step 6.2 – Verify:

You should receive a couple of emails, the first of which will be the verification email. Click the link in the email and follow any further instructions.

Step 6.3 – Download the Client:

No-IP needs to know where to find your computer on your network. We'll do this the quick and simple way as per their own instructions.

Type:

cd /usr/share/src

sudo wget http://www.no-ip.com/client/linux/noip-duc-linux.tar.gz

sudo tar xf noip-duc-linux.tar.gz

cd noip-2.1.9-1/

sudo make install

Once the installation has finished it should ask you to login with your no-ip account username and password. If not type:

sudo /usr/local/bin/noip2 -C

The noip client needs to be run at least once a month to keep the records up to date. You can do this manually every ~30 days by typing:

sudo /usr/local/bin/noip2


or alternatively you can make a startup script for it.

Step 6.3.2 - The Noip Startup Script:

In the terminal type:

sudo nano /etc/rc.local

Just before the "exit 0" line at the bottom type:

/usr/local/bin/noip2

Now Ctrl + o to save and Ctrl + x to exit nano. When you next reboot you should have an automatically running no-ip client automatically updating your hosts for you.

Step 6.4 – Setup Port Forwarding:

In your favourite browser navigate to your router. The IP address is usually something like "192.168.1.1" without the quotes though some routers do use a different IP address such as "192.168.0.1" or "192.168.2.1".

Once you've logged in, find a link or menu item that says something like virtual host/server or WAN. On my ASUS Router and I believe on most ASUS router there is a link called WAN and under this page there is a Virtual Server/Port Forwarding tab. This is where you add any ports to forward. The main one we're dealing with is port 80.

Asus router links

Under port range you will want to put the external port that web browsers will be looking for, by default this is port 80. Under local IP you want to add the Pi's IP address. Under local port you want to put Cherokee's listening port which in this case is 80 again. If your router lets you assign a service name or similar then name this port redirection anything you want, "RaspberryPiCherokeeV1" or something could work.

Once you've hit apply and waited for your router to update/reboot you should be able to point your browser to your-host.no-ip.org or whatever it was you chose and your Pi website should load.

Asus port forwarding settings

Step 6.5 - Extra Port Forwarding - Optional:

If you want, now is the time to add port forwarding for your SSH server (if you have one setup, by default I believe Raspbian is set to listen for SSH connections on port 21 or port 22). I would recommend using a custom port range for this as it means only people who know that you're running an SSH server on your Raspberry Pi can find it.

Try something like: port range 6565, Raspberry Pi local ip, local port 22, protocol TCP. Now if you want to remotely SSH into your Pi from another network you'd type:

Finally you could also add the Cherokee-admin port (9090) to this list so that you can do remote server admin from a browser on another computer not connected to the same network as your pi (say from your laptop in a coffee shop) but as I don't recommend this practice for security purposes I won't tell you how.

And we're done! I'll do another post in the future for how to setup Cherokke in a more advanced way. I'm sorry this was such a long post but there was a lot to cover and I wanted to it to be as in-depth as possible. I hope my ramblings and information on how to customise your setup weren't too confusing and please tweet me if you have any questions about setting up Cherokee further.


If you liked this blog post, why not buy me a beverage?

Blog Appreciation: Usefulness