Configure Cargo for SSL/TLS

Overview

This guide explains how to configure your local Cargo-based development environment to use SSL/TLS. By default, the Tomcat container in a Bloomreach Content project uses HTTP. Use these steps if you need to develop or test with HTTPS locally.

Note: For more details on Tomcat SSL/TLS configuration, see the Apache Tomcat 8 SSL/TLS Configuration HOW-TO.

Only use this configuration for local development and testing.

Prerequisites

Steps

1. Create Keystore, Certificate, and Truststore

Change to your project's conf directory:

cd conf

Generate a keystore using the Java keytool utility:

keytool -keystore tomcatkeystore -genkey -alias 127.0.0.1 -keyalg RSA

When prompted, enter the following values. Use "127.0.0.1" for the Common Name (CN):

Enter keystore password:
Re-enter new password:
What is your first and last name?
  [Unknown]:  127.0.0.1
What is the name of your organizational unit?
  [Unknown]:  Infra
What is the name of your organization?
  [Unknown]:  Bloomreach
What is the name of your City or Locality?
  [Unknown]:  Mountain View
What is the name of your State or Province?
  [Unknown]:  CA
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=127.0.0.1, OU=Infra, O=Hippo, L=Boston, ST=MA, C=US correct?
  [no]:  yes

Enter key password for <127.0.0.1>
        (RETURN if same as keystore password):
Re-enter new password:

After completing these prompts, the tomcatkeystore file will appear in your conf directory.

Export a certificate from the keystore:

keytool -keystore tomcatkeystore -exportcert -alias 127.0.0.1 -file tomcat.cert

Create a truststore and import the certificate:

keytool -import -file tomcat.cert -alias 127.0.0.1 -keystore tomcattruststore

When prompted to trust the certificate, type yes:

Trust this certificate? [no]:  yes

You should now have a tomcattruststore file in your conf directory.

2. Update Cargo Plugin Configuration

Open your project's root pom.xml file.

Locate the cargo.run Maven profile. Inside this profile, find the cargo-maven3-plugin plugin configuration.

Add the following properties under plugin/configuration/configuration/properties:

<cargo.servlet.port>8443</cargo.servlet.port>
<cargo.protocol>https</cargo.protocol>
<cargo.tomcat.connector.clientAuth>false</cargo.tomcat.connector.clientAuth>
<cargo.tomcat.connector.sslProtocol>TLS</cargo.tomcat.connector.sslProtocol>
<cargo.tomcat.connector.keystoreFile>${project.basedir}/conf/tomcatkeystore</cargo.tomcat.connector.keystoreFile>
<cargo.tomcat.connector.keystorePass>changeit</cargo.tomcat.connector.keystorePass>
<cargo.tomcat.connector.keyAlias>127.0.0.1</cargo.tomcat.connector.keyAlias>
<cargo.tomcat.httpSecure>true</cargo.tomcat.httpSecure>

Still within the cargo.run profile, add these system properties to plugin/configuration/container/systemProperties:

<javax.net.ssl.trustStore>${project.basedir}/conf/tomcattruststore</javax.net.ssl.trustStore>
<javax.net.ssl.trustStorePassword>changeit</javax.net.ssl.trustStorePassword>

Build your project to apply the changes.

3. Configure HST Host Settings

Start your project.

Open your browser and navigate to the console:

https://127.0.0.1:8443/cms/console/

Log in as admin. Navigate to the node:

/hst:platform/hst:hosts

Set the hst:scheme property to https:

/hst:platform/hst:hosts
  - hst:scheme = https

Navigate to:

/hst:platform/hst:hosts/dev-localhost

Set the hst:defaultport property to 8443:

/hst:platform/hst:hosts/dev-localhost
  - hst:defaultport = 8443

Repeat these steps for your site host configuration at /hst:myproject/hst:hosts.

Set the hst:scheme property:

/hst:myproject/hst:hosts
  - hst:scheme = https

Set the hst:defaultport property:

/hst:myproject/hst:hosts/dev-localhost
  - hst:defaultport = 8443

Save your changes to the repository.

4. Verify SSL/TLS Setup

Open your browser and go to:

https://localhost:8443/cms/

Confirm that the Channel Manager loads and operates as expected.

Troubleshooting

  • If the browser reports a certificate warning, verify that you used "127.0.0.1" as the CN and are accessing the correct hostname.
  • If Tomcat fails to start, check the keystore and truststore paths and passwords in your pom.xml.
  • For SSL handshake errors, ensure the truststore contains the correct certificate.
Share Feedback
Page: /build/development-tools/configure-cargo-for-https-ssl-tls
Section: Build
Category *
Configure Cargo for SSL/TLS | Bloomreach Content Documentation