In this article I decided to come back with another tutorial, however I will drift away from the common paradigm of the previous ones, which was the software development, and let’s perform some administrative tasks. Let’s start from the beginning, I was several days ago surfing through the JBoss.org website and it didn’t take too long to arrive to something called OpenShift, the Red Hat’s PaaS open-source cloud. I’m always curious about new technologies and I’ve been following (and giving a try) to several PaaS providers in the last year and this time it wasn’t different than the previous ones so I wanted to give it a go.
One of the things I most liked from OpenShift is that it allows you to create your own infrastructure with several ready-to-go applications that can be running in a matter of seconds after a couple of clicks. The current set is a bit limited but they will be adding more from time to time and, if you are one of those that can’t wait, there is a “do-it-by-yourself” option that provides you with a blank repository that you can use to install any HTTP enabled application. And that’s the reason why I’m writing this tutorial.
We already know how systems behave when we try to get beyond the “supported features”, even when that system provides with a valid mechanism to do it, sooner or later you’ll face the limitations that will make you give up at the end and look in a different direction. I decided for an easy challenge: deploy YouTrack as a standalone server. I decided for YouTrack for several reasons: first, I like it; second: it’s lightweight and would fit perfectly into the OpenShift limitations; third: it is distributed as a single jar file, so easy to install, easy to wrap. The result was quite good and it turned out to be easier than what I thought, If you want to try it on your own, steps follow, try to stick with them and it will be quite straightforward.
Well, obviously we need the YouTrack application since it’s the main purpose of this “challenge”. However there are some tools that will be needed to interact with our OpenShift server. Windows users in particular will need to install Git for Windows and an SSH client. For the latter I would recommend all the family of tools provided by the PuTTY team from Cambridge: PuTTY, Pageant and PuTTYgen will be essential. Unix (and similar SOs) won’t need too much more from a basic installation. Basically ensure you have the Open-SSH and Git clients installed at your system. Besides, since we will using Git a lot I suggest to any newbie to have a Git guide at hand at all times during this tutorial.
Setting up your OpenShift account
So, here we go, let’s get started! The first obvious thing to do is to get an account at OpenShift so go straight there and create yours, it’s free and you can cancel it at any time if at the end you decide to not use it anymore.
Go to the OpenShift website, click on the “SIGN UP – IT’S FREE” link and fill the form with an email, password and captcha:
During the registration process you will be asked for an application namespace, all applications on OpenShift are hosted as subdomains of openshift.com, the application namespace is an identifier that gets appended to all your applications to avoid name collisions.
Once finished a screen like the following will appear at your browser:
Choose the Do It Yourself option and choose a name for your application, that name will be appended by a dash (“-”) and the application namespace that you have chosen in the previous step.
At the end of this process OpenShift will create a a Git remote repository accessible via SSH and that is the place in which we have to put our application files to get our application accessible via HTTP. So, since the communication protocol is SSH we need a pair of SSH keys. Go to “My Account” and find at the right of the screen a section where your are shown with your current SSH public keys.
If you don’t have one you should follow next steps to add it to your account. Without that keys you won’t be able to access your repository.
Adding SSH public keys
As you could see in previous screen shot, there is button that says “Add a new key…”, click on it and you will be asked for the details in a form like the following one:
Key name is an arbitrary name that you will use as an identifier for your key. Since we might be using more than one computer to connect to our repository OpenShift allows us to store more than one public SSH key. Getting your SSH keys will be different depending on which Operating System are you using. For instance, users of the different members of the *nix OS family, just need to open a command shell, type the following and complete the details when asked:
$ssh-keygen -t rsa
That will generate a pair of files in a .ssh folder at your home directory: id_rsa (private key) and id_rsa.pub (public key). What matters here is the contents of the latter as it is your public SSH key. Copy it to your clipboard and paste it into the previous form.
In the other hand, Windows users can use PuTTYgen to generate their keys. The application will ask the user to move the mouse randomly in front of the application window for a short period of time to end up showing a long string compound of characters, numbers and symbols. That’s you public SSH key. Copy it to the clipboard and paste it into the previous form (don’t forget to save your private key file as you will need it later).
Getting your feet wet
Ok, so now we are ready to start building the application that’s going to be deployed into our OpenShift Gear. The first step is to clone the Git repository that OpenShift has set up for us. First of all, go to your OpenShift applications and click on the “YouTrack” application. You should reach a view like the following:
You should find there the specific URL that will give you access to the Git repository at OpenShift. Open a command line terminal (or the graphical tool or you preference) and issue following command to clone it and get your working copy:
$git clone ssh://<your openshift id>@youtrack-<your application namespace>.rhcloud.com/~/git/youtrack.git/
Note: Windows users need to use the utility Pageant and load the previous generated SSH private key file with it. Program will run in the background with a set of pre-loaded SSH private keys that will be used by other SSH-enabled applications.
You’ll end up with an almost empty working copy on your local machine. This working copy contains a very simple Ruby sample application inside a diy folder which opens an HTTP socket. Additionally, there is an empty misc folder and a hidden .openshift one. The latter is the real important one, that folder is used internally by OpenShift to hook actions like build, deploy/undeploy and start/stop your application or cron jobs. The repository comes with some really basic scripts that we will need to modify later to get the application working.
We won’t need any cron job in this setup so we are going to pay attention to just the ones at .openshift/action_hooks. The set of provided scripts at that folder are executed every time we push changes into the remote repository as follows:
- stop: if there is a previous installation it must be stopped before we deploy the new version. OpenShift executes this script as the first step to disable the running application.
- pre_build: executed right before trying to build your application. Its purpose is to prepare the build, perform cleanup tasks, etc.
- build: the build script itself.
- deploy: any special actions to be done to deploy your application? put them all in that script, it will be executed once it has been successfully built.
- post_deploy: its name is almost self explanatory, executed right after your application has been deployed.
- start: the script that will make your application live again after the new deployment.
Since we are going to deploy just binary files and shell scripts, the only important scripts for us will be start and stop.
To avoid having port conflicts when deploying our application, I recommend to make a small change in the provided hook scripts that will disable that sample application provided, just in case it’s running in the server. This small change is as simple as commenting out (pre-pending a # symbol) in the line that starts that application at the .openshift/action_hooks/start script. Right after doing that we need to commit and push the changes into the remote repository, this is done issuing following git commands in a terminal window:
$git add .openshift/action_hooks/start $git commit -m "disabling sample application" $git push
When pushing previous changes OpenShift will execute the scripts contained in the .openshift/action_hooks folder in the previous specified order stopping the sample application provided and doing nothing else. Once finished a good practice is to make same modifications we did to the start script to the stop one, but we don’t need to push the changes again, committing them in our local working copy would be enough for now.
Note: Sample application at the diy folder is no longer needed, so we can remove it from the repository along with the misc folder. Just remember that you are working in a distributed version control system and thus you will need to issue git commands after every change you do. Using a graphical tool will ease those tasks and it’s the better way until you are used to the way Git handles the different versions, branches, etc.
Eager to start with the good stuff? Now it’s the moment, we have a clean working copy now so there is no other application that may interfere in with the new one. If you didn’t download the YouTrack binaries now it’s the moment to do so. YouTrack is distributed as a single JAR executable file with an embedded Jetty server in it, we can run it right after being downloaded without any additional setup and test it’s working typing “http://localhost:8080” in the address field of our preferred browser.
However we want to run it in a server as a daemon so we can’t use as it is, some changes will be needed to get it perfectly working in our OpenShift Gear. There is a good guide about how to use the Java Service Wrapper to daemonise it and we can use it as a starting point. I’m not going to repeat all the steps documented in that guide in this article, I suggest to the reader to start the installation as a local service the same way it’s documented in that guide but with the following small set of changes:
- Rename the youtrack_initd.template file to youtrack-server.sh and place it inside the bin folder of the standalone root directory instead of the /etc/init.d one suggested in that document as we don’t have access to that system folder in OpenShift.
- Perform sensible modifications to the previous mentioned file so every system-specific variable it’s pointing to the right place in your local machine.
- Comment out the line: RUN_AS_USER=youtrack.
Note: YouTrack Stand-Alone Installation Guide on Linux assumes that you will be using a 64 bits box but, at the time this article was written, OpenShift just provides a 32 bits box so be aware of that when downloading the correct version of the Java Service Wrapper. It’s highly recommended that Windows users use a Linux emulator like Cygwin when following that guide since the application is going to be deployed on a Linux box and the installation process is quite different on Windows machines.
Once local installation is finished we should have a standalone folder inside our YouTrack repository with a youtrack-server.sh script file inside a bin folder. This is a good moment to locally commit all the new files into our local repository but we should test if this local installation works before pushing any changes to the server. Issue a youtrack-server.sh start command, then use your browser to open the http://localhost:8080 URL, you should see the YouTrack application running; right? ok, stop the application with a youtrack-server.sh stop command, it’s enough for now but don’t push your changes yet.
The Cloud Side
Ok, we reached a sort of milestone in our process: we have successfully daemonised YouTrack in our local machine. But this isn’t enough to get it working in our OpenShift Gear. As I said, YouTrack comes ready-to-run out of the box, it’s pre-configured in way that will try to bind to the 8080 port in all available addresses at the machine where it is running. However OpenShift won’t allow us to listen at a random port in all available addresses, in fact it just allows us to listen to a specific port in a specific IP address. At the time this article was written the port is 8080 and the IP may vary from one application to another. It happens that the provided port by OpenShift is the same that YouTrack will use as default but we must consider that as a coincidence and we shouldn’t rely on the fact that it won’t change in the future.
Both IP address and port are already configured in our OpenShift Gear as environment variables so we are able to know which are the exactly ones for our specific application. Changing the port YouTrack uses to listen for HTTP request is as easy as adding a command line parameter to the launch command (i.e.: java -jar youtrack-<version>.jar 8081) but changing the address used to listen for those HTTP request is not as straight forward as that. It’s important to find a way to tell YouTrack which is the IP address it must use since we won’t be able to reach the application without it.
In the other hand, we must remember that we are deploying a application to be run in a cloud. Applications ran in those kind of environments are usually deployed on volatile chrooted folders, which means that any files and/or data used by the application and stored in its own repository will be removed and cleaned up after each deployment (or when it needs to scale to a new instance). All the persistent data/files must be stored in a persistent repository instead of the one used by the application itself (the volatile one). This allows for easy scalability of our application: when it needs to scale, just the application binaries are replicated in a new cloudified repository but having access to the persistent storage where the data of other instances has been saved and thus, allowing the new instance to offer us with same data without us noticing that we are connected to a different instance of the same application.
There is a set of environment variables that we must use to configure our YouTrack instance in order to enable it work properly on a cloudified environment. Those variables are as follows:
- OPENSHIFT_INTERNAL_IP: It gives us the exact IP address that our application must use to listen for HTTP requests.
- OPENSHIFT_INTERNAL_PORT: The HTTP port that our application must use when binding the HTTP socket.
- OPENSHIFT_REPO_DIR: Absolute path on the server to our application repository (the volatile one).
- OPENSHIFT_DATA_DIR: Absolute path on the server to the folder that represents the persistent storage. This is the place where files and data used by our application at runtime must be placed.
- OPENSHIFT_LOG_DIR: Absolute path on the server to the folder were to put the application log files.
- OPENSHIFT_RUNTIME_DIR: Absolute path on the server to the folder where to put pid files and related stuff.
- OPENSHIFT_TMP_DIR: Absolute path on the server to the folder where to store the temporary files.
Note: There are more environment variables defined in our OpenShift Gear but we will just using there previous mentioned ones.
So now it’s the moment to perform some modifications to our local YouTrack installation to make it able to use those variables and thus to be properly cloudified.
Getting into the stage
Did I already say that you should commit your changes to your local working copy? I think so, let’s do it now before starting to make changes if you didn’t do it before. We won’t be able to test locally the new changes unless we define all the above environment variables in our local machine. Committing the files won’t upload them to the server until we push all the commits but will allow us to revert back to our previous state in which the application was properly running.
The first place where we need to start making changes is the youtrack-server.sh launch script:
- Replace the value of the JAVA_HOME variable to point to /usr/lib/jvm/java.
- Replace the value of the CATALINA_HOME variable to point to $OPENSHIFT_REPO_DIR/standalone.
- Replace the value of the TMP_DIR variable to point to $OPENSHIFT_TMP_DIR.
- Replace the value of the PIDDIR variable to point to $OPENSHIFT_RUNTIME_DIR variable.
- Replace the value of the LOCKDIR variable to point to $OPENSHIFT_RUNTIME_DIR variable.
Basically, we just did some minor changes now regarding some important system folders that our application will be using but nothing regarding IP addresses or HTTP ports yet, there still are much more changes to do. Our next step is to create a Jetty configuration file that will provide the embedded server with the configuration needed to listen to a specific IP and port. I named that file server.xml (you can name it as you want) and put it in the conf folder inside the standalone root directory (that’s the recommended place where to put it).
Contents for that server.xml file should be as follows:
<Configure id="standalone-server" class="org.eclipse.jetty.server.Server"> <Call name="addConnector"> <Arg> <New class="org.eclipse.jetty.server.bio.SocketConnector"> <Set name="port"> <SystemProperty name="openshift.internal.port" default="8080" /> </Set> <Set name="headerBufferSize">10240</Set> <Set name="host"> <SystemProperty name="openshift.internal.ip" default="localhost" /> </Set> <Set name="forwarded">true</Set> <Set name="threadPool"> <New class="org.eclipse.jetty.util.thread.QueuedThreadPool"> <Set name="minThreads">20</Set> <Set name="maxThreads">100</Set> </New> </Set> </New> </Arg> </Call> </Configure>
And now we need to modify the Java Service Wrapper configuration file (wrapper.conf placed at the same folder we put the server.xml) so the wrapper can provide the YouTrack installation with the previous created configuration file and some other minor changes needed to link our installation to the persistent storage folder given by OpenShift:
- Replace the value of the wrapper.java.classpath.1 property to be: %OPENSHIFT_REPO_DIR%/standalone/lib/wrapper.jar
- Replace the value of the wrapper.java.library.path.1 property to be: %OPENSHIFT_REPO_DIR%/lib
- You’ll find a set of parameters to pass to the JVM defined as wrapper.java.additional.X, the value for the one defining the catalina.base system property should be changed to %OPENSHIFT_DATA_DIR%. YouTrack uses that system property to know where to create a folder in which all the persistent data will be stored.
- Add following additional system properties to pass to the JVM:
- openshift.internal.ip as %OPENSHIFT_INTERNAL_IP%
- openshift.internal.port as %OPENSHIFT_INTERNAL_PORT%
- There is another set of parameters defined as wrapper.app.parameter.Xwhich is used to pass parameters to the running application instead of the JVM. We will need to make following changes in that set in order to get it working:
- Replace the value of the wrapper.app.parameter.2 property to be %OPENSHIFT_INTERNAL_PORT%.
- Add an additional parameter to provide the running application with the previously created server.xml file. To value to pass by should be %OPENSHIFT_REPO_DIR%/standalone/conf/server.xml.
- Replace the value of the wrapper.logfile property to be %OPENSHIFT_LOG_DIR%/wrapper.log.
Right, that has been a lot of stuff, it’s highly recommended to test it locally but that just can be possible if we define all used variables in our local machine. I will skip that part here and in the next section we will move into our server. Once you are happy with your “cloudified” local installation commit all the changes in the local working copy of your repository.
Testing the Setup
With all the previous steps done, to test if the installation will work as it should we need to push the previous commits into the remote repository, since it’s the first time we push the whole installation it will take a while to upload the approx. 40 MB. During the upload process we will see how OpenShift will invoke the hook scripts located under .openshift/action_hooks, since right now those scripts are empty (or with all its statements commented out) they won’t do anything for us. At this moment we will just test if the application is able to start and serve HTTP requests and then will do a couple of small modifications in those hook scripts so the application can be started automatically thus enabling it for being scalable in the cloud.
To make the application start we will need to do a remote SSH login into the OpenShift box and invoke the youtrack-server.sh script manually. The SSH command & URL to access the server can be found at the OpenShift site, at the same page where we already found the Git URL to the repository, let’s get into that page again to get that URL:
Note: Windows users will need a SSH client like PuTTY to perform the remote SSH login or, if they have a Cygwin installation (or something similar) the can use the same command shown in the above screenshot.
Once we are inside the box we must get into the youtrack/repo/standalone/bin folder and launch the server:
$cd youtrack/repo/standalone/bin $./youtrack-server.sh start
Right after this let’s get into the $OPENSHIFT_LOG_DIR folder to have any feedback about the starting process:
$cd $OPENSHIFT_LOG_DIR $tail -f wrapper.log
And we should see a line like the following one:
INFO | jvm 1 | 2012/06/30 11:05:45 | 2012-06-30 11:05:45.200:INFO::Started SocketConnector@192.168.12.32:8080
Now it’s the moment to check it it’s finally working fine or not: we will use our browser to access the YouTrack external URL and we should be able to access the web application. Although we have bound our server instance to a specific IP and port we won’t be pointing our browser to neither both of those values because OpenShift uses an internal proxy instance that redirects all HTTP request against the application external URL to the local chrooted instance we have just installed. That external URL instance will be different depending of the application namespace that you have chosen when configuring your OpenShift account. The one that I’ll be using will be http://youtrack-codenibbles.rhcloud.com. Open your browser, enter your application external URL and wait a bit to the application to come up, since this is our first installation it may take a while to start as YouTrack needs to perform several automatic setup steps on the first run.
So, did it work? could you see your YouTrack application running? Great! If you couldn’t then check that all the files in your local working copy have been uploaded to the server and do a review of all the previous steps, check that you didn’t skip none of them and do the test again.
To finish the whole setup we need now to configure the OpenShift hook scripts so the application can be started and stopped automatically by OpenShift. Go to your local working copy under .openshift/action_hooks and modify you start script as follows:
nohup $OPENSHIFT_REPO_DIR/standalone/bin/youtrack-server.sh start > $OPENSHIFT_LOG_DIR/launcher.log 2>&1
Now modify the stop script adding following line (before the exit 0 statement):
nohup $OPENSHIFT_REPO_DIR/standalone/bin/youtrack-server.sh stop >> $OPENSHIFT_LOG_DIR/launcher.log 2>&1
As we could see, the guys at Red Hat are making a great effort to provide the community with a place where to put their web applications and let them scale in the cloud as the demand rises without the need of performing tedious administrative tasks. In my honest opinion, the greatest thing in OpenShift is this do-it-yourself option that anyone can use to deploy applications not supported out-of-the-box, which is a very interesting feature by the way even though the amount of resources provided without charge are quite limited.
In this tutorial we went through all the steps required to deploy an application which is as simple to install as YouTrack is, more complex applications will require more work but I hope that this tutorial can provide you with a good start point when trying to deploy you own ones. Enjoy!
Cloudify YouTrack on OpenShift by Code Nibbles, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.