How to Modify Java KeyStore in Docker

This page shows to use a modified Java KeyStore file in a dotCMS Docker container without having to build a custom Docker image.

We use Docker Compose in this example but this can be applied in other container deployments like kubernetes.

The Java KeyStore file is a repository of security certificates that allows dotCMS to make secure connections to remote servers that use valid SSL/TLS certificates. It may be necessary to add additional certificates to the default Java KeyStore — most commonly when dotCMS needs to connect to HTTPS API servers that use self-signed certificates.

Specify the dotCMS release in docker-compose.yml rather than use latest, as the included KeyStore file can change when dotCMS releases new Docker images.

services:
    dotcms:
        image: dotcms/dotcms:21.09
        environment:
        CMS_HEAP_SIZE: '8g'
        ...
    volumes:
        - cms-shared:/data/shared
        ... 

Copy the default Java KeyStore file from a running container:

mkdir keystore
    
docker cp {container_id}:/java/lib/security/cacerts keystore/cacerts

Add custom cert(s) to the copied KeyStore file using the default password changeit. Give it a descriptive alias to be nice to future admins, then verify its presence:

keytool -import -trustcacerts -storepass changeit -file /PATH/TO/SELF-SIGNED-CERT.cer -alias doctms-SELF-SIGNED-CERT-YYYY -keystore keystore/cacert

keytool -storepass changeit -list -rfc -keystore keystore/cacerts | grep dotcms

To use the custom KeyStore in docker-compose.yml, mount the updated KeyStore file; also specify the custom KeyStore path in JAVA_OPTS:

environment:
CMS_JAVA_OPTS: '... -Djavax.net.ssl.trustStore=/srv/custom_keystore/cacerts -Djavax.net.ssl.trustStorePassword=changeit'
CMS_HEAP_SIZE: '8g'

volumes:
- /path/to/keystore/cacerts:/srv/custom_keystore/cacerts
- cms-shared:/data/shared

In a clustered environment, distribute the updated KeyStore file to all dotCMS nodes.