Merge pull request #16 from hardyoyo/DS-1663-add-documentation-and-ex…

…amples

Ds 1663 add documentation and examples

README.md

@@ -111,6 +111,54 @@ The following Vagrant plugins are not required, but they do make using Vagrant a
 * Vagrant-Proxyconf: http://vagrantplugins.com/plugins/vagrant-proxyconf/
 * Vagrant-VBox-Snapshot: http://vagrantplugins.com/plugins/vagrant-vbox-snapshot/
 
+How to Tweak Things to your Liking?
+-----------------------------------
+
+local.yaml
+----------
+
+If you look at the config folder, there are a few files you'll be interested in. The first is common.yaml, it's a [Hiera](http://projects.puppetlabs.com/projects/hiera) configuration file. You may copy this file to one named local.yaml. Any changes to local.yaml will override the defaults set in the common.yaml file. The local.yaml file is ignored in .gitignore, so you won't accidentally commit it. Here are the options:
+
+* git_repo - it would be a good idea to point this to your own fork of DSpace
+* git_branch - if you're constantly working on another brach than master, you can change it here
+* mvn_params - add other maven prameters here (this is added to the Vagrant user's profile, so these options are always on whenever you run mvn as the Vagrant user
+* ant_installer_dir - until we figure out how to have the installer just run from whatever version of DSpace is in the target folder produced by Maven, we'll need to hard code the DSpace version so we can have Puppet look in the right place to run the Ant installer for DSpace
+* admin_firstname - you may want to change this to something more memorable than the demo DSpace user
+* admin_lastname - ditto
+* admin_email - likewise
+* admin_passwd - you probably have a preferred password
+* admin_language - and you my have a language preference, you can set it here
+
+local-bootstrap.sh
+------------------
+
+In the config folder, you will also find a file called local-bootstrap.sh.example. If you copy that file to local-bootstrap.sh and edit it to your liking (it is well-commented) you'll be able to customize your git clone folder to your liking (turning on the color.ui, always pull using rebase, set an upstream github repository, add the ability to fetch pull requests from upstream), as well as automatically batch-load content (an example using AIPs is included, but you're welcome to script whatever you need here... if you come up with something interesting, please consider sharing it with the community). 
+
+local-bootstrap.sh is a "shell provisioner" for Vagrant, and our vagrantfile is [configured to run it](https://github.com/DSpace/vagrant-dspace/blob/master/Vagrantfile#L171) if it is present in the config folder. If you have a fork of Vagrant-DSpace for your own repository management, you may add another shell provisioner, to maintain your own workgroup's customs and configurations. You may find an example of this in the [Vagrant-MOspace](https://github.com/umlso/vagrant-mospace/blob/master/config/mospace-bootstrap.sh) repository.
+
+maven_settings.xml
+------------------
+
+If you've copied the example local-bootstrap.sh file, you may create a config/dotfiles folder, and place a file called maven_settings.xml in it, that file will be copied to /home/vagrant/.m2/settings.xml every time the local-bootstrap.sh provisioner is run. This will allow you to further customize your Maven builds. One handy (though somewhat dangerous) thing to add to your settings.xml file is the following profile:
+<code>
+                <profile>
+                        <id>sign</id>
+                        <activation>
+                                <activeByDefault>true</activeByDefault>
+                        </activation>
+                        <properties>
+                                <gpg.passphrase>add-your-passphrase-here-if-you-dare</gpg.passphrase>
+                        </properties>
+                </profile>
+</code>
+
+NOTE: any file in config/dotfiles is ignored by Git, so you won't accidentally commit it. But, still, putting your GPG passphrase in a plain text file might be viewed by some as foolish. If you elect to not add this profile, and you DO want to sign an artifact created by Maven using GPG, you'll need to enter your GPG passphrase quickly and consistently. Choose your poison.
+
+vim and .vimrc
+--------------
+
+Another optional config/dotfiles folder which is copied (if it exists) by the example local-bootstrap.sh shell provisioner is config/dotfiles/vimrc (/home/vagrant/.vimrc) and config/dotfiles/vim (/home/vagrant/.vim). Populating these will allow you to customize Vim to your heart's content. 
+
 What's Next?
 ------------
 

Vagrantfile

@@ -61,7 +61,7 @@ Vagrant.configure("2") do |config|
 
     # The url from where the 'config.vm.box' box will be fetched if it
     # doesn't already exist on the user's system.
-    config.vm.box_url = "http://files.vagrantup.com/precise64.box"
+    config.vm.box_url = "http://github.com/DSpace/vagrantbox-ubuntu/releases/download/v1.1/precise64.box"
 
     # Hostname for virtual machine
     config.vm.hostname = "dspace.vagrant.dev"
@@ -88,6 +88,10 @@ Vagrant.configure("2") do |config|
     # then tell Vagrant to use the next available port between 8081 and 8100
     config.vm.usable_port_range = 8081..8100
 
+    # name this machine
+    config.vm.define :dspace do |t|
+    end 
+
     # Turn on SSH forwarding (so that 'vagrant ssh' has access to your local SSH keys, and you can use your local SSH keys to access GitHub, etc.)
     config.ssh.forward_agent = true
 
@@ -132,6 +136,11 @@ Vagrant.configure("2") do |config|
         shell.args = %q{/etc/sudoers.d/root_ssh_agent "Defaults    env_keep += \"SSH_AUTH_SOCK\""}
     end
 
+    # Shell script to set apt sources.list to something appropriate (close to
+    # you, and actually up, via apt-spy2
+    config.vm.provision :shell, :inline => "echo '   > > > running apt-spy-2-bootstrap.sh, do not worry if it shows an error, it will be OK, there is a fallback.'"
+    config.vm.provision :shell, :path => "apt-spy-2-bootstrap.sh"
+
     # Shell script to initialize latest Puppet on VM
     # Borrowed from https://github.com/hashicorp/puppet-bootstrap/
     config.vm.provision :shell, :path => "puppet-bootstrap-ubuntu.sh"
@@ -142,6 +151,17 @@ Vagrant.configure("2") do |config|
     config.vm.provision :shell, :path => "librarian-puppet-bootstrap.sh"
 
     # Call our Puppet initialization script
+    config.vm.provision :shell, :inline => "echo '   > > > beginning puppet provisioning, this will appear to hang...'"
+    config.vm.provision :shell, :inline => "echo '   > > > PATIENCE! output is only shown after each step completes...'"
+
+    # display the local.yaml file, if it exists, to give us a chance to back out
+    # before waiting for this vagrant up to complete
+
+    if File.exists?("config/local.yaml")
+        config.vm.provision :shell, :inline => "echo '   > > > using the following local.yaml data, if this is not correct, control-c now...'"
+        config.vm.provision :shell, :inline => "echo '---BEGIN local.yaml ---' && cat /vagrant/config/local.yaml && echo '--- END local.yaml -----'"
+    end
+
     config.vm.provision :puppet do |puppet|
         # Set some custom "facts" for Puppet manifest(s)/modules to use.
         puppet.facter = {
@@ -169,8 +189,8 @@ Vagrant.configure("2") do |config|
 
 
     if File.exists?("config/local-bootstrap.sh")
+        config.vm.provision :shell, :inline => "echo '   > > > running config/local_bootstrap.sh'"
         config.vm.provision :shell, :path => "config/local-bootstrap.sh"
-        config.vm.provision :shell, :inline => "echo 'running config/local_bootstrap.sh'"
     end
 
     #############################################

apt-spy-2-bootstrap.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+
+# apt-spy-2-bootstrap.sh
+# Uses the Ruby gem apt-spy2 to ensure the apt sources.list file is configured appropriately for this location, and that it selects mirrors that are currently functional
+
+# figure out the two-letter country code for the current locale, based on IP address
+
+export CURRENTIP=`curl -s http://ipecho.net/plain`
+
+#TODO verify that you actually have an IP address there, and not some evil text
+
+export COUNTRY=`geoiplookup $CURRENTIP | awk -F:\  '{print $2}' | sed 's/,.*//'`
+
+#TODO verify that country code, and use US if it doesn't look reasonable
+
+if [ "$(gem search -i apt-spy2)" = "false" ]; then
+  gem install apt-spy2
+  apt-spy2 fix --launchpad --commit --country=$COUNTRY ; true
+else
+  apt-spy2 fix --launchpad --commit --country=$COUNTRY ; true
+fi

config/.gitignore

@@ -2,3 +2,4 @@
 !common.yaml
 *.yaml
 local-bootstrap.sh
+dotfiles

config/common.yaml

@@ -4,7 +4,7 @@ git_repo          : 'git@github.com:DSpace/DSpace.git'
 git_branch        : 'master'
 mvn_params        : '-Denv=vagrant'
 
-ant_installer_dir : '/home/vagrant/dspace-src/dspace/target/dspace-4.0-SNAPSHOT-build'
+ant_installer_dir : '/home/vagrant/dspace-src/dspace/target/dspace-4.0-rc4-SNAPSHOT-build'
 admin_firstname   : 'DSpaceDemo'
 admin_lastname    : 'Admin'
 admin_email       : 'dspacedemo+admin@gmail.com'

config/local-bootstrap.sh.example

@@ -15,10 +15,10 @@ CONTENT="/vagrant/content"
 HOME="/home/vagrant"
 DSPACE_HOME="$HOME/dspace"
 DSPACE="$DSPACE_HOME/dspace"
-DSPACE-SRC="$DSPACE_HOME-src"
+DSPACESRC="$DSPACE_HOME-src"
 
 ## START OFF BY CUSTOMIZING THE GIT CLONE ##
-cd $DSPACE-SRC
+cd $DSPACESRC
 
 # set git to allways rebase when we pull (using sudo to run as the vagrant user, since this script runs as root)
 sudo -i -u vagrant git config --global --bool pull.rebase true
@@ -32,24 +32,70 @@ sudo -i -u vagrant git config --global core.autocrlf input
 # and I don't need merge backups, really, I don't
 sudo -i -u vagrant git config --global --bool merge.keepbackups false
 
-# use the simple push, which means you have to be explicit about the branch you're pushing, which is a good thing, stop with all the smarts
-sudo -i -u vagrant git config --global push.default simple
-
-
 echo "and now setting up my preferences for my working copy... adding an upstream remote, PR refs..." 
 
-
 # add an upstream remote
 git remote add upstream git@github.com:DSpace/DSpace.git
 
 # enable fetching of pull requests from upstream (this may or may not be common practice, but it's handy, why not try it out?)
 git config --add remote.upstream.fetch +refs/pull/*/head:refs/remotes/upstream/pr/*
 
+# Git-smart is super helpful, especially for git newbies, and is worth installing just for smart-log
+echo "installing git-smart"
+sudo /opt/vagrant_ruby/bin/gem install git-smart
+
+# BASH inputrc customization 
+if [ -f "/vagrant/config/dotfiles/inputrc" ]; then
+    echo "setting up BASH inputrc file"
+    sudo -i -u vagrant cp /vagrant/config/dotfiles/inputrc /home/vagrant/.inputrc
+fi
+
+# Vim customization
+
+# copy vimrc if it exists
+if [ -f "/vagrant/config/dotfiles/vimrc" ]; then
+    echo "setting up .vimrc file"
+    sudo -i -u vagrant cp /vagrant/config/dotfiles/vimrc /home/vagrant/.vimrc
+fi
+
+# copy vim folder and its contents if they exists
+if [ -d "/vagrant/config/dotfiles/vim" ]; then
+    echo "copying .vim settings folder"
+    sudo -i -u vagrant cp -r /vagrant/config/dotfiles/vim /home/vagrant/.vim
+    echo "creating .vimbackups folder"
+    sudo -i -u vagrant mkdir /home/vagrant/.vimbackups
+fi
+
+# MORE dotfiles
+
+# copy GPG keys and trust files if they exist
+if [ -d "/vagrant/config/dotfiles/gnupg" ]; then
+   echo "copying GPG keys and trust files..."
+   sudo -i -u vagrant cp -r /vagrant/config/dotfiles/gnupg /home/vagrant/.gnupg
+fi
+
+# copy maven settings.xml if it exists
+if [ -f "/vagrant/config/dotfiles/maven_settings.xml" ]; then
+   echo "copying Maven settings.xml file..."
+   sudo -i -u vagrant cp /vagrant/config/dotfiles/maven_settings.xml /home/vagrant/.m2/settings.xml
+fi
+
+# NOTE: if you want more dotfiles installed, you'll need to specifically copy them, following
+# the examples above. We do this so that we only install files with intention, and don't
+# blindly install a config file. We recommend being cautious and only attempt to copy
+# files and directories if they exist (use the -f and -d tests).
+
+
 ## now add content ##
 
+# NOTE: this will only work if the SITE AIP file is named the same as the handle prefix
+# configured for this Vagrant-DSpace workspace (check vagrant.properties in dspace-src). By
+# default it's the same prefix as the demo.dspace.org server, as DSpace Committers have
+# ready access to the AIP files used to populate demo.dspace.org, and we can use
+# Vagrant-DSpace to create more such AIPs. Demo's handle prefix is 10673.
+
 SITE=`echo $CONTENT/SITE@* | cut -f1 -d' '`
-if [ -n "$SITE" ]
-then
+if [ -n "$SITE" ]; then
    echo "Recursively installing content from AIPs at $CONTENT (starting with $SITE AIP)" 
 
           # let's get the handle from this site AIP
@@ -66,15 +112,15 @@ then
           echo "" 
 
    cd $HOME
-   sudo -i -u vagrant /home/vagrant/dspace/bin/dspace packager  -u -r -a -f -t AIP -e $WHO -i $SH -o skipIfParentMissing=true -o createMetadataFields=true $SITE
+   sudo -i -u vagrant $DSPACECMD packager  -u -r -a -f -t AIP -e $WHO -i $SH -o skipIfParentMissing=true -o createMetadataFields=true $SITE
 	# ----------------------------------------------
-	# Re-index content
+	# Re-index content -- only necessary for DSpace 3.x and earlier
 	# ----------------------------------------------
 
-	echo "Reindexing all content in DSpace..."
-	$DSPACE index-init
+	#echo "Reindexing all content in DSpace..."
+	#/home/vagrant/dspace/bin/dspace index-init
 
-	echo ""
+	#echo ""
 
 	# --------------------------------------
 	# Start up Tomcat
@@ -88,7 +134,7 @@ then
 	# --------------------------------------
 	echo "Rebuilding Discovery (Solr) Indexes..."
 	# Note: the '-f' option tells Discovery to force a reindex of everything and remove docs which no longer exist
-	$DSPACE update-discovery-index -f
+	/home/vagrant/dspace/bin/dspace index-discovery -f
 
 	echo ""
 	echo ""