DSpace + Vagrant。快速启动虚拟机(通过Vagrant),即“DSpace development ready”
Vagrant can be used to spin up a temporary Virtual Machine (VM) in a variety of providers (VirtualBox, VMWare, Amazon AWS, etc).
Simply put, ‘vagrant-dspace’ uses Vagrant and Puppet to auto-install latest DSpace on the VM provider of your choice (though so far we’ve mostly tested with VirtualBox).
Some example use cases for ‘vagrant-dspace’:
vagrant destroy; vagrant up
)This work began as a collaborative project between tdonohue and hardyoyo,
but has now been more broadly accepted.
BIG WARNING: THIS IS STILL A WORK IN PROGRESS. YOUR MILEAGE MAY VARY. NEVER USE THIS IN PRODUCTION.
‘vagrant-dspace’ does all of the following for you:
master
by default)~/dspace-src
on the VM is synced to [vagrant-dspace]/dspace-src
on your host machine. This allows for IDE-based development. But, it’s disabled by default (as it has slow performance)Most of the magic happens in our Vagrantfile
which tells vagrant how to setup the VM.
However, the Puppet modules are all installed using librarian-puppet, see our Puppetfile
.
If you want to help, please do. We’d prefer solutions using Puppet.
WINDOWS INSTRUCTIONS: detailed step-by-step installation instructions for setting up Vagrant-DSpace on Windows can be found in the docs
folder.
git clone git@github.com:DSpace/vagrant-dspace.git
cd [vagrant-dspace]/
vagrant up
http://localhost:8080/xmlui/
or http://localhost:8080/jspui/
in your local web browser to see if it worked! More info below on what to expect.config/local.yaml
(see below for more details)Once complete, you’ll have a fresh Ubuntu VM that you can SSH into by simply typing vagrant ssh
. Since SSH Forwarding is enabled, that Ubuntu VM should have access to your local SSH keys, which allows you to immediately use Git/GitHub.
NOTE: sometimes when vagrant up
finishes running, you will see a message like this:
Booting VM...
SSH connection was refused! This usually happens if the VM failed to
boot properly. Some steps to try to fix this: First, try reloading your
VM with 'vagrant reload', since a simple restart sometimes fixes things.
If that doesn't work, destroy your VM and recreate it with a 'vagrant destroy'
followed by a 'vagrant up'. If that doesn't work, contact a Vagrant
maintainer (support channels listed on the website) for more assistance.
This is normal, the VM just took a while longer to boot than Vagrant wanted to wait. Don’t lose hope, you can still run vagrant ssh
and very likely the machine will be ready for you. Especially if you’ve wandered off during the vagrant up
command.
http://localhost:8080/xmlui/
or http://localhost:8080/jspui/
from your local web browserconfig/local.yaml
file, see below)dspacedemo+admin@gmail.com
, Default Pwd: ‘vagrant’~/dspace-src/
) and Java/Maven/Ant/Git installed.sync_src_to_host=true
in your config/local.yaml
, then this VM directory will also be synce to [vagrant-dspace]/dspace-src
on your host machine. ~/dspace/webapps/
. The full DSpace installation is at ~/dspace/
.http://localhost:8080/probe/
If you want to destroy the VM at anytime (and start fresh again), just run vagrant destroy
.
No worries, you can always recreate a new VM from scratch with another vagrant up
.
As you develop with ‘vagrant-dspace’, from time to time you may want to run a vagrant destroy
cycle (followed by a fresh vagrant up
), just to confirm that the Vagrant setup is still doing exactly what you want it to do.
This cleans out any old experiments and starts fresh with a new base image. If you’re just using vagrant-dspace for dspace development, this isn’t advice for you.
But, if you’re working on contributing back to vagrant-dspace, do try this from time to time, just to sanity-check your Vagrant and Puppet scripts.
Here’s some common activities which you may wish to perform in vagrant-dspace
:
sudo service tomcat7 restart
sudo service postgresql restart
psql -h localhost -U dspace dspace
(Password is “dspace”)cd ~/dspace-src/
(Move into source directory)mvn clean package
(Rebuild/Recompile DSpace)cd dspace/target/dspace-installer
(Move into the newly built installer directory)ant update
(Redeploy changes to ~/dspace/)sudo service tomcat7 restart
(Reboot Tomcat)If you look at the config
folder, there are a few files you’ll be interested in. The first is default.yaml
, it’s a YAML configuration file (which is loaded by Vagrantfile to configure Vagrant, as well as loaded by Hiera to configure Puppet). You may copy this file to one named local.yaml
. Any changes to local.yaml
will override the defaults set in the default.yaml
file. The local.yaml
file is ignored in .gitignore
, so you won’t accidentally commit it. Here are the basic options (see the default.yaml
for more):
vm_name
- Name of the Virtual Machine to create (default is usually fine)vm_memory
- Specify the amount of memory to give this VM (2GB by default)vm_cpu_max
- Limit the amount of local CPU this VM can access (off by default)ip_address
- Local IP address to assign to the VMport
- Local port this VM should use for Tomcat (port 8080 by default)db_port
- Local port where VM’s PostgreSQL database will be accessible (port 5432 by default). This lets you manage the VM database locally via tools like pgAdminIII, and debug code in your local IDE while using the VM database for “test” data.sync_src_to_host
- Whether or not to auto-sync the ~/dspace-src/
folder on the VM to the [vagrant-dspace]/dspace-src/
folder on your host machine. By default this is false as the sync folder currently is often slow. But, if you want to work in a local IDE, you probably will want this to be set to “true”.dspace::git_repo
- it would be a good idea to point this to your own fork of DSpace. By default this is a GitHub SSH URL. But, if vagrant-dspace is unable to connect to GitHub via SSH, this will be dynamically changed to a GitHub HTTPS URL.dspace::git_branch
- if you’re constantly working on another brach than master, you can change it heredspace::admin_firstname
- you may want to change this to something more memorable than the demo DSpace userdspace::admin_lastname
- dittodspace::admin_email
- likewisedspace::admin_passwd
- you probably have a preferred passworddspace::admin_language
- and you may have a language preference, you can set it heredspace::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)dspace::handle_prefix
- Handle prefix to use for the DSpace in your VM (Default=123456789
). This is handy to set if you want to auto-load content using local-bootstrap.sh
(see below).dspace::catalina_opts
- the default CATALINA_OPTS setting for Tomcat. This allows you to tweak the amount of memory available to Tomcat (1GB by default)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, 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 repository.
Apt-spy2 is used to locate a nearby apt repository mirror, which should help speed up the startup of your VM (as packages should download more quickly).
The default apt-spy-2-bootstraph.sh
script can be copied to the config
folder and modified to reflect your preferences. This can potentially speed up provisiong of new machines by allowing you to tweak the apt-spy2
commands to better fit your typical work conditions. We of course recommend using the default, especially if you do not know for sure where your travels may take you next. But, you are free to tinker with this script as you see fit.
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:
<profile>
<id>sign</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
<gpg.passphrase>add-your-passphrase-here-if-you-dare</gpg.passphrase>
</properties>
</profile>
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.
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)[http://www.vim.org/] to your heart’s content.
Vagrant has a robust community of plugin developers, and some of the plugins are quite nice. Installing a Vagrant plugin is simple.
The following Vagrant plugin is required, if you use the default ubuntu/xenial base box (in other words, if you don’t change the default, you’ll need this plugin).
The following Vagrant plugins are not required, but they do make using Vagrant and vagrant-dspace more enjoyable.
vagrant plugin install vagrant-vbguest
Here are a few things we’d like to explore in future version of vagrant-dspace:
Bugs / Issues or requests for enhancements can be reported via the DSpace Issue Tracker. Please select the “vagrant-dspace” component when creating your ticket in the issue tracker.
We also encourage you to submit Pull Requests with any recommended changes/fixes. As it is, the vagrant-dspace
project is really just a labor of love, and we can use help in making it better.
This work is licensed under the DSpace BSD 3-Clause License, which is just a standard BSD 3-Clause License.