Installation of the Shepherd Project Framework is relatively simple, but it does involve installation of a web server, which many users may be unfamiliar with. The following link is to a 13 minute video that summarize the full installation process. We recommend watching the video and following along on your home PC.
To run the framework, you will need a Windows, Mac or Linux laptop or desktop with the following software pre-installed:
- Java SE 6 or 7 (a.k.a, “Java 1.6” or “Java 1.7”). These are available from Oracle. At a minimum, download and install the Java Runtime Environment (JRE); if you wish to develop Java programs, download and install the Java Development Kit (JDK), which includes the JRE. Don't forget to define JAVA_HOME as a system environment variable (settings its value to the file system path to Java on your computer) to allow Java-based applications to use your installed Java version.
- Tomcat 6 or 7, which is available from the Apache Software Foundation. Download the “binary distribution” that is appropriate for your operating system (e.g., “64-bit Windows zip” for 64-bit Windows machines, or “zip” or “tar.gz” for Linux and Macintosh machines). Tomcat is a “servlet container” that can run Java-based applications under a web server. It can also act as a web server by itself. Jetty, older versions of Tomcat, and other J2EE containers/servers may work but have not been tested. Integration of Tomcat with third party web servers (e.g., Apache 2.2.x) is common, but this topic is well beyond the scope of these instructions. These sample instructions assume that Tomcat has been installed on your local laptop or desktop and is listening on port 8080.
Installing Tomcat is beyond the scope of this document, but it is very well documented on the web:
- For Windows operating systems, Tomcat can be downloaded with Windows installers, making the installation process very easy.
- For Macintosh hardware, these instructions are excellent. Use Apple's “Terminal” app to type the various “sudo” commands shown in the instructions.
- Tomcat is very well supported for Linux, but instructions for downloading and installing will vary according to Linux flavor. Consult your Linux distro (you may already have Tomcat) or the Web for Tomcat installation instructions for your Linux platform.
The Framework is downloaded and deployed as a web application archive file (.WAR) in Tomcat. To install this file:
- Using your web browser, download the latest available WAR file (shepherd-XXXXX.war) from the downloads page. For example, version 3.3.0 of the Shepherd project is deployed through the war file ''shepherd-3.3.0-RELEASE.war''.
- Place the WAR file in the "webapps" folder of Tomcat. For example, if your WAR file is named "shepherd-3.3.0-RELEASE.war":
- If you installed Tomcat to "C:\Program Files\Apache Software Foundation\Tomcat" on Windows, then you would place the WAR file in the folder "C:\Program Files\Apache Software Foundation\Tomcat\webapps". The folder "C:\Program Files\Apache Software Foundation\Tomcat\webapps\shepherd-3.3.0-RELEASE" will be created when Tomcat is (re)started.
- On a Macintosh, following the Tomcat installation instructions above, you would type "mv ~/Downloads/shepherd-3.3.0-RELEASE.war /Library/Tomcat/webapps" in a Terminal window.
- Open a web browser to the following address:
http://localhost:8080/shepherd-XXXXXFor example, if your WAR file is named "shepherd-3.3.0-RELEASE.war", then the URL to use is
http://localhost:8080/shepherd-3.3.0-RELEASE/.A default landing page for the Shepherd Project Framework is displayed. This steps assumes a basic Tomcat installation on a laptop or desk top (i.e., not a web server) with Tomcat assigned to use its default port 8080. If you are using Tomcat on a web server or assigned it to a different port, you will need to specify that port and use the appropriate URL . Further configuration of the framework is also required to support non-localhost URLs and ports.
- Log into the framework using the default 'tomcat' user ID and 'tomcat123' password.
The Shepherd Project Framework is now ready for use. Keep in mind that Tomcat must be running to enable access to the Framework through your Web browser. If Tomcat is stopped, or your computer is rebooted, Tomcat must be restarted as described above.