How to install Zuul if you don't know anything about all this computer stuff?

Zuul is a web application. This means you need a server that runs Zuul, and a browser to access Zuul. For running Zuul that means that you have to start the server to start Zuul and stop it to shutdown Zuul. Simply quitting your browser will not shutdown Zuul!

Updating Zuul

If you already installed Zuul before and just want to update it, start with the "Installation Process" below. To keep all the data you already put into Zuul, simply use the folder you created before in the configuration of Zuul.

System Requirements

You need the following software to be installed on your computer:

  • Java 6 or higher
  • A servlet container such as Apache Tomcat (http://tomcat.apache.org/). Zuul was developed and tested on Apache Tomcat 6.0.

This means you need to download Apache Tomcat (that is the server) from here. Under "Binary Distributions" select a download that fits your system. E.g. the zip-file for OSX or 32-bit/64-bit Windows Service Installer for Windows.

If you're using a Windows computer simply run the installer and that should take care of everything (see this tutorial for help). If you using a Mac, move the unzipped folder (probably named apache-tomcat-6.0.35 or similar) to your Applications folder. You then have to make certain scripts in the bin folder of your apache-tomcat folder executable. To do that do the following:

  1. Open the Terminal application located in Applications/Utilities.
  2. Type cd and then drag and drop the folder named "bin" in your Tomcat installation director (/Applications/apche-tomcat-6.0.3X) in your Terminal, so that you have something like: cd /Applications/apache-tomcat-6.0.35/bin
  3. Hit enter.
  4. To check if that worked, you can type pwd and hit enter, the terminal should show you the path to the bin folder in your Tomcat directory.
  5. Now type chmod u+x *.sh and hit enter.
  6. To check if this command worked type ls -l and hit enter. You should get something like shown below.

    Note that in the beginning of each line that is returned from the last commend (ls -l), every line that ends with a file that has the ending ".sh" starts with -rwxr--r--@. The "x" is the important part here. If your output looks like that, you're good to go.

Installation Process

To install Zuul three steps are necessary: download Zuul, deploy Zuul, and configure Zuul. In the following each step is described in more detail.

Download

Download the latest release of Zuul from here.

That should download a file named zuul-vX.Y.war. Save that file in a folder in your file system and rename it to zuul.war.

Deploy Zuul

To deploy Zuul means that you will add the Zuul web application to your server (Tomcat). Tomcat will take care of executing Zuul, so that you can access it via a browser. To deploy Zuul, copy the file zuul.war that you downloaded and renamed into the webapps folder of your Tomcat directory (e.g. OSX: /Applications/apache-tomcat-6.0.36/webapps, Windows: C:\Program Files\Apache Software Foundation\Tomcat 6.0 unless you chose a different installation directory).

You now need to start Tomcat. For more help also see here.

OS X

To start Tomcat on a Mac, do the following:

  • Go to the bin folder of your Tomcat installation (e.g. /Applications/apache-tomcat-6.0.36/bin).
  • Right-click on the file startup.sh, and choose "Open With..." and then "Other".
  • Find the folder "Utilities" in your "Applications" folder. Make sure that you select "All Applications" from the drop-down menu below the files list.
  • Select the program "Terminal.app" and click "Open". A terminal window should open and you should see something similar to the picture below.
  • To check if Tomcat started up correctly, point your browser to http://localhost:8080/. If everything worked you should see the Tomcat welcome page. Note that "localhost" is your own computer. You can compare "localhost" to the name of the street in which Tomcat is living. "8080" is called the port at which Tomcat is running. You can think of the port as the house number of Tomcat.

Windows

To start Tomcat on Windows, do the following:

  • Go to the bin folder of your Tomcat installation (e.g. C:\Program Files\Apache Software Foundation\Tomcat 6.0).
  • Depending on which installation you chose you should either have a script called startup.bat or a file named Tomcat6w.exe. You should be able to start either of them by double-clicking. Also see here under "Windows XP" for more help.
  • To check if Tomcat started up correctly, point your browser to http://localhost:8080/. If everything worked you should see the Tomcat welcome page. Note that "localhost" is your own computer. You can compare "localhost" to the name of the street in which Tomcat is living. "8080" is called the port at which Tomcat is running. You can think of the port as the house number of Tomcat.

Configure Zuul

The next step is to configure Zuul. To do that, you first need to stop Tomcat again. On startup, Tomcat should have unpacked Zuul and your Tomcat's webapp folder should now have a folder called "zuul" in it. To stop Tomcat run the script shutdown.sh (OSX), or shutdown.bat or stopping Tomcat's exe (service). the same way that you ran the script startup.sh (via "Open With..." Terminal).

You need a folder somewhere in your file system for Zuul to store all its files. The folder can be anywhere (e.g. on your Desktop or in your home directory). Call that folder for instance "zuul." In that folder create another folder "files."

Next, find the following files in the folder webapps/zuul in your Tomcat directory and adjust them as described below.

db4o-config.xml

To configure the path to the database files, open the file db4o-config.xml that is located in the folder WEB-INF/spring. In the XML file find the section that defines the database files paths and replace the value for "databasePath" with the full path to the folder where the database files should be stored. That path would be the path to the folder you just created (e.g. OSX: /yourhomedir/Desktop/zuul, or C:\yourhomedir\zuul) You should do that for three files. Make sure that you keep the file names in the end (e.g. users.db). Also, ensure that the database folder is modifiable by the servlet container.

<!-- Database paths --> <bean id="userDatabaseManager" class="edu.asu.zuul.db4o.DatabaseManager" init-method="init" destroy-method="close"> <property name="databasePath" value="/path/to/zuul/storage/users.db" /> </bean>

Change the italic part in value="/path/to/zuul/storage/users.db" to your path to Zuul's folder.

storage.properties

To configure the path to the folder in which Zuul stores uploaded folders, open the file storage.properties located in WEB-INF/classes/conf. Add the path to a folder for Zuul to store uploaded files, e.g. OSX: /yourhomedir/Desktop/zuul/files, or Windows \\C:\\yourhomedir\\zuul\files (modify the italic part). Note that on Windows you need to use two backslashes (instead of one like in the xml file), and the path needs to start with two backslashes as well.

_storage_path=/path/to/zuul/storage/files

spring-security.xml

To configure the admin password open the file spring-security.xml in the folder WEB-INF/spring and change it as needed. The relevent code is around line 47. You can add more admin accounts by adding additional user tags. You don't need to do this if your running Zuul on your laptop or desktop computer and not as web application.

<user name="admin" password="password" authorities="ROLE_ZUUL_ADMIN" />

Restart Zuul

Almost done. Now the only thing left to do is restarting Tomcat. Run the startup.sh (OSX), startup.bat or the exe (Windows) the same way that you did before.

Your Zuul instance is running on http://localhost:8080/zuul.