Set up a Railo/Apache/MySQL host on Ubuntu - Part 1: install Railo and Apache
Firstly, I must admit, I'm not a Unix guy. I love Windows, I love point and click, I love something that just takes 2 minutes to install so that I could focus on doing something else more important. And that is what I was looking for last time when I installed Railo on Ubuntu: a step-by-step guide to install Railo for those who have no or not much experience with Unix. But I found no complete one. They generally have one or many of the following issues:
- They make too many assumptions about the OS and the users/developers experience with Unix. Every Unix version is different and even though I need to install a server on Unix (sound like a big job), that is in fact all I want to do with Unix. I don't want to go through tons of documentation just to get this done
- They do not provide sufficient details about what needs to be prepared first for the actual Railo installation to happen
- There is no clear and easy way for me to verify that I follow the steps in the guide correctly
I did manage to get my hosting up using those guides though and I really thank who wrote those articles. But it was a hard time. I spent a lot of time doing side-track tweaks, changes and other pre-installations to get it work. So I now compile them into one guide that I hope to be a more complete one to help those who want to install Railo with Apache on Ubuntu.
This guide is for installing Railo 3.1 with Apache 2 and MySQL (or RAM) on Ubuntu 9 (work with Ubuntu 8 too if I remember correctly). Depending on what Unix OS you are using, you might need to adjust the steps a little bit. If you do, please share them at the comments at the end of the article to help build a more complete guide.
This is an article I hope I had by the time I set up my VPS. You do not need much knowledge about Unix to follow this article. I will explain the process in step by step and also point out where I encountered problem so that you could watch out for it! Plus, at the end of every step, I will include a little part called Step verification for you to know if you have completed that step successfully. It's important that you check this as a step depends on the one before it to be completed. So if you could not get one step done successfully, there is chance you will encounter errors at the steps that follow.
I break this guide into 4 parts to make it easier for you to follow and also give you a chance to review at the end of every part to make sure the setup has been going as expected before moving on:
- Part 1: install Apache and Railo
- Part 2: install MySQL and enable remote access
- Part 3: install FTP server and set up user access
- Part 4: install subdomains
PART 1: Install Railo and Apache
1. Assumptions and notes
1.1 You have SSH access
This article assumes that you already installed Ubuntu 9 and you got SSH access to your host.
When login to SSH, you need to have permission to run the commands stated below. If you receive error saying "Permission denied" or something similar, try to use sudo before the command and login with your password when asked at the first time.
1.2 If you are using Windows, you have a Unix-mode editor installed
During this process, you will need to edit some config files. If you are on Windows, make sure you use an editor that supports Unix-mode to do this. A good and free one is Crimson Editor. This is very important. You have to edit the files under this editor otherwise it will cause errors when you reupload it to the server. Do NOT use Notepad.
There are many small programs that are quite essential and we need them for this Railo installation but unfortunately depending on your OS, they might not be installed by default. So before you start installing Railo or Apache, you need to install these programs first. They include:
- GCC compiler
- Apache2 threaded dev package
To install them, run the following commands from the SSH command prompt one by one:
$ apt-get install gcc
$ apt-get install automake
$ apt-get install autoconf
$ apt-get install lynx
$ apt-get install apache2-threaded-dev
3. Download installation files
Railo and many other programs cannot be installed in the same way as you do above (using apt-get command). The installation files need to be downloaded first and installed from there (just like you do on Windows, download the exe file and double click on it to install).
3.1 Create a directory to hold the downloaded installation files
You can download the installation files to any location you like on the host, but I prefer to keep all of my installation files in a particular directory for easy management, in this case I keep them at /opt/soft/_install_files. So if you choose to put the downloaded files at another location, make sure you change the paths in the related commands accordingly.
Create the installation file directory:
3.2 Download Railo
By the time of this writing, the latest version of Railo does not work (!), so I download the version 3.1.1.000 at:
I don't think it is a major issue for not running the latest version. Plus, you can still upgrade it later if you like.
You notice that the file name has the part "without-jre" in it. Yes, I want to get the version that does not have JRE. It will be installed separately at a later step.
To download Railo, run the following commands:
$ wget http://www.getrailo.org/railo/remote/download/3.1.1.000/server/all/railo-3.1.1.000-resin-without-jre.tar.gz
3.3 Download JDK
Similar to downloading Railo, we need to download the JDK. However, the link to this JDK is a little bit more complicated. To find out the link:
- Go to the following page: http://java.sun.com/javase/downloads/widget/jdk6.jsp
- Select Linux from the drop down
- Click "Continue"
- Once you are presented with the download links, copy one of the them, such as the rpm one (let's refer to this as [THE JDK LINK])
- Also keep in mind the file name such as jdk-6u20-linux-i586-rpm.bin (the version number depends on what is available at the time you download). You need this name in the step below.
Once you got the link, go back to SSH and type the following commands and replace the JDK link with the one you copied:
$ wget [THE JDK LINK] jdk-6u20-linux-i586-rpm.bin
We need to include the file name in the wget command this time because due to the complexity of the link, the download sometimes breaks. One way to help prevent this is to specify the name of the downloaded file rather than letting Ubuntu work out itself.
4. Install Apache2
As Railo will be connected with Apache, we need to install Apache first. From the SSH, run:
Start Apache by typing the following command at the SSH:
5. Install JDK
We need to install the JDK before we can install Railo. To do this, we need to know the path to the downloaded JDK file. If you follow the structure as I set up, the JDK file will be sitting at /opt/soft/_install_files/jdk-6u20-linux-i586-rpm.bin. The file will be installed into a directory with the same name as the file name but without the extension, i.e. jdk-6u20-linux-i586-rpm. Type the following commands from SSH:
$ cd /opt/soft
$ ln -s jdk-6u20-linux-i586-rpm java
A little bit of explanation here. At the third line, I call the file directly. This will execute the installation file just like when we double click on the exe file on Windows. Just in case you wonder why the file is called directly without any command specified.
In the fourth command, I create a symbolic link to the installation directory. The reason is as explained above, the installation directory will be the name of the file (without the extension) which is long, hard to remember and hard to type. So by creating a symbolic link, I can just use the name of the link every time I want to refer to that directory. For example, to go to that directory, instead of typing: "cd jdk-6u20-linux-i586-rpm.bin", I can just type: "cd java". How cool is that!
6. Install Railo
With JDK installed, we can now move on to the next step: install Railo. There is a slight difference here as the Railo file that we downloaded is a source file (in a zip format) instead of an executable file. That means we cannot call the file directly to execute it but instead we need to compile it or make it. But first of all, we need to extract it.
6.1 Extract Railo
We need to know that path to the file that we downloaded earlier to extract it. If you download it from the link that I provided, the file name will be railo-3.1.1.000-resin-without-jre.tar.gz which is located in the installation file directory. That means the path to the file will be /opt/soft/_install_files/railo-3.1.1.000-resin-without-jre.tar.gz. Similar to the case of the JDK, it will be extracted to a directory of the same name without extension, i.e. railo-3.1.1.000-resin-without-jre. From SSH, type:
$ tar –xf /opt/soft/_install_files/railo-3.1.1.000-resin-without-jre.tar.gz
$ ln -s railo-3.1.1.000-resin-without-jre railo
The commands also created a symbolic link to the new Railo installation directory with the link name railo.
6.2 Make/install Railo
From SSH, type:
$ ./configure -with-java-home=/opt/soft/java --with-apxs=/usr/bin/apxs2
$ make install
If no error occurs, then Railo has been installed and connected to Apache. A module called mod_caucho.so has also been created and put in the right place for that Railo-Apache connection.
6.3 Change the java reference inside Railo httpd.sh
Inside the config file of Railo, there is a reference to the java path installed earlier. However, this is incorrect, probably due to the environment variable not registered correctly. To fix that, we need to change it to be an absolute path.
You can edit the config file directly on Unix or download it onto your computer, change it and reupload it (I prefer this way as I found the editor in Unix very hard to use). If you choose the latter and you are using Windows, make sure you use an editor that supports Unix-mode as stated above. A good and free one is Crimson Editor. Do NOT use Notepad or it will cause errors when you upload it back to the host.
Follow these steps to change the java reference:
- Open (or download to your computer) the config file which is located at /opt/soft/railo/bin/httpd.sh
- Locate the line that says:
Change it to:
java = /opt/soft/java/bin/java
- Save it (or reupload it if you edit on your local)
If you download and reupload the file using Windows. You need to change the file permission again as for some reason, the file permission has been modified during the download/upload process. From SSH:
6.4 Start Railo
If everything went smoothly, you should be able to start Railo now. From SSH:
7. Install domains/name-based hosts
If you have passed all the previous steps without any error, you already have Apache2 and Railo 3.1 installed on your host and they have also been connected successfully. The next step is to install the domain settings. What it does is: let Apache and Railo know that they can expect the following domains coming and where they should redirect the requests to based on the domain name. This will make more sense in case you have multiple domains set up on one host. But if you have only one domain, that is ok, you can still do this and I in fact recommend you to do this as it will help the setup a lot clearer and give you room to plug in another domain (or more) in case you decide to do so in the future. Once this has been set up, you basically have one directory for every site you run on your host and they are independent of each other.
In the following sections, you need to change the domain names and IP address to your actual ones. But to make it easy to explain, let's assume:
- You run 2 domains called mysite1.com and mysite2.com on your host.
- Your host IP address is 188.8.131.52
7.1 Install name-based hosts for Apache2
Go to the directory: /etc/apache2/sites-available/. Create 2 new files called mysite1.com and mysite2.com with the following content. Again, if you are on Windows, make sure you use an editor that supports Unix-mode like Crimson Editor for this, not Notepad.
<VirtualHost 184.108.40.206:80> ServerAdmin email@example.com ServerName mysite1.com ServerAlias www.mysite1.com DocumentRoot /srv/www/mysite1.com/public_html/ ErrorLog /srv/www/mysite1.com/logs/error.log CustomLog /srv/www/mysite1.com/logs/access.log combined </VirtualHost>
<VirtualHost 220.127.116.11:80> ServerAdmin firstname.lastname@example.org ServerName mysite2.com ServerAlias www.mysite2.com DocumentRoot /srv/www/mysite2.com/public_html/ ErrorLog /srv/www/mysite2.com/logs/error.log CustomLog /srv/www/mysite2.com/logs/access.log combined </VirtualHost>
Create the corresponding directories.
$ mkdir /srv/www/mysite1.com/logs
$ mkdir /srv/www/mysite2.com/logs
After you have created the site setting files and their directories, you need to enable them in Apache and reload the server. From SSH:
$ a2ensite mysite2.com
$ /etc/init.d/apache2 reload
(if you receive an error, try to use sudo before the command)
* Credit of this step is given to the help from Linode at http://library.linode.com/lamp-guides/ubuntu-9.10-karmic/.
7.2 Install name-based hosts (web contexts) for Railo
The site settings above are for Apache to know where to grab static files such as .html, .css, .js, images, doc files, pdf files, etc. You need to do the same thing for Railo to tell it where to grab Coldfusion files.
Open the Railo config file at: /opt/soft/railo/conf/resin.conf and look for a section that says:
<host id=""> <root-directory>/var/www</root-directory> <access-log path="logs/access.log"/> <web-app id="" root-directory="htdocs"/> </host>
Add the following code after the above section for mysite1.com:
<!--- MY SITE 1 ---> <host id="mysite1.com"> <host-alias>www.mysite1.com</host-alias> <root-directory>/srv/www/mysite1.com</root-directory> <access-log path="/srv/www/mysite1.com/logs/access.log"/> <web-app id="/" root-directory="public_html"/> </host>
And then this for mysite2.com:
<!--- MY SITE 2 ---> <host id="mysite2.com"> <host-alias>www.mysite2.com</host-alias> <root-directory>/srv/www/mysite2.com</root-directory> <access-log path="/srv/www/mysite2.com/logs/access.log"/> <web-app id="/" root-directory="public_html"/> </host>
Watch out for the opening and closing tags in this config file.
8. Set up index.cfm file
Apache by default does not consider index.cfm as an index file so we need to tell it that.
Open the Apache config file at: /etc/apache2/httpd.conf
Locate the line that says:
Change it to:
DirectoryIndex index.html index.cfm index.php index.shtml
You see I add the index files index.php and index.shtml as well. This is optional but I do that now so that I don't have to add them in the future when I need to. If the line was not there yet, just create it and add it at the bottom of the file.
9. Sum up and testing
This is the end of part 1. By now, you should have Apache and Railo configured correctly. Restart the servers using the following commands:
$ /etc/init.d/apache2 restart
(if you receive an error, try to use sudo)
And you should be able to open your site!
PLEASE NOTE: you might need to change the settings from your Domain Provider to point to the host and it is outside the scope of this article. Without that, you won't be able to open the site at http://yourdomain.com but you should still be able to access it using IP address.
10. Useful commands
This section includes the list of commands you might find useful when working with Railo and Apache. I use sudo here but the command may still work without it depending on what account you login.
To start, stop and restart Railo:
To start, stop and restart Apache:
To check for Apache status:
To enable and disable a site in Apache:
To reload Apache after a site is enabled/disabled:
11. What's next?
In Part 2, I will show you how to install MySQL on your host. This will be a short article (compared to this one!). More importantly, I will show you how to enable remote access to your database so that you can test the live data from your localhost, a feature that I find extremely helpful for testing and debugging with live data.
What do you think about this article? This is my first Coldfusion blog post so there are still a lot of things I need to learn. Please write your comments below if you have any questions about this topic or suggestions of how I could write this better and make it easier to understand. And finally, thanks for reading.