This article provides the step-by-step instructions to download a template Brown Dog converter, customize it, test it and contribute a new converter to the repository.
Step 1. Set up environment to run the Brown Dog template converter project
- Install Docker.
For different OS, installation steps will be different.
For Mac OS X, follow the step-by-step instructions provided in the link: https://docs.docker.com/mac/step_one/
Note: The steps work even if you have pre-installed virtualbox. Make sure that you close virtual box before starting the installation procedure.
2. Click on the icon for the Quickstart Terminal window to launch it from the Application/Docker folder. Verify the installation by running the hello-world container.
$docker-run hello-world
If Quickstart Terminal startup script did not configure the shell correctly, you may get message “docker: cannot connect to the Docker daemon. Is the docker daemon running on this host?.”
The following commands to configure the shell:
$docker-machine env default
$eval $(docker-machine env default)
Now, you should be able to run hello-world container.
For some common troubleshooting during installation can be found here : https://docs.docker.com/faqs/troubleshoot/
Creation, Run and Deletion of Docker machine/container using bash shell can be found here: https://docs.docker.com/engine/installation/mac/
Note: You do not need superuser/root privileges to install Docker.
Step 2. Download the template project from the NCSA opensource repository
- git clone https://opensource.ncsa.illinois.edu/bitbucket/scm/bd/path/to/template_converter.git
- Or, Download the template project from the repository: https://opensource.ncsa.illinois.edu/bitbucket/projects/BD/repos/path/to/templatemplate_converter
The template-converter directory consists of one file (docker-compose.yml), and one sub-directory, example-server , with two files: Dockerfile and ImageMagick_convert.sh.
Step 3: Launching the development set up environment
- Change to the template-converter directory:
$cd template-converter
- Run the docker-compose.yml:
$docker-compose up
Docker Compose obtains the ncsa/polyglot-server image, mongodb image and rabbitmq from docker Hub, builds, launches these services within different containers and links them.
Step 4: Testing the example-server
- Change to the example-server directory:
$cd example-server
- Make sure the permission for ImageMagick_convert.sh is 755.
$cd chmod 755 ImageMagick_convert.sh
- Build and launch the example software server with the converter
$docker build –t example-server .
$docker run --rm -t -i --link polyglot_rabbitmq_1:rabbitmq example-server
- Check in the browser 192.168.99.100:8184, you should be able to see the test-endpoints of polyglot server.
TODO: Redirection to Software Server IP:8182 not working because of the internal/private IP within Docker machine.
Step 5: Modifying the template and creating your own converter
- Create a directory for your converter outside the directory of example-server
$mkdir mysoftwareserver
- Change to the directory and copy the files from example-server to current directory
$cd mysoftwareserver
$cp –R /path/to/template-converter/example-server
.
- Rename the ImageMagick_convert.sh
$mv ImageMagick_convert.sh MyTool_convert.sh
- Modify the MyTool_conver.sh using any editor (e.g. vim). A simple example is shown below:
1 #!/bin/sh
2 #ImageMagick (v6.5.2)
3 #image
4 #png bmp foobar
5 #jpg
6
7 output_filename=$(basename "$2")
8 output_format="${output_filename##*.}"
9
10 #Output PGM files as ASCII
11 if [ "$output_format" = "pgm" ]; then
12 convert "$1" -compress none "$2"
13 else
14 convert "$1" "$2"
15 fi
Line 2 : Change ImageMagick to MyTool
Line 4 : Replace foobar with gif
Line 5: Add ico
Then save the file.
A detail document explaining how to write converter for any tool can be found here:
Modify Dockerfile file using any editor (e.g. vim):
Line 11: Add MyTool to the .aliases.txt
Modify:
echo "ImageMagick" > /home/polyglot/polyglot/scripts/sh/.aliases.txt
To
echo "MyTool" > /home/polyglot/polyglot/scripts/sh/.aliases.txt
Line 15: Copy MyTool_convert.sh script to the script directory
COPY MyTool_convert.sh /home/polyglot/polyglot/scripts/sh/
Save the file
To build, launch and test the new converter, run the following command:
$docker build –t mytool .
$docker run --rm -t -i --link polyglot_rabbitmq_1:rabbitmq mytool