Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

We will explain all the necessary steps to configure a development environment on your computer. The idea is to install a Cytomine instance on your localhost and all the development tools/libraries required so that you can develop and test on your own computer. 

Step 1 - Install the pre-requirements

Cytomine-Core and Cytomine-IMS mainly rely on Java, Groovy and the Grails framework.

Code Block
languagebash
linenumberstrue
sudo apt-get update -y
sudo apt-get install -y git curl linuxsoftware-image-extra-$(uname -r) linux-image-extra-virtual properties-common wget unzip build-essential locate apt-transport-https
software-properties-common ca-certificates g++
 
curlsudo -s "https://get.sdkman.io" | bash
source "/home/{your_home}/.sdkman/bin/sdkman-init.sh"
sdk install groovy 1.8.6
sdk install grails 2.4.4
 
echo "deb http://ppa.launchpad.net/webupd8team/java/ubuntu precise main" | sudo tee -a /etc/apt/sources.list
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys EEA14886
sudo apt-get update
echo oracle-java7-installerecho debconf shared/accepted-oracle-license-v1-1 select true | sudo debconf-set-selections
sudo echo debconf shared/accepted-oracle-license-v1-1 selectseen true | sudo /usr/bin/debconf-set-selections
sudo add-apt-repository -y ppa:webupd8team/java
sudo apt-get update -y
sudo apt-get install -y oracle-java7java8-installer

Edit your .bashrc to export your JAVA_HOME:

Code Block
languagebash
linenumberstrue
export
JAVA_HOME="XXX"

...

echo 'export JAVA_HOME="/usr/lib/jvm/

...

java-8-oracle"

...

' >> .bashrc
 
cd /tmp/ && curl http://get.sdkman.io | bash
sdk install grails 2.4.4
sdk install groovy 2.3.7


Then, check Java and Groovy version:

Code Block
languagebash
linenumberstrue
java -version #(1.78)
groovy -v #(12.83.67)

 

If you prefer, you can visualize the installation with screenshots here.

 

Restart a terminal in order the environment variable $GRAILS_HOME is effective. Fix Grails 2.4.4 to work with Java 8:

Code Block
languagebash
linenumberstrue
wget repo.spring.io/libs-snapshot-local/org/springframework/springloaded/1.2.3.BUILD-SNAPSHOT/springloaded-1.2.3.BUILD-SNAPSHOT.jar -O $GRAILS_HOME/lib/org.springframework/springloaded/jars/springloaded-1.2.1.RELEASE.jar


Step 2 - Install an integrated development 
environment

We recommend to use Intellij IDEA Ultimate Edition. The following considers it is the case.

...

If you prefer you can visualize the installation with screenshots here.

 

Step 3 - Retrieve source code

Download our source code in a local directory (e.g. $HOME/Cytomine/) by cloning Cytomine-core and Cytomine-IMS from our source repository: 

Code Block
languagebash
linenumberstrue
mkdir Cytomine/ ; cd Cytomine/
git clone https://github.com/cytomine/Cytomine-core.git
git clone https://github.com/cytomine/Cytomine-IMS.git

 

Step 4 - Configure projects in Intellij

Import the Cytomine-Core and Cytomine-IMS source project into Intellij, by choosing Maven as external model to import the projects.

...

For more detailed importation of projects if you are not familiar with Intellij, see the screenshots on this page.

 

Step 5 - Create a Dockerized development environment.

One of the main interest of Docker is to have the same environment between developers and final users.

In order to do this and to avoid installation of an additional local machine, we will setup a Dockerized development environment. Follow the two first points of an Automatic Installation with Docker (Download Cytomine-bootstrap and install Docker).

 

Step 6 - Install IMS required libraries (if needed).

If you want develop on IMS, the IMS will run on your machine and you will need all the dependencies of IMS : tiffinfo, identify, vips. You can find into the Dockerfile of IMS the way to install these dependancies. The following commands should be enough to get the related libs:

Code Block
languagebash
linenumberstrue
sudo apt-get -y update
sudo apt-get install -y software-properties-common
sudo add-apt-repository -y ppa:semiosis/ppa 
sudo apt-get -y update 
sudo apt-get install -y ant dnsutils gobject-introspection gtk-doc-tools imagemagick libcairo2-dev libglib2.0-dev libgsf-1-dev libjpeg8-dev libmemcached-dev libopenjpeg-dev libtiff5-dev libtiff-tools libxml2-dev pkg-config swig
sudo apt-get -y build-dep openslide iipimage-server libvips-dev
 
# Openslide
cd /tmp 
git clone https://github.com/openslide/openslide 
cd /tmp/openslide 
sudo autoreconf -i 
sudo ./configure 
sudo make 
sudo make install

# Vips
cd /tmp 
wget https://github.com/jcupitt/libvips/releases/download/v8.5.1/vips-8.5.1.tar.gz 
tar -zxvf ./vips-8.5.1.tar.gz 
cd ./vips-8.5.1 
ldconfig 
sudo LDFLAGS="-L/usr/local/lib -lopenslide" CPPFLAGS="-I/usr/local/include/openslide"  ./configure 
sudo make
sudo make install
 
# Openslide-java
cd /tmp 
git clone https://github.com/cytomine/openslide-java 
cd /tmp/openslide-java 
sudo autoreconf -i 
sudo ./configure 
sudo make 
sudo make install


Step 7 - Update the bootstrap procedure.

Then, in the Bootstrap folder you have downloaded at step 5, make the following changes :

...

Code Block
languagebash
docker stop iipJ2
docker rm -v iipJ2

 

Step 8 - Update your /etc/hosts

Don't forget to update it, if you deploy on local host. If you kept the default configuration, update your /etc/hosts with:

Code Block
languagebash
linenumberstrue
127.0.0.1   localhost-core
127.0.0.1   localhost-ims
127.0.0.1   localhost-ims2
127.0.0.1   localhost-upload
127.0.0.1   localhost-retrieval
127.0.0.1   rabbitmq
127.0.0.1   localhost-iip-base # if IMS dev
127.0.0.1   localhost-iip-jp2000 # if IMS dev
127.0.0.1   localhost-iip-cyto # if IMS dev

 

Step 9 - Last modifications to your IDE

The last modifications need to be done in your development environment (IDE).

...

  • In the Cytomine-ims/grails-app/conf/Config.groovy file, 
    • update the public and private keys of admin, superAdmin, and ImageServer users with the keys generated at previous step.
    • as long as the database is not Dockerized, update the the cytomine.imageServerPrivateKey and cytomine.imageServerPublicKey values by the private and public keys of the username 'ImageServer1' (in the sec_user table) in the database.
  • In IntelliJ, in the "Run" menu toolbar, Go to "Edit configurations" edit the Command Line by "-reloading -Dserver.port=9080 run-app -echoOut --stacktrace -nocoverage --verbose".

Step 10 - Start Docker containers and develop

In Cytomine-boostrap directory, you can now run the script start_dev.sh. This will deploy the Docker containers:

Code Block
sudo ./start_dev.sh 

In IntelliJ, you can now run the Cytomine-core project that will simulate a server at the grails.serverURL mentionned above. So in this example you can now access the core development server at http://CORE_URL:8080 to test your core dev environment. It will rely on other containers installed by Docker but use your own core (and IMS) development container(s).

 

To restart the docker containers while keeping data, use:

Code Block
languagebash
linenumberstrue
sudo ./restart_and_keep_data.sh

 

 

Troubleshooting

  • If you encounter a "java.lang.OutOfMememoryError: PermGen space" error, add the option -XX:+CMSClassUnloadingEnabled to the JVM, when running Cytomine-Core. In Intellij, go to Run > Edit Configurations and add it in the VM options field.
  • If you have an error "org.codehaus.groovy.grails.commons.ConfigurationHolder: class not found" when compiling Cytomine-IMS, edit the file ~/.grails/2.4.4/projects/IMS/plugins/background-thread-1.6/BackgroundThreadGrailsPlugin.groovy, by replacing 

    Code Block
    languagegroovy
    linenumberstrue
    import org.codehaus.groovy.grails.commons.ConfigurationHolder as CH

    by 

    Code Block
    languagegroovy
    linenumberstrue
    import grails.util.Holders as CH
  • As nginx will try to contact your machine, you may need to allow docker containers to contact port 8080 & 9080. Here is the command with UFW

    Code Block
    languagegroovy
    linenumberstrue
    sudo ufw allow from 172.17.0.1/27