Skip to main content

Tercen developer’s guide

9 Creating a docker operator

Some R packages require additional system libraries that might not be installed in the Tercen environment. We can install them locally, but a problem persists:

How to tell Tercen to install these dependencies when installing an operator?

A solution is to create a docker container with our environment. If you are not familiar with Docker, it is highly recommended that you read the Get started with Docker guide.

Create the R operator locally

As an example, we will use the worldmap Tercen operator. It requires the R package sf, commonly used to plot maps. This package requires an external system dependency, GDAL, depending itself on UDUNIT2.

You will not be able to install this R package if you don’t have these dependencies installed on the system. To install the package in Tercen Studio, we simply need to run this command in the terminal:

apt-get -y update && apt-get install -y libudunits2-dev libgdal-dev

Once the operator is running locally (see section Running docker operators locally), we can prepare the docker operator.

Create the docker operator

First, create a second GitHub repository that will hold the code used to build the image:

It contains different files:

  • Dockerfile: instructions to build the Docker container

  • README.md: to document the operator

  • operator.json:

  • start.R: internal, should not be modified.

For the worldmap operator, the Dockerfile look like this:

FROM tercen/dartrusttidy:1.0.7

USER root
WORKDIR /operator

RUN apt-get update
RUN apt-get install -y libudunits2-dev
RUN apt-get update
RUN apt-get install -y libgdal-dev

RUN git clone https://github.com/tercen/shiny_worldmap_operator.git

WORKDIR /operator/shiny_worldmap_operator

RUN echo 0.0.5 && git pull
RUN git checkout 0.0.5

RUN R -e "renv::restore(confirm=FALSE)"

ENV TERCEN_SERVICE_URI https://tercen.com

COPY start.R /start.R

ENTRYPOINT [ "R","--no-save","--no-restore","--no-environ","--slave","-f","/start.R"]

From the template, we need to:

  • indicate the git repository containing the R operator (here, https://github.com/tercen/shiny_worldmap_operator.git)

  • modify the working directory (/operator/shiny_worldmap_operator, based on the GitHub repository name)

  • modify the tag (here, 0.0.5)

  • add the commands to install our dependencies:

RUN apt-get update
RUN apt-get install -y libudunits2-dev
RUN apt-get update
RUN apt-get install -y libgdal-dev

Finally, we need to modify the operator.json docker operator file.

{
  "name": "Worldmap",
  "description": "Shiny world map representation",
  "tags": ["map"],
  "authors": ["tercen"],
  "urls": ["https://github.com/tercen/shiny_worldmap_docker_operator"],
  "container": "agouy/worldmap:0.0.5",
  "isWebApp": true
}

Pay attention to the two following lines:

  • "container": "agouy/worldmap:0.0.5" is used to indicate the account, name and tag of the docker container,

  • "isWebApp": true as we are handling a Shiny app.

Build and push docker image

  • If you do not already have one, create an account on Docker Hub.

  • Install Docker on your machine: How to install Docker

  • Login to Docker Hub using the docker login command and your credentials. [Refer to the docker login docs for a complete reference]

docker login --username=YOURUSERNAME --password=YOURPASSWORD
  • Build your image with the docker build command (with ACCOUNT your account name, REPO your image name and TAG your tag)
docker build -t $ACCOUNT/$REPO:$TAG .
  • Finally, push the image to your hub.
sudo docker push $ACCOUNT/$REPO:$TAG

Running docker operators locally

If you wish to test your docker operator in your local Tercen, you require to activate the docker capability in Tercen Studio by changing the docker-compose.yaml file of your Tercen Studio setup.

Please check the docker-compose.yaml file, it is found in main installation folder of Tercen Studio.

The steps to modify the file are:

First stop the dockers:

docker-compose down

Edit the docker-compose.yaml file, read the comments within the file, there a set of lines which require to be uncommented. The are by default commented out:

#    environment:
#      - tercen.log.level="0"
# needed for docker operators, 172.17.0.1 is the default docker gateway
#      - tercen.public.client.uri=http://172.17.0.1:5402
#      - tercen.worker.public.ip=172.17.0.1

The above is an example to activate on an Ubuntu system, the settings may differ for windows, please check with support@tercen.com.

After you have saved the file, then start the dockers.

docker-compose up -d

These modification allow Tercen Studio to run operators which are using dockers.

Integrating any code (e.g. C++)

If your algorithm code is not in R. Then consider the following example, it highlights an operator which is written in C++ called atsne or approximate tsne.

It is implemented in Tercen using two concepts, one an operator and one a docker.

The atsne_operator calls the C++ code implemented in the atsne_docker.

Please check out the repository (click on links above) and see how this it was configured.