Docker - Documentation topics on: docker,.

Docker

Important

  • Currently dotCMS does not perform any testing of dotCMS on the Docker platform, and as such dotCMS is not officially supported on Docker.
    • This document is provided for informational purposes only, to address user questions about dotCMS in Docker.
  • Therefore if you do wish to test installing dotCMS on Docker, you should do so for development or testing purposes only.

Please also be aware that there are additional considerations if you wish to create an extensible and manageable approach; please consult the relevant Docker documentation in order to get an overview of all the possibilities.


Running dotCMS in a Docker Container

There are no technical limitations preventing dotCMS from running under the Docker platform. However there are potential licensing issues, and some elements of the Docker architecture can introduce performance issues and can interfere with some dotCMS features (especially clustering). Since dotCMS ships with an embedded H2 database and a starter site as the default configuration, the only addtional required element is to install a proper JDK in the Docker container.

Running dotCMS in a Docker Multi-Container Environment

It may be possible to run dotCMS using a Docker multi-containter deployment, but only when using a database other than H2. You may wish to use a Docker multi-container deployment to guarantee the modular spirit of docker, and to benefit from an already created and maintained database server image. You may find several database flavors available as a docker image, just make sure the database is a supported version of a dotCMS supported database.

Not Supported for Production Systems

Running dotCMS in Docker is not supported for production systems for the following reasons:

  1. dotCMS is not tested on the Docker platform.
  2. Performance can not be guaranteed.
    • Docker is not suitable for most production installations of dotCMS due to the challenges in guaranteeing CPU, memory, and storage resources to the JVM running dotCMS.
      • It can be difficult to achieve acceptable performance for dotCMS production workloads due to how these resources are allocated to Docker containers.
    • In addition, the Docker networking architecture imposes a connection overhead which can add significant latency to connections, which is not suitable for production sites.

Performance Considerations

For all Java web applications to achieve acceptable performance, minimum requirements for CPU, memory and networking. Therefore, if you are considering running dotCMS in Docker, please review the following sections and ensure that Docker is configured properly to minimize performance issues.

CPU Performance

As a Java application, the environment that dotCMS runs in should have 100% guaranteed (reserved) access to the CPU resources allocated to it. CPU oversubscription can cause severe performance problems for all workloads on the server due to Java garbage collection dynamics. Guaranteeing CPU allocation to a Docker container inside a virtual machine may be possible, but requires fine-tuned adjustment in the runtime parameters.

For more information on the Docker CPU allocation parameters, please see the Docker documentation.

Memory Performance

As a Java application, the environment that dotCMS runs in should have 100% guaranteed (reserved) access to the memory (RAM) resources allocated to it. Memory oversubscription can cause severe performance problems (including application crashes) for all workloads on the server due to Java garbage collection dynamics.

Important: Swap disk should not be used on any server running dotCMS, and this is even more critical in a Docker environment.

For more information on the Docker memory allocation parameters, please see the Docker documentation.

Disk Storage

Docker has a number of different options for allocating storage to Docker containers. Unfortunately, many of these introduce overhead and latency to the storage layer which can significantly impact dotCMS performance. Additionally, allocating data storage within the Docker container can introduce significant challenges with dotCMS storage scalability and data lifecycle management & persistence.

The best I/O performance and data management is usually achieved by mounting a host data directory in the dotCMS Docker container (documentation) to use for database, assets (ASSET_REAL_PATH), and dotsecure (DYNAMIC_DATA_PATH) storage. This provides a good separation of concerns between the application managed in the Docker container, and the persistent data managed outside of the Docker container.

For more information on the Docker storage parameters, please see the Docker documentation.

Networking

Docker has several different options for managing network connectivity for containers using bridging and/or NAT. These can introduce varying levels of system overhead and network latency, although this is typically unnoticeable in a single-server dotCMS environment. However, dotCMS clustering can be fairly sensitive to network latency, and the NAT port mappings used by some Docker networking models can interfere with proper cluster operation. Running a dotCMS cluster will be challenging to configure properly and might not be possible.

For more information on the Docker networking parameters, please see the Docker documentation.

Java Licensing

When running Java on Docker, you must pay particular attention to the licensing of the Java virtual machine you use, as each JVM has its own licensing requirements, and some JVM licenses do not allow use on virtual platforms such as Docker.

Java licensing is a complex and challending aspect of running dotCMS under Docker, so please ensure that you research this issue well before proceeding.

Oracle Java

The license that Oracle Java is distributed under has very strict restrictions on redistribution and acceptance of the license agreement. While there are many community-contributed Docker files and images that purport to include Java, these are generally not in compliance with Oracle Java licensing.

OpenJDK

One alternative to Oracle Java is to use a 3rd-party Java such as OpenJDK. Please be aware that OpenJDK has its own restrictions regarding redistribution, so you must read and understand the licensing to ensure conformance.

In addition, it's important to note that many of the OpenJDK versions bundled into Docker (such as those from Debian or Ubuntu) are based on non-standard builds that:

  • Do not match a known Java version.
  • Contain code that is in-between multiple versions.
  • Have not been through full compatibility and conformance testing.

Azul Zulu

Azul Zulu may be a compliant JVM from a licensing and Java compatibility perspective. However please be aware that dotCMS has not been tested with Zulu, so some incompatibilities or issues may exist.