Skip to content

Setting up a local development environment on Ubuntu

Jump to bottom
alawvt edited this page Nov 3, 2015 · 1 revision

Instructions for setting up a Local Development Environment (LDE) for VTechWorks on Ubuntu

Purpose

To quote Rachel Andrew's article "A Simple Workflow from Development to Deployment", "When designing and developing your website, you should try to match the live web server as much as possible. This should include ensuring that paths from root don’t change between local and live versions, and that [modules] and permissions are the same in both places. This approach will reduce the possibility of something going wrong as you push the site live. It should also enable you to come back to a site to make changes and updates and know that you can then deploy those changes without breaking the running site. A good local development environment saves you time and stress. It gives you a place to test things out."

Step 1: Install prerequisite tools

Note that you will probably need at least 8Gb of memory on your computer to install and run the following.

  • Download and install VirtualBox for your operating system (Windows, OSX, or Linux). VirtualBox will allow your desktop or laptop computer to function like a web server rather than as a client.
sudo apt-get install virtualbox virtualbox-ext-pack
  • Download and install Vagrant for your operating system. Vagrant is a tool for managing virtual servers such as the one you will create with VirtualBox.
sudo apt-get install vagrant
  • Check permissions on the .vagrant.d directory in your home directory:
ls -al
  • You should be the owner of the directory. If not, run the following command (assuming that "jdoe" is your username on your computer):
sudo chown -R jdoe .vagrant.d/
  • If you are using OS X, install Homebrew. Homebrew is a package manager for OS X that comes with many tools that developers need. To install Homebrew, paste the following at the command line:
ruby -e "(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • Install Ansible. Ansible is a tool that allows automatic configuration and deployment of complex systems like DSpace. If you are using OS X, paste the following at the command line:
sudo apt-get install ansible
  • Install Java and the Java Development Kit (and make sure you do so before you install Maven). Java is the language DSpace is written in, as well as a runtime environment, virtual machine, and development kit for your computer. The following command will also install the Java Development Kit (Oracle JDK). If you are using OS X, paste the following at the command line:
sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java7-installer
sudo apt-get install oracle-java7-set-default
  • Install Maven. Maven is a software management tool that "can manage a project's build, reporting and documentation from a central piece of information." The following command will install version 3.2 of Maven. If you are using OS X, paste the following at the command line:
sudo apt-get install maven

If you find you need another version of Maven, you can use the following commands to install the correct version:

brew unlink maven
brew install homebrew/versions/[maven version here]

Step 2: Make sure you have the necessary authorizations

  • Make sure you can log in to the VT GitLab service at https://git.it.vt.edu. Edit your profile: add an avatar and contact info.

  • Make sure you have a GitHub account and that your account is a member of the Virginia Tech University Library GitHub organization at https://github.com/VTUL.

  • Set up a public SSH key on your machine. The public SSH key is a bit like a password: it allows you to authenticate yourself so that you can make changes to the GitLab codebase from your computer. Follow the instructions at https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key You don't have to create a passphrase when prompted (just hit enter), but if you do, make sure to remember or record it!

  • Open the file id_rsa.pub in a text editor and copy the whole text to your clipboard.

  • Add your public SSH key to the GitLab repo at https://git.it.vt.edu/it-services/vtlibans_dspace. Click on your profile avatar in the top right and then click "Edit Profile Settings", or else go directly to your Profile Settings at https://git.it.vt.edu/profile. Click the 'SSH Keys' tab. Give your SSH Key a title (like "My VT Computer") and then paste in the full text of the file id_rsa.pub. You will need to add an SSH key for every device and application you use to push to GitLab.

  • Add your public SSH key to the GitHub repo at https://github.com/VTUL/vtechworks. Similarly, click on your profile avatar on GitHub, click on "Settings" for your profile, then click on "SSH Keys" on the left. You will need to add an SSH key for every device and application you use to push to GitHub.

Step 3: Get a copy of the codebase

Now that you have all the tools and authorizations necessary to do development on VTechWorks's DSpace code, you need a copy of the code itself.

  • Clone the VTechWorks git repository by pasting the following command:
git clone [email protected]:it-services/vtlibans_dspace.git

This repo is accessible only from Virginia Tech IP addresses.

  • Once you have cloned the vtlibans_dspace repository, go to the directory:
cd vtlibans_dspace

git clone [email protected]:VTUL/vtechworks.git dspace

Note that the Vagrantfile expects VTUL's fork of DSpace to be on your host machine at dspace of your cloned repo. Don't use any other directory name.

(note: you may need to prepend the path to your shared file in Vagrantfile, line 18, for instance,

# add dspcefolder to be synced locally
    dspacedevvm.vm.synced_folder "/Users/alaw/GitHub/vtlibans_dspace/dspace/dspace/target/dspace-installer",
"/usr/share/tomcat7/src/git/DSpace/dspace/target/dspace-installer", type: "rsync"
  • Then, from the vtlibans_dspace directory, clone the DSpace source, and build using Maven.
cp templates/dspacedevvm.local.vt.edu.properties dspace
cd dspace
git checkout vt_5_x_dev
mvn package -Denv=dspacedevvm.local.vt.edu -Dmirage2.on=true
  • Then, from the vtlibans_dspace directory:
cp vars.TEMPLATE.yml vars.yml
vagrant up
  • Go get a cup of coffee! This will take awhile.

Step 4: Set up your Virtual Machine

  • Login to your VM to import localizations.
vagrant ssh
  • We will be deleting the default database to install a sample of records. So, first, stop the Tomcat server.
sudo /usr/sbin/service tomcat7 stop
  • The following steps will require becoming superuser. Make yourself a superuser.
sudo -s
  • Switch to the dspace bin directory.
cd /dspace/bin
  • Empty the demo dspace database. When asked if you want to PERMANENTLY DELETE everything from the database, type 'y' for 'yes.'
./dspace database clean
  • Get a .sql dump of the database and put it in the vtlibans_dspace folder (there is a zipped sample file named 20150616_dspace5_dump.sql in the VTechWorks Team Google Drive folder; this is the example used below).
sudo -u postgres psql dspace < /vagrant/20150616_dspace5_dump.sql
  • Make sure it is the right database.
./dspace database info
  • Update it if needed.
./dspace database migrate
  • Restart the tomcat7 server
sudo /usr/sbin/service tomcat7 restart
  • If you don't see collections or items, you'll need to reindex the database.
sudo -u tomcat7 /dspace/bin/dspace index-discovery -b
sudo /usr/sbin/service tomcat7 restart

  • Congratulations! You can view your installation at http://192.168.60.4

  • When through with session, exit as root, exit as user

exit
exit

Stopping Vagrant

  • Close the virtual machine OR write the contents of the virtual machine's RAM to the host's hard drive OR destroy the whole thing and recreate it from a clean environment (RECOMMENDED)
vagrant destroy #destroys the whole environment and leaves your environment in a clean state (recommended) 
vagrant halt #closes virtual machine or
vagrant suspend #writes contents of virtual machine RAM to host hard drive

Further Resources

  • The How-To Geek. "Command Line Basics". LifeHacker 9/9/10.
  • William E. Shotts Jr. The Linux Command Line. No Starch Press 2012. Available for free online through the VT Library's Safari Books Online subscription.
  • "Try Git". Code School. Free interactive git tutorial.
  • Richard E. Silverman. Git Pocket Guide. O'Reilly Media 2013. Available for free online through the VT Library's Safari Books Online subscription.
  • Mitchell Hashimoto. Vagrant: Up and Running. O'Reilly Media 2013. Available for free online through the VT Library's Safari Books Online subscription.
  • DSpace 5.x Documentation.
Clone this wiki locally