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, andoverride.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
-
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
-
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 variableJAVA_XMX
. Meanwhile, to override the Java initial memory allocation pool (Xms
), pass the value to the variableJAVA_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
-
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.
-
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/
-
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.
-
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" /
-
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
-
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 |
|
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.
-
To know more about how Martini uses Solr, see: