Versions Compared

Key

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

The Brown Dog Data Transformation Service (DTS) is a highly extensible/distributed service providing a uniform means of managing and accessing transformation capabilities within the web.   Utilized tools can come in the form of command line applications, GUI driven applications, libraries, and/or other services.   Here we go over the process of preparing a new transformation tool, either an extractor or a converter, for usage with the DTS.

Using the BD Development Base

BD-base runs the necessary dockerized Brown Dog Data Transformation Service components (Clowder, Polyglot, Fence, RabbitMQ, MongoDB, Redis, an example extractor, an example converter, and the BD CLI) allowing a developer to get up and running more quickly as they create and debug new extractors/converters. You can get the BD-base by cloning the git repo:

Code Block
git clone https://opensource.ncsa.illinois.edu/bitbucket/scm/bd/bd-base.git

or download the VirtualBox VM image and run it:

https://browndog.ncsa.illinois.edu/downloads/bd-base.ova

After downloading BD-base, users can simply run the bash script in the command-line to start up the BD development base.

Code Block
cd bd-base 
./bd

The BD-base script will split your terminal into panes and start each of the services needed for the Brown Dog DTS. This provides a useful and convenient way to view the logs of running services in panes. 

Image Added

Extractors

...

Users can switch between panes using Tmux commands.  The panes are as follows: Fence (top), Clowder (middle-left), example extractor (middle-right), Polyglot (middle-left), example convert (middle-right), and the BD CLI (bottom). In the bottom pane, users can run BD-CLI commands to interact with the Brown Dog Data Transformation Service (username: bd, password: browndog):

Image Added


Image Added

CTRL-b <arrow key> will navigate panes.
Exit the bd-base session by typing CTRL-b then :kill-session.
NOTE: There is a .tmux.conf file included in bd-base. If you copy this file into your home directory before starting a bd-base session you will be able to navigate panes via the mouse and end the session by typing CTRL-b then CTRL-c.

Extractors

Here we describe the process for taking a working piece of code and deploying it as a Brown Dog Extractor.  It extractor. For simplicity, it is assumed that the method can be invoked from a single call.  In In this example, we are using the python extractor wrapper and will invoke a python function.  In In a very similar fashion, a method developed in a language other than python can be invoked using subprocess.

...

  1. Wrap the tool for use as an extractor in Clowder (and through that Brown Dog)
  2. Dockerize the extractor
  3. Deploy the extractor
  4. Add the extractor to the Tools Catalog

A few assumptions are that you have a tool that extracts some kind of metadata from a file or dataset and that you have installed Python, Git, and Docker as well as any other specific software needed by your extractor (if any) on your computer.

...

Install pyClowder2, which is a Python library that helps to easily communicate with Clowder - the backend services service of Brown Dog which handles extractions. The advantage of using this library is that it manages all communications with Clowder and RabbitMQ (the distributed messaging bus) and the developer doesn't have to take care of such tasks. Needless to say, an extractor can also be written in native Python without the use of pyClowder2, but it would be more time consuming.could be more 

Code Block
themeConfluence
pip install --upgrade pip
pip install -r https://opensource.ncsa.illinois.edu/bitbucket/projects/CATS/repos/pyclowder2/raw/requirements.txt git+https://opensource.ncsa.illinois.edu/stashbitbucket/scm/cats/pyclowderpyclowder2.git

2. Get Your Code Together

We have developed a template extractor written in Python. It is a simple wordcount word count extractor that counts lines, words, and characters in a text file. Clone the template extractor and rename the directory to an appropriate name that reflects the purpose of your extractor.

...

Make changes to extractors.py (main program). Consider the process_file method as the main method of an extractor and accordingly it needs to contain the main logic. You can call other methods in your python code from this method after importing necessary modules into this file.


3. Edit

...

Edit extractor configuration file config.py:

  1. Change the rabbitmq queue name - in this case replace "wordCount" with an appropriate name for your extractor

  2. Change the messageType field to reflect the MIME type(s) of the file for which you are writing the extractor
  3. Update other fields like rabbitmqURL, rabbitmqExchange, sslVerify, to include
  4. If your extractor needs other custom parameters, they need to be added to config.py

Image Removed

4. Edit extractor.info.json

...

extractor_info.json

This file contains information about the extractor in JSON-LD format. Update all relevant fields as needed.

Image Added

4. Configuration Parameters

Extractors obtain the configuration details required to connect to RabbitMQ, Clowder, etc., either from command-line arguments or environment variables. If you look at the Dockerfile inside the termplate extractor directory you can see some of the environment variables being set.  For the purpose of running your extractor using BD Development Base, you DO NOT have to change anything.

Note: The remaining part of this section is relevant ONLY if you want to run your extractor against another production instance at some other location. Otherwise, you can skip and continue reading the next section.

If you are planning to run your extractor using Docker, you will need to modify the Dockerfile to set the environment variables as required.

Image Added

Otherwise, if you run your extractor as a standalone program (outside of Docker), you will need to set the relevant command-line arguments. You can get a list of these parameters by running your extractor with the help option (-h, --help).

Image Added

5. Edit the Dockerfile

...

Code Block
themeConfluence
USER root
RUN apt-get update && apt-get install -y imagemagick

6. Test

...

the Extractor

You can test your extractor as follows:

Code Block
themeConfluence
docker-compose up -d
docker build -t <your_extractor_name> .
docker run -it -rm -i -tlink browndog_clowder_1 --link <your_extractor_name_with_only_alphabets>_browndog_rabbitmq_1:rabbitmq <your_extractor_name>

...

Code Block
themeConfluence
INFO    : pyclowder.extractors -  Waiting for messages. To exit press CTRL+C

Converters

In this sectionHere we described the process for taking a working piece of code (an application, library, other service, etc) and deploying it as a Brown Dog converter.  In this example, we describe the creation of a converter using the popular image converter written using tool, ImageMagick.

...

1. Get Your Code Together

We have developed a template

...

converter. It is a simple image converter that

...

converts between different image formats using ImageMagick tool. Clone the template converter and rename the directory to an appropriate name that reflects the purpose of your converter

Code Block
themeConfluence
git clone https://opensource.ncsa.illinois.edu/bitbucket/scm/bd/convertors-template.git
mv convertors-template/ <your_converter_name>
cd <your_converter_name>

Rename and edit ImageMagick_convert.sh script to wrap your

...

conversion tool. This script file should be named in the format <alias>_convert.<script_type>. Here <alias> needs to be replaced by the name of the conversion tool with which the converter registers with Polyglot and <script_type> needs to be replaced by the extension for the type of

...

script this wrapper is written in. Polyglot currently supports scripts written in Python, Bash, R, AutoHotKey, AutoIT, and Sikuli (e.g. *.py, *.sh, etc.). For the sake of ease of explanation, we will rename the script file as MyTool_convert.sh. This script accepts three parameters: 

  1. Full path to input file
  2. Full path to output file (including filename)
  3. Full local path to available scratch space (optional)

This script will be used by the Software Server to

...

run the tool and carry out any requested conversions. The example script ImageMagick_convert.

...

sh that uses ImageMagick tool to convert images between different formats is shown below. The conversion script follows a specific header and is written as comments:

  1. First line is the shebang line
  2. Second line contains the name of the converter followed by the version (if any)
  3. Third line refers to the type of the data that it can convert
  4. Fourth line contains a comma-separated list of the input file formats accepted by this converter
  5. Fifth line contains a comma-separated list of the output file formats that this converter can generate
  6. This is followed by the actual code that does conversion.

Image Modified

2. Edit the Dockerfile

Modify the Dockerfile in the converter directory to

...

replace ImageMagick with MyTool. Specifically change line numbers 11, 15, 16 and 17. You need to also change other fields like maintainer and may need to add instructions to install any specific software required by your converter. For example, you can see instruction to install ImageMagick software in the example Dockerfile:

Code Block
languagetext
themeConfluence
titleDockerfile
linenumberstrue
# Create softwareserver for polyglot.
FROM ncsapolyglot/polyglot:develop
MAINTAINER Rob Kooper <kooper@illinois.edu>

USER root
# - install requirements
# - enable shellscripts to be scanned
# - enable imagemagick conversion by adding to .aliases.txt
RUN apt-get update && apt-get -y install vim nano imagemagick && \
	/bin/sed -i -e 's/^\([^#]*Scripts=\)/#\1/' -e 's/^#\(ShellScripts=\)/\1/' /home/polyglot/polyglot/SoftwareServer.conf && \
	echo "ImageMagick" > /home/polyglot/polyglot/scripts/sh/.aliases.txt

# copy convert file to scripts/sh folder in container
# this is done to keep cache so you can debug script easily
COPY ImageMagick_convert.sh /home/polyglot/polyglot/scripts/sh/
RUN chown polyglot /home/polyglot/polyglot/scripts/sh/ImageMagick_convert.sh && \
    chmod +x /home/polyglot/polyglot/scripts/sh/ImageMagick_convert.sh

# back to polyglot
CMD ["softwareserver"]

...

Specifically, modify:

Code Block
themeConfluence
echo "ImageMagick" > /home/polyglot/polyglot/scripts/sh/.aliases.txt

...

to:

Code Block
themeConfluence
echo "MyTool" > /home/polyglot/polyglot/scripts/sh/.aliases.txt

...

modify:

Code Block
themeConfluence
COPY ImageMagick_convert.sh /home/polyglot/polyglot/scripts/sh/

...

to:

Code Block
themeConfluence
COPY MyTool_convert.sh /home/polyglot/polyglot/scripts/sh/

...

and modify:

Code Block
themeConfluence
RUN chown polyglot /home/polyglot/polyglot/scripts/sh/ImageMagick_convert.sh && \
    chmod +x /home/polyglot/polyglot/scripts/sh/ImageMagick_convert.sh

...

to:

Code Block
themeConfluence
RUN chown polyglot /home/polyglot/polyglot/scripts/sh/MyTool_convert.sh && \
    chmod +x /home/polyglot/polyglot/scripts/sh/MyTool_convert.sh

...

6. Test the Converter

You can test your converter as follows:

Code Block
themeConfluence
docker

...

 

...

build –t mytool .
docker run -

...

it 

...

-

...

BD-tmux runs the necessary dockerized  Brown Dog Data Transformation Services (Polyglot, Clowder, Fence, ImageMagick converter and OCR extractor) and combines them into one integrated program. 

  • After downloading BD-tmux, users can simply run bash script under command-line to start BD-tmux.
Code Block
 bd.sh
  • The BD-tmux script will split your terminal into panes and start each of the services needed for the  Brown Dog Data Transformation Services. It provides a useful and convenient way to view the logs of running services in panes. 

    Image Removed

...

There is an example to perform a conversion from jpg to bmp.

...

-link browndog_rabbitmq_1:rabbitmq mytool

You should see the following in the terminal. This means that the converter is running and waiting for messages:

Code Block
themeConfluence
Available Software:
  ImageMagick (ImageMagick)