The bioacoustic workbench server. Manages the structure and audio data. Provides an API for client access.

Documentation Code Climate Test Coverage


master (latest release)

Build Status Documentation Status Coverage Status

develop (most recent commits)

Build Status Documentation Status Coverage Status


This project's dev environment is managed by Vagrant and Ansible. Ensure Vagrant v1.8.1 or greater is installed on your dev machine.

Audio processing and other long-running tasks are performed using baw-workers.


See the document for guidelines on making changes.

Environment Setup

Clone this repo, then change directory to your cloned directory and on your host machine run

$ vagrant up

This will prepare a complete development environment. To see what is involved in the setup, look at the provision/vagrant.yml and bin/setup files.


To reprovision your environment, on your host machine run:

$ vagrant provision


$ vagrant up --provision

Destroy your environment

If you wish to remove the baw-server development environment completely, on your host machine run:

$ vagrant destroy

This will completely delete the development VM.


Start by running, on your host machine:

$ vagrant up
$ vagrant ssh
# in the dev machine
$ cd ~/baw-server

Sometimes you may need to update dependencies first:

~/baw-server$ bundle install

End by suspending the virtual machine:

# exit the ssh session
$ exit
# on the host machine:
$ vagrant halt

When running the server in development or test modes, these configuration files will be used:

  • /config/settings/development.yml
  • /config/settings/test.yml

They are based on /config/settings/default.yml.

Web Server

To start the development server

$ thin start


The tests are run using Guard, either:

$ bin/guard

or in case the listening does not work, force the use of file polling:

$ bin/guard guard --force-polling

Press enter to execute all tests. Guard will monitor for changes and the relevant tests will be run as files are modified.

Tests can also be run with a specified seed using rspec:

$ rspec --seed <number>


Use this style guide as a reference:


Documentation can be generated from tests using rspec_api_documentation:

$ bin/rake docs:generate GENERATE_DOC=true

Other commands

These commands should be executed automatically but are listed because they are helpful to know.

  • Create the test database: bin/rake db:create RAILS_ENV=test
  • Then migrate and seed the test database: bin/rake db:migrate db:seed RAILS_ENV=test
  • Prepare the local development database:bin/rake db:setup RAILS_ENV=development
  • Run rspec tests: bin/rspec
  • Generate API documentation: bin/rake docs:generate GENERATE_DOC=true

Production setup and deploying

Create production settings file config/settings/production.yml based on config/settings/default.yml.
Create staging settings file config/settings/staging.yml based on config/settings/default.yml.

We deploy using Ansible (and in particular Ansistrano). Our Ansible playbooks are currently private but we have plans to release them.

If you want to use background workers, you'll need to set up Redis.

Working with RubyMine

If using a remote setup (i.e. vagrant) make sure you set up a remote Ruby SDK using the RVM instructions.

If you need sudo to install a gem (i.e. if Rubymine can't do it) try running rvm fix-permissions.


This project was originally created and maintained by @cofiem - all the amazing things it does are a credit to them.


Apache License, Version 2.0