Resources for Dicoogle users and developers.

Building Dicoogle

Dicoogle is an open-source project. The official sources are hosted on GitHub here. This page provides instructions on building Dicoogle from the official sources.

Dicoogle is licensed under the GNU General Public License v3.0

According to this license, you are free to use, modify, and distribute Dicoogle, including modified versions. Nevertheless, certain conditions must be met to preserve this freedom:

Permissions of this strong copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license.
Copyright and license notices must be preserved.
Contributors provide an express grant of patent rights.

When in doubt, please consult the official GNU General Public License v3.0 website.

Before building, please make sure that your system contains the following tools:

Java JDK, either Oracle or OpenJDK (at least version 7; JDK 8 is recommended). This package contains the necessary parts for building Java programs.
Maven 3. We use Maven to retrieve dependencies and execute scripts for building, checking and testing projects.
Git, to retrieve the source code from the official repository.

Retrieve the full source code from the official repository:

git clone https://github.com/bioinformatics-ua/dicoogle.git

Navigate to the project’s base directory, and build the parent Maven project:
```
mvn install
```
You can build Dicoogle without the web application by skipping the npm process:
```
mvn install -Dskip.npm
```
The resulting jar file can be found in “./dicoogle/target”. Plugins are provided separately, and must be compatible with the built version of Dicoogle.

Building and debugging the web application

The web app is located in “dicoogle/src/main/resources/webapp”. It is possible to work on the web application as a separate project, and configure it to use a Dicoogle instance on a different location.

First of all, make sure that Node.js (LTS or Stable) and npm are installed. npm is a popular package manager for JavaScript development, and we’ll be using it to automatically retrieve all of the webapp’s dependencies and build the resulting parts. First of all, you need to call npm install:

npm install

The script above is usually sufficient. Regardless, when the dependencies are already installed, we can invoke specific scripts. To build all resources:

npm run debug        # for development
npm run build        # for production

To build just the css files:

npm run css

To watch for changes in JavaScript resources (good for development):

npm run js:watch

To watch for changes in the SASS resources (thus building css):

npm run css:watch

All of these npm scripts map directly to Gulp tasks. Gulp is the task runner that is currently used by the project.

$ gulp --tasks

 ├── lint
 ├─┬ js
 │ └── lint
 ├─┬ js-debug
 │ └── lint
 ├── js:watch
 ├── html
 ├── html-debug
 ├── css
 ├── css-debug
 ├── css:watch
 ├─┬ production
 │ ├── js
 │ ├── html
 │ └── css
 ├─┬ development
 │ ├── js-debug
 │ ├── html-debug
 │ └── css
 ├── clean
 └─┬ default
   └── production

Running as a standalone server

We have included a script for running a static server containing the standalone webapp. If you already have Python installed, simply execute:

./run_server

Otherwise, many static server applications are available, such as the static-http package:

npm install -g static-http   # install static-http globally
static-http -p 9000          # serve directory

Debugging the webapp

The web application can be tested separately without having it embedded in a jar file. The steps are fairly simple:

Start Dicoogle, locally or on a server: java -jar dicoogle.jar -s. The jar file does not need to contain the web application in this case. You may also need to change your configuration in the config.xml file, so as to enable cross-origin requests:

<server enable="true" port="8080" allowedOrigins="*" />

Navigate to the webapp’s source code. Define the URL to Dicoogle’s base endpoint using the DICOOGLE_BASE_URL environment variable, and bundle the source code:

DICOOGLE_BASE_URL=http://localhost:8080 npm run debug

When the environment variable DICOOGLE_BASE_URL is set, we are instructing our build scripts to use a custom base URL to the server. An update to the web application different server only requires a rebuild of the webapp (and a page refresh in your browser). The server itself does not have to be restarted. See the section above on building scripts section above for more scripts.

Start a static server on the web application’s base folder. If you have Python, the run_server script will do.
Open your browser and navigate to the static server: http://localhost:9000

The difference here is that, while the running Dicoogle instance is hosted at http://localhost:8080, the web application is actually served in http://localhost:9000. REST operations to the server will be properly directed.

Back