Skip to content

Simple Dockerized Deployment of TORO Integrate using the Official Image

This page will guide you how to deploy TORO Integrate using the official Docker image from the Docker Registry. The image already comes pre-configured with sensible defaults. It's built particularly for production use.

We'll also discuss which directories you should mount as volumes, so that your data is safe when a container is deleted and which you can opt not to. At the same time, version upgrades should be easy if you have followed this guide.

Important Directories

Normally, when a Docker instance is stopped and removed, the data inside the container will be lost unless you have defined the directories or files as volumes for them to be persisted. The directories listed below are the directories in the image that we need to persist. They will store the important data TORO Integrate needs.

  • /data/data - contains all Solr-related1 data files, Hypersonic databases, ActiveMQ data, and override.properties files
  • /data/packages - contains all legacy packages installed in TORO Integrate
  • /data/code - contains Gloop Models and other data related to your services.
  • /data/logs - contains all log files created by TORO Integrate
  • /root/.java - used by Java to store application preferences

Why are these directories prefixed with /data?

When using the official TORO Integrate Docker image, TORO Integrate's home directory is set to /data. To learn more about TORO Integrate's directory structure, you can check this page.

Procedure

Using the Image with Fresh Data Directories

  1. Create the counterparts of the directories specified above in your host server. In our case, we're going to persist them under the host server's /opt/apps/toro-integrate directory.

    1
    mkdir -p /opt/apps/toro-integrate/{data,packages,code,logs,.java}
    

    Using this single command, the directories will be created under /opt/apps/toro-integrate.

    1
    2
    3
    4
    5
    6
    /opt/apps/toro-integrate
    ├── data
    ├── packages
    ├── code
    ├── logs
    ├── .java
    
  2. After creating the directories, we're now ready to deploy the container. Start the container by using the command below. As you may notice, we've added -v arguments so as to define the volumes we're going to mount to persist data.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    docker run -p 8080:8080 \
    -v /opt/apps/toro-integrate/data:/data/data \
    -v /opt/apps/toro-integrate/packages:/data/packages \
    -v /opt/apps/toro-integrate/code:/data/code \
    -v /opt/apps/toro-integrate/logs:/data/logs \
    -v /opt/apps/toro-integrate/.java:/root/.java \
    --privileged=true \
    --name toro-integrate \
    toroio/integrate
    

    Overriding Java Memory Settings

    The official docker image is shipped with environment variables that can override Java Memory configurations. To override the Java Maximum heap memory allocation pool (Xmx), pass a value to the environmental variable JAVA_XMX. Meanwhile, to override the Java initial memory allocation pool (Xms), pass the value to the variable JAVA_XMS. See the sample command below for your reference.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    docker run -p 8080:8080 \
    -v /opt/apps/toro-integrate/data:/data/data \
    -v /opt/apps/toro-integrate/packages:/data/packages \
    -v /opt/apps/toro-integrate/code:/data/code \
    -v /opt/apps/toro-integrate/logs:/data/logs \
    -v /opt/apps/toro-integrate/.java:/root/.java \
    -e JAVA_XMX=1g \
    -e JAVA_XMS=128m \
    --privileged=true \
    --name toro-integrate \
    toroio/integrate
    
  3. Verify that the Docker instance has been created by running the command below.

    1
    docker ps
    

    If all is well, you should see an entry for your instance in the response like below:

    1
    2
    CONTAINER ID   IMAGE              COMMAND                  CREATED           STATUS          PORTS                              NAMES
    72972dbf8452   toroio/integrate   "/bin/sh -c /data/bi…"   28 seconds ago    Up 26 seconds   0.0.0.0:8080->8080/tcp, 8443/tcp   toro-integrate
    

Using the Image with Existing Instance Data

Since you already have the data directories somewhere in your server, we just need a way to map them to the directories in the image. And then the steps should be similar to what we'd do if they didn't exist yet.

  1. Go to the directory where TORO Integrate is installed. If your instance is installed in /opt/toro-integrate-3.0, your command should be similar to the one below.

    1
    cd /opt/toro/integrate-3.0/
    
  2. Verify that TORO Integrate's directories exist. Take note of their locations.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    # Listed contents of TORO Integrate's home directory via `ls -l`.
    drwxrwxr-x@   6 root  root    204 Mar 15 13:31 assets
    drwxrwxr-x@   9 root  root    306 Mar 15 13:31 bin
    drwxrwxr-x@   3 root  root    102 Mar 15 02:21 code
    drwxrwxr-x@  11 root  root    374 Mar 15 13:32 conf
    drwxrwxr-x@  14 root  root    476 Mar 15 13:30 core
    drwxrwxr-x@   8 root  root    272 Mar 21 08:40 data
    drwxrwxr-x@ 478 root  root  16252 Mar 15 13:31 lib
    drwxr-xr-x    4 root  root    136 Mar 21 08:36 logs
    drwxrwxr-x@   5 root  root    170 Mar 15 02:21 packages
    drwxrwxr-x@   4 root  root    136 Apr  2 12:36 solr
    drwxrwxr-x@   3 root  root    102 Mar 15 02:21 tmp
    drwxrwxr-x@  45 root  root   1530 Mar 15 13:30 web
    

    Originally, your TORO Integrate instance has multiple directories in the installation directory. However, the official Docker image has an installer embedded in it, that's why we only need to mount some of the directories.

  3. Look for the Java preferences directory and take note of its location.

    Now that we have verified that the TORO Integrate directories exist, the next thing to do is to check for the Java preferences directory. If you've run TORO Integrate before using the root user (which is not recommended), your preference directory must be in its home directory. Try running the command below to see the Java preferences directory:

    1
    2
    3
    4
    5
    6
    ls -la ~/
    
    # And then you'll get entries like this:
    ...
    drwxrwxr-x@   6 root  root    204 Mar 15 13:31 .java
    ...
    

    If you have found the Java preferences directory, we're now good to go. If not, you can run the find command as shown below:

    1
    find -name ".java" /
    
  4. Start the container. After you've verified that all the needed directories exist, you may now run your container and map these directories using the command below:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    docker run -p 8080:8080 \
    -v <toro-integrate-installation-path>/data:/data/data \
    -v <toro-integrate-installation-path>/packages:/data/packages \
    -v <toro-integrate-installation-path>/packages:/data/code \
    -v <toro-integrate-installation-path>/logs:/data/logs \
    -v <java-preference-directory>:/root/.java \
    --privileged=true \
    --name toro-integrate \
    toroio/integrate
    
  5. Finally, verify if the Docker instance has been created.

    1
    2
    3
    # Checked via the `docker ps` command.
    CONTAINER ID   IMAGE              COMMAND                  CREATED           STATUS          PORTS                              NAMES
    72972dbf8452   toroio/integrate   "/bin/sh -c /data/bi…"   28 seconds ago    Up 26 seconds   0.0.0.0:8080->8080/tcp, 8443/tcp   toro-integrate
    

    Once verified, you should now be able to access TORO Integrate in <docker-server-ip>:8080. That's it!

    At first, TORO Integrate will ask for a license and after installing the license, your TORO Integrate instance should be ready to serve requests.

    Things you might need to consider for memory intensive systems

    If you will be running memory intensive processes in your TORO Integrate dockerized instance, you have to consider tuning the instance's JVM.

    If your host machine runs Linux and it starts detecting insufficient memory to perform system tasks, it might throw an Out of Memory Exceptions (OOME) and will start killing processes to free up memory. Because of this, your container's process might get killed by the kernel and in return, it will shut down your TORO Integrate instance.

    To mitigate this memory problem, you can lower the OOM priority on the Docker container by adding the --oom-score-adj flag on your run command. You can also try disabling the process-killing behavior of the kernel by flagging --oom-kill-disable upon startup. However, we do not recommend setting the OOM score to a very low negative number or disabling OOM for production systems as it might crash the host instance. To know more about limiting a container's resources, you can visit this link.

Upgrading to the Latest Version

In order to upgrade your instance to the latest version of TORO Integrate, you'll have to pull the newest release of the official Docker image from the Docker Registry and then restart your instance for the new image to be used by the Docker Engine.

To pull the new image from the Docker Registry, execute the command below:

1
docker pull toroio/integrate:latest

And then delete your existing instance and run a new one.

Restarting your container won't update the image

Restarting your instance by executing the command docker restart {instance_name} won't update the image used by your container. You will always have to remove the instance completely and then start a new one.

Read the upgrade notes before updating your instance

Most of the time, you won't really need to do anything special or tedious to upgrade your TORO Integrate instance. However, we always recommend that you read the upgrade notes to see all the changes brought by the newest release.

After your instance has been recreated, it should now be using the newest release of TORO Integrate.


  1. To know more about how TORO Integrate uses Solr, see: