LA Development Guide

• Introduction
• Install basic dependencies
• Install sdkman
• Install maven
• Clone the ALA module you are interested in
• Install grails
• Basic build
• Install Intellij or similar
• Import the ALA module in Intellij
• Development configuration
• Development databases
• More information

Introduction

This is an unofficial guide to setup and ALA development environment and start to contribute to ALA code base and adapt it to your needs.

Disclaimer: Software forks and custom code changes are sometimes quite easy to do, but quite hard to maintain, even for Google. So we recommend to try to generalize your software customizations and send Pull Requests to ALA repositories, so your code can be useful to other LA nodes (and also maintained by all of us).

Install basic dependencies

sudo apt install curl git openjdk-8-jdk
sudo update-java-alternatives -s java-1.8.0-openjdk-amd64

Install sdkman

Install sdkman:

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk version

Install maven

Some ALA modules are build with maven (like biocache-store):

sudo apt install maven

Clone the ALA module you are interested in

In this guide we'll use ala-bie as sample:

git clone https://github.com/AtlasOfLivingAustralia/ala-bie.git
cd ala-bie

Install grails

Install the grails version that uses the ALA module you are interested in:

grep grailsVersion gradle.properties
# Doing this in our cloned module ala-bie shows that nowadays grailsVersion=3.2.11 so:

sdk install grails 3.2.11

Basic build

Let's do a basic build to download dependencies and test the repository building before modify any code:

# in ala-bie
./gradlew build
Downloading https://services.gradle.org/distributions/gradle-3.4.1-all.zip
(...)
Finished Precompiling Assets
:compileWebappGroovyPages NO-SOURCE
:compileGroovyPages
:bootRepackage
:assemble
:processTestResources NO-SOURCE
:testClasses UP-TO-DATE
:test NO-SOURCE
:check UP-TO-DATE
:build

BUILD SUCCESSFUL

Total time: 10 mins 0.015 secs

The war should be in:

ls build/libs/
ala-bie-1.4.20.war  ala-bie-1.4.20.war.original

Install Intellij or similar

Following some tutorial, install an IDE like intellij:

sudo snap install intellij-idea-community --classic

Run Intellij from Ubuntu "Activities" and choose default options, like suggested plugins.

Import the ALA module in Intellij

In our example, as ala-bie is a grails project, check the Intellij documentation about Creating Grails Application from Existing Code.

Select "Import project" in main Intellij dialog:

In your project structure select build.grandle file:

Intellij will index, compile and build our code:

Now you can run your project:

In many cases this will fail because we need some LA module configuration (similar to the one created by ansible in /data/*/config/ and also access to some database (depending on the module).

Some LA modules don't require db connections (like regions, or biocache-hub) so we can point our development configuration to some production biocache-service, spatial, etc to do our dev tests.

Development configuration

Your LA module will look to /data for configuration properties like in production. So we need to generate some configuration.

A fast way to generate many of these configurations is to use ansible, locally with the help of the LA ansible generator:

https://github.com/living-atlases/generator-living-atlas/wiki/Generating-updated-LA-configuration-properties-files

Development databases

You need some local database (mysql, postgresql, mongo, etc) to run your LA module correctly in local, but exists other options like to have some VM, vagrant or docker environment. Also you can tunnel you db connections via ssh.

Some ALA modules are using docker to get a development database easily, for instance:

• https://github.com/AtlasOfLivingAustralia/spatial-service#running-it-locally
• https://github.com/AtlasOfLivingAustralia/image-service#running-it-locally

Other option if you have a test LA enviroment you can use their database. For this you can tunel your mysql connections (for instance) via ssh:

ssh -L 33060:127.0.0.1:3306 ubuntu@your_la_demo -N -f

and setup that port in your deve configuration:

dataSource.url=jdbc\:mysql\://localhost:33060/specieslists?autoReconnect=true&connectTimeout=0&useUnicode=true&characterEncoding=UTF-8

Don't forget to match your mysql user & password with those configured in your LA test environment.

You can use this also to tunnel solr and cassandra conections.

More information

See Development-Resources for more LA development wiki pages and more related information.