Running locally for testing or development

Geographic visualisation tool for bat recordings with GAUNO data, eg from Wildlife Acoustics

Download .zip Download .tar.gz

Running locally for testing or development

These instructions should work on a Mac or Linux box. I’ve added a few Mac shortcuts as that’s the system I’m working on.

It should be technically possible to run this under Windows, but I don’t have a machine to test that on.


Before you start, you’ll need a copy of Docker running on your system:

Visit, and download, install and run “Docker Desktop” for your system. You may need to create an account to be able to download Docker.


First, get a copy of the code - either:

Then, change into that directory in the console

cd batbox

prepare your settings file,

cp batbox/ batbox/

and open it in a text editor (Mac console shortcut: open -e batbox/

To enable the maps in the site, you’ll need a token from Mapbox. These are free for personal use.

To get one, visit in your browser and follow thw instructions - you may need to create an account first.

(Mac console shortcut: open

You’ll also need a long, random string to set as the SECRET_KEY. The easiest way to generate this on Mac or Linux is to type:

openssl rand -hex 50

and copy the result into your editor. Once you’ve changed those two lines, save and close the editor.

Adding your recordings

Copy your bat recording audio files into webroot/media/sessions inside the project directory. The layout doesn’t matter so long as all your WAVs are somewhere in the sessions folder.

Adding species data

The software can use the species list from to provide full latin and common names for the species detected. Download a copy of the CSV file from that site (either all species, or just bats) and save it as data/asm-species.csv (you’ll probably have to rename the file). It will be processed when the server starts.

Run the code

Once you’ve done the above once, you can start here every time you want to run the code.

In the project folder, run:


And wait. The first time you run, a local server is built that runs the code; the build isn’t needed on subsequent runs.

Once the server is built, it’ll analyse and load your audio files. Any time you add files, just stop the server and run ./ again and they’ll be found.

Finally, it’ll start the server. Once you see:

## You should now be able to access the project at

you can open your browser and visit that address.

To access the admin part of the site, you’ll need an admin password. The setup process creates this automatically - look in FIRSTPASS.txt in the project directory once the project has built. The username that goes with this is admin.

If you have problems

First, check that you’ve not missed any steps out above. Then, feel free to open an issue in Github at

Finally, a note for developers

What you’ve built above is exactly the environment that the code is developed in - with one exception. The default server for the above environment doesn’t reload the code when you edit it, so you won’t see any changes as you edit files. Instructions on how to run the development server locally can be found in [].