Skip to content

Toro Cloud Dev Center


Deployment within standard Docker container

This page will guide you on how to deploy a Martini Runtime instance using the official Docker image from the Docker registry. The image already comes pre-configured with sensible defaults, and 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. Storing your data in a different location also makes it easier to perform version upgrades.

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 you need to persist. They will store the important data Martini needs.

  • /data/data - contains all Solr-related1 data files, Hypersonic databases, ActiveMQ data, and override.properties files
  • /data/packages - contains all packages installed in Martini
  • /data/logs - contains all log files created by Martini
  • /root/.java - used by Java to store some of Martini's preferences

Why are these directories prefixed with /data?

When using the official Martini Docker image, Martini's home directory is set to /data. You can learn more about Martini's directory structure here.

Procedure

Using the image with empty data directories

  1. Create the counterparts of the directories specified above on your host server. In the examples on this page, it's going to persist them under the host server's /opt/apps/martini directory using the command below:

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

    Using this single command, the directories will be created under /opt/apps/martini.

    1
    2
    3
    4
    5
    6
    /opt/apps/martini
    ├── data
    ├── packages
    ├── code
    ├── logs
    ├── .java
    
  2. After creating the directories, you can deploy the container. Start the container by using the command below. As you may have noticed, the -v argument has been added to define the volumes that will be mounted for persisting data.

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

    Overriding Java memory settings

    The official Docker image is shipped with environment variables that can override the Java memory configuration. 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 reference.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    docker run -p 8080:8080 \
    -v /opt/apps/martini/data:/data/data \
    -v /opt/apps/martini/packages:/data/packages \
    -v /opt/apps/martini/code:/data/code \
    -v /opt/apps/martini/logs:/data/logs \
    -v /opt/apps/martini/.java:/root/.java \
    -e JAVA_XMX=1g \
    -e JAVA_XMS=128m \
    --privileged=true \
    --name martini \
    toroio/martini-runtime
    
  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 similar to the one below:

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

Using the image with existing instance data

If you already have data directories on your server, you only need to map them to the directories in the image. Afterwards, the steps will be similar to what we'd do if they didn't exist yet.

  1. Go to the directory where Martini is installed. If your instance is installed in /opt/toro/martini, your command should be similar to the one below.

    1
    cd /opt/toro/martini/
    
  2. Verify that Martini's directories exist. Take note of their locations.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    # Listed contents of Martini'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@  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 Martini instance has multiple directories in the installation directory. However, the official Docker image has an installer embedded in it, which is why only some of the directories need to be mounted.

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

    If you have verified that the Martini directories exist, the next thing to do is to check for the Java preferences directory. If you have run Martini 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, you will be ready to launch the container. 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 required directories exist, you can start the container and map the directories using the command below:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    docker run -p 8080:8080 \
    -v <martini-installation-path>/data:/data/data \
    -v <martini-installation-path>/packages:/data/packages \
    -v <martini-installation-path>/packages:/data/code \
    -v <martini-installation-path>/logs:/data/logs \
    -v <java-preference-directory>:/root/.java \
    --privileged=true \
    --name martini \
    toroio/martini-runtime
    
  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/martini-runtime   "/bin/sh -c /data/bi…"   28 seconds ago    Up 26 seconds   0.0.0.0:8080->8080/tcp, 8443/tcp   martini
    

    Once verified, you will be able to access Martini at <docker-server-ip>:8080.

Upgrading to the latest version

In order to upgrade your instance to the latest version of Martini, 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/martini-runtime:latest

Then, delete the existing instance and start the newly installed instance.

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 the 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 Martini instance. However, we always recommend that you read the upgrade notes to see all the changes brought by a newer release.

After your instance has been re-created, it will use the latest release of Martini.

Considerations for memory intensive systems

If you are running memory intensive processes in your dockerized Martini instance, you should consider tuning the instance's JVM.

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

To mitigate this memory problem, you can lower the out-of-memory priority on the Docker container by adding the --oom-score-adj flag to 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.


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