*Deprecated* See https://wiki.duraspace.org/display/VIVODOC/All+Documentation for current documentation

The goal of this tutorial page is for a human with a recent Mac (OS X 10.7.5 here) to setup their VIVO development environment from scratch. At the end of this tutorial, you should have:

  • Eclipse Juno or newer installed
  • Eclipse EGit 2.3 or newer installed
  • Java JDK 7 or newer installed
  • Apache Ant 1.8 or newer installed
  • your very own Vitro remote Git repository ("repo") represented as a Java project in your Eclipse environment
  • your very own VIVO remote Git repo represented as a Java project in your Eclipse environment
  • a local MySQL 5.6 or newer server instance
  • a local Apache Tomcat 7 or newer server instance
  • future? a local Apache HTTP Server instance connected to Tomcat
  • a local VIVO web application
  • future? install Selenium IDE and run existing acceptance tests
  • future? a local SPARQL endpoint
  • future? a local linked data web service
  • future? automating some of this with Homebrew, Boxen, Puppet, Vagrant, or another tool

This process should be similar on a Linux or Windows computer. There are also many ways to skin this cat. Some people don't care to use Eclipse or EGit. You can certainly contribute to the VIVO open source code project using a Git command line tool or the GitHub client application. You can also use a different database, another triple store, and a different Servlet container. It would be great to have other developers "fork" this tutorial, or parts of it, to share alternates approaches and describe their benefits. This is a fork of sorts of the VIVO Release V1.5 Installation Guide with a developer in mind.

The only assumptions, at this point, are that you have courage, some time, and a working GitHub account with an SSH key uploaded (and working SSH access). See https://help.github.com/articles/signing-up-for-a-new-github-account and https://help.github.com/articles/generating-ssh-keys for more information.

Feel free to click/unclick the check boxes below to track your progress. It is unlikely that two humans will be working through this process at the same time, but if you wish, you can fork this wiki page by making a copy. That would also be useful if you are likely to modify the steps if your approach diverges or you plan to use a different tool like Glassfish or a different database/triple store. It might also make sense to break this page up into smaller pages to avoid duplication.

Install Eclipse

  • Download Eclipse from http://www.eclipse.org/downloads/ –  Eclipse IDE for Java EE Developers works for me, and you should start with the latest release (Juno or newer)
  • Install Eclipse download on your Mac
  • Launch Eclipse
  • Go to Help menu and select Check for Updates to confirm your install (you might have upgraded from an older version with 3rd party solutions installed) – restart Eclipse as needed

Install Eclipse EGit

  • Go to Help menu and select Eclipse Marketplace
  • Enter "EGit" in the Find text box and click Go
  • Install EGit - Git Team Provider and you might also install other Git or GitHub solutions if you wish
  • I would recommend restarting Eclipse at this point
  • Go to Eclipse menu and select Preferences...
  • Type "Git" into the search field and select the Git node found under the Team node
  • Make a note of the Default repository folder path for use below

Install Java 7

  • Download Java 7 or newer from http://www.oracle.com/technetwork/java/javase/downloads/index.html – Java SE Development Kit 7 works for me, just make sure you download Tomcat 7 below, as Tomcat 6 and Java 7 don't always get along
  • The JDK disk image, that I downloaded, installed Java 1.7 with minimal interaction. There were no install options and the JDK was placed in /Library/Java/JavaVirtualMachines/jdk1.7.0_21.jdk/Contents/Home on my Mac.
  • Launch the Eclipse application
  • Go to Eclipse menu and select Preferences...
  • Type "JRE" into the search field and select the Installed JREs node found under the Java node
  • Click the Add button to bring up the Add JRE dialog
  • Select the Standard VM JRE Type and click the Next button
  • Click the Directory... button and navigate to your JDK 7 Home folder – click the Open button with that folder selected
  • The JRE home, name and system libraries fields should auto-populate in the Add JRE dialog – if they do not, you probably had the wrong folder selected in the last step
  • You might change the JRE name field to something more descriptive than "Home", e.g. "Java SE 7u21"
  • TODO: Describe updates needed to environment to reference Java 7 instead of default Java in command line - For command line access on mac, I used the information at  http://blog.hgomez.net/blog/2012/07/20/understanding-java-from-command-line-on-osx/.

$ java -version
java version "1.7.0_21"
Java(TM) SE Runtime Environment (build 1.7.0_21-b12)
Java HotSpot(TM) 64-Bit Server VM (build 23.21-b01, mixed mode)

$ which java
/usr/bin/java

Install Apache Ant 1.8

  • Download Ant 1.8 or newer from http://ant.apache.org/bindownload.cgi
  • TODO: I already had Ant 1.8.2 installed, so I didn't install anything at this time (Ant 1.9.0 is available)
  • On Mac, I used macports and installed with the command: sudo port install apache-ant

$ ant -v
Apache Ant(TM) version 1.8.2 compiled on June 3 2011

$ which ant
/usr/bin/ant

Install Vitro source code

  • Go to File menu and select Import...
  • Select the Projects from Git node – there is a GitHub node, but it didn't work for me
  • Select the URI repository source
  • Bring up https://github.com/vivo-project/Vitro (or a different Vitro repo in GitHub) in your browser
  • On the GitHub page, look for a toolbar with HTTP | SSH | Git read-only buttons
  • On the GitHub page, click SSH and copy the URI displayed next to it, e.g. git@github.com:vivo-project/Vitro.git
  • Back in Eclipse, paste the copied text into the URI field in the Source Git Repository dialog, and click the Next button
  • Unless otherwise specified, don't change any of the default branch settings and just click the Next button
  • Unless otherwise specified, don't change any of the default local destination settings and just click the Next button
  • If not selected, select Use the New Project Wizard and click the Finish button
  • In the New Project dialog, select Java Project and click the Next button
  • Uncheck Use default location, click the Browse button, and navigate to your repository folder (see above) and select the new Vitro folder
  • Click the Finish button
  • Go to Project menu and select Properties
  • Select the Java Build Path node
  • Click on the Libraries tab in the main dialog panel and scroll through the list of JARs, looking for JRE System Library
  • Confirm that JRE System Library is referencing the JDK 7 that was installed above – it might help to highlight it in the list, click the Edit... button and verify that Workspace default JRE is selected and reflects your JDK 7 label, e.g. "Java SE 7u21" 

Install VIVO source code

  • Go to File menu and select Import...
  • Select the Projects from Git node – there is a GitHub node, but it didn't work for me
  • Select the URI repository source
  • Bring up https://github.com/vivo-project/VIVO (or a different VIVO repo in GitHub) in your browser
  • On the GitHub page, look for a toolbar with HTTP | SSH | Git read-only buttons
  • On the GitHub page, click SSH and copy the URI displayed next to it, e.g. git@github.com:vivo-project/VIVO.git
  • Back in Eclipse, paste the copied text into the URI field in the Source Git Repository dialog, and click the Next button
  • Unless otherwise specified, don't change any of the default branch settings and just click the Next button
  • Unless otherwise specified, don't change any of the default local destination settings and just click the Next button
  • If not selected, select Use the New Project Wizard and click the Finish button
  • In the New Project dialog, select Java Project and click the Next button
  • Uncheck Use default location, click the Browse button, and navigate to your repository folder (see above) and select the new Vitro folder
  • Click the Finish button
  • Go to Project menu and select Properties
  • Select the Java Build Path node
  • Click on the Projects tab in the main dialog panel and click the Add... button
  • Select the Vitro project and click the OK button
  • Click on the Libraries tab in the main dialog panel and click the Add JARs... button
  • Remaining on the Libraries tab, scroll through the list of JARs, looking for JRE System Library
  • Confirm that JRE System Library is referencing the JDK 7 that was installed above – it might help to highlight it in the list, click the Edit... button and verify that Workspace default JRE is selected and reflects your JDK 7 label, e.g. "Java SE 7u21"
  • Drill down to the Vitro | webapp | lib folder, select all of the JARs in that folder, then click the OK button
  • Look for any red 'X' indicating any remaining errors, or bring up the Problems view which is accessed from the Window | Show View menu – there should be none at this stage

Install MySQL

  • Download MySQL Community Server from http://dev.mysql.com/downloads/ – I downloaded the DMG format, and you may also wish to download the MySQL Workbench for some visual tools
  • Install the main MySQL package, e.g. mysql-5.6.11-osx10.7-x86_64.pkg
  • Optionally install MySQL.prefPane or MySQLStartupItem.pkg depending on whether you'd like the MySQL server instance to launch on system startup
  • If you won't be starting MySQL automatically, then you'll have to launch the server process from the command line or using the MySQL app in System Preferences. You can also use that app to check the current status of the server instance.

Also see MySQL configuration, tuning, and troubleshooting, VIVO Database Server Setup and Localhost Only Webserver Configuration

Install Apache Tomcat

Build VIVO and deploy

  • No labels

*Deprecated* See https://wiki.duraspace.org/display/VIVODOC/All+Documentation for current documentation