Using jettywrapper

These instructions assume that you want to work with jettywrapper via its rake tasks, so the ruby snippets below are meant to be added to your project's Rakefile, along with require 'jettywrapper'.

For information about configuration, see Configuring jettywrapper. Information about installation is in the README.

Gotchas

Jetty may take a while to spin up

Jetty can take quite a while to spin up, especially if it is starting Fedora and Solr as well, per hydra-jetty. For testing, it can be prudent to allow 60 seconds or more for jetty to spin up, especially on a Continuous Integration server. This is accomplished by setting startup_wait in config/jetty.yml:

development:
  startup_wait: 15
test:
  startup_wait: 60

Jetty may not shut down cleanly

Sometimes jetty doesn't shut down properly. One way this can be caused is by interrupting the process using Jettywrapper.wrap, such as running your tests. It is also common to forget that you spun it up manually, or not realize that it didn't shut down.

Sometimes the first you are made aware of it is when your tests fail due to unexpected data conditions, or your dev instance is behaving oddly.

There is a rake task provided to help with this:

rake jetty:status

Or you can check your system directly:

$ ps -eaf | grep jetty

If there is a jetty process running, you can stop it with:

$ rake jetty:stop

If that doesn't work, you can always use the nuclear option and kill jetty manually:

$ pkill -f jetty

What rake tasks are provided by jettywrapper?

To use jettywrapper's rake tasks, in your project's Rakefile add:

require 'jettywrapper'

then run

rake -T

and you will see a number of rake tasks in the jetty namespace.

Working with the zip file

Jettywrapper is designed to expect a packaged jetty instance in a zip file with the web services needed by your project.

The presumption is that you want to download the zip file rarely, but you may want to reset your project's jetty instance as part of testing.

See Configuring jettywrapper for information on how to specify the zip file.

The relevant rake tasks do the obvious things:

rake jetty:download                     # download the jetty zip file
rake jetty:unzip                        # unzip the downloaded jetty archive

This is often one-time setup for a project using jettywrapper.

Setting up jetty for your project

In addition to any configuration params you want to indicate to jettywrapper (see Configuring jettywrapper), you may need to copy project specific configurations to the web services in the jetty instance.

Since you may want to be able to reset your jetty instance to a pristine state as part of testing, it is generally useful to set up a rake task to do this configuration:

namespace :myproj
  desc 'Copies the default SOLR config for the bundled Testing Server'
  task :configure_jetty do
    FileList['solr_conf/conf/*'].each do |f|
      cp("#{f}", 'jetty/solr/blacklight-core/conf/', verbose: true)
    end
  end
end

Starting jetty

$ rake jetty:start

If jetty is already running, there is a task to stop it and restart it:

$ rake jetty:restart

but see Gotcha section above.

Stopping jetty

$ rake jetty:stop

but see Gotcha section above.

Wrapping your code

The Jettywrapper.wrap method will start the jetty server before a block of code and stop the server after the block, which is especially useful for automated testing.

An example rake task:

require 'jettywrapper'

desc 'run the tests for continuous integration'
task ci: ['jetty:clean', 'myproj:configure_jetty'] do
  ENV['environment'] = 'test'
  jetty_params = Jettywrapper.load_config
  jetty_params[:startup_wait] = 60

  error = nil
  error = Jettywrapper.wrap(jetty_params) do
    # run the tests
    Rake::Task['spec'].invoke
  end
  raise "test failures: #{error}" if error
end

Resetting Jetty to pristine state

$ rake jetty:clean

The jetty:clean rake task resets Jetty to a pristine state. It does this by removing the existing instance of Jetty in your project, then unzipping the downloaded zip file with jetty. This also wipes out any project specify changes you made to the jetty instance. You might want a rake task like this:

namespace :myproj
  desc 'wipe and reset jetty'
  task jetty_reset: ['jetty:clean', 'myproj:configure_jetty']
end