How To Change the Ports on Your Crafter CMS Installation

One of the most common questions I get from developers is:  “When I download Crafter CMS it runs on port 8080.  How do I change that?”  They are not simply looking to put Crafter on port 80 or 443.  They want to move it to port 9080 or some other port because they are already running something on port 8080.

To make things easy, let’s look at a standard development installation — which consists of the following microservices:  Crafter Studio, Crafter Engine, Crafter Search, Solr and Crafter Deployer.

In the diagrams above you will note the black arrows between components.  These are HTTP connection to (typically) localhost and the port specified on the target component.    Let’s review each of these connections:

A. Developer/consumer goes to Crafter Studio application (/studio).  Crafter Studio IFrames Crafter Engine rendering.
B. Crafter Studio queries Crafter Search when users do a search inside the CMS
C. When rendering Crafter Engine can leverage Crafter Search to perform content queries and searches.
D. Crafter Search applies platform-specific business rules and makes query requests to Solr via connection D
E. When content, code or configuration is saved via Crafter Studio or directly via Git it is picked up by the preview deployer and published to Crafter Search.  Crafter search performs inserts updates and deletes on Solr via connection D
F. 
Crafter Studio maintains/caches project/user and operational metadata (workflow state, dependencies) about content locally in an embedded MariaDB.

Configuration for Tomcat ports:

  • Impact: Ports for Crafter Studio, Crafter Engine, and Crafter Search
  • Location: INSTALL_DIR/bin/apache-tomcat/conf/server.xml
  • Configured ports: There are several ports listed in this XML file.
    • 8005 (shutdown port),
    • 8080 (HTTP connector)
    • 8443 (HTTPS connector)
    • 8009 (AJP connector)
  • INSTALL_DIR/bin/crafter-setenv.sh / crafter.bat
    • Linux: export TOMCAT_HTTP_PORT=8080
    • Windows: SET TOMCAT_HTTP_PORT=8080

Once you change the Tomcat ports you must update the configuration for the communication between microservices to Crafter Search:

  • Impact: Crafter Studio Connections
  • Location: INSTALL_DIR/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
  • Configured Ports:  There are several ports to update when Tomcat’s connector ports are changed:
    • studio.preview.engineUrl
    • studio.preview.search.createUrl
    • studio.preview.search.deleteUrl
  • Impact: Crafter Engine
  • Location: INSTALL_DIR/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties
  • Default Ports:  Update the crafter search port
    • crafter.engine.search.server.url
  • Impact: Crafter Deployer
  • Location: INSTALL_DIR/bin/deployer/config/classes/crafter/engine/extension/base-target.yaml
  • Default Ports:  Update the crafter search port
    • target/search/serverUrl

Configuration for Deployer ports:

  • Impact: Configures the ports for the deployer, impacts Studio
  • Location: INSTALL_DIR/bin/deployer/config/application.yaml
  • Configured Portsport
  • INSTALL_DIR/bin/crafter-setenv.sh / crafter.bat
    • Linux: export SET DEPLOYER_PORT=9191
    • Windows: export DEPLOYER_PORT=9191

Once you change the Deployers ports you must update the configuration for the communication between Crafter Studio and the deployer

  • Impact: Crafter Studio’s communication with deployer
  • Location: INSTALL_DIR/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
  • Configured Ports:  There are several ports to update when the deployer ports are changed:
    • studio.preview.defaultPreviewDeployerUrl
    • studio.preview.createTargetUrl
    • studio.preview.deleteTargetUrl

Configuration for Solr ports:

  • Impact: Crafter Search’s communication with Solr
  • Location: INSTALL_DIR/bin/crafter-setenv.sh / crafter.bat
  • Configured Ports:
    • Linux: export SOLR_PORT=8694
    • Windows: SET SOLR_PORT=8694
  • Impact: Crafter Search’s communication with Solr
  • Location:INSTALL_DIR/bin/apache-tomcat/shared/classes/crafter/studio/extension/server-config.properties
  • Configured Ports:
    • crafter.search.solr.server.url

Reindexing Content for Search and Queries in Crafter CMS

It is necessary from time to time to reindex content due to schema changes, migrations, and other scenarios. A bulk deployment will push all content to your index but involves several steps in addition to indexing which may not be needed. This article shows how to use the deployer to (re)index content that has already been deployed.

Reindexing the site content can be done using the reprocess feature in Crafter Deployer.

Step 1: Delete any existing content in the index

curl "http://hostname:port/solr-crafter/update/?commit=true" -H "Content-Type: text/xml" -d "<delete><query>crafterSite:MYSITENAME</query></delete>"

Step 2: Invoke the reprocessing

curl http://hostname:port/reprocess?password=MYPASSWORD&target=MYTARGET&processor=MyBeanName
Parameter Name Description Example
hostname Deployer’s hostname localhost
port Deployer’s port. 9191 default is 9191
password Deployer password
target The name property value of a target bean in target context file. demodotcomprod
processor The bean name of a processor. For reindexing, it should be the bean name of a search update post processor registered for a target bean in target context file. (e.g. SearchUpdateFlattenXmlProcessor) DemoDotComProdSearchProcessor

Step 3: Wait for indexing

You will see indexing activity in the deployment log as well as entries on the server(s) running Crafter Search and Solr. Indexing activity time is dependant on the amount of content which must be re-processed.

Reindexing Content Without Disrupting Service in Production

In some scenarios, it’s not possible/appropriate to delete a live index and wait for the index to rebuild in production. Perhaps the index is driving dynamic features on the site that will break while the index is empty or being rebuilt. In these scenarios, you need a process for building the index offline and swapping it in.

Step 1: Prepare a re-index core

The first step is to prepare an additional empty core on Solr where you can index the content.

Step 2: Set up a new deployment context that points to the new core

The next step is to create a new deployment context that mimics/is a copy of the production deployment context but that points to the “re-index” core. Note that you must restart the deployer in order for the new context to be detected.

Step 3: Content freeze

Once you are about to start a re-index you need to freeze your authoring/editing activity. If Content is being updated in the live environment while you are rebuilding your indexes, you may miss updates. Ask your authors not to publish during your re-index process.

Step 4: Re-index

Following the process above “Reindexing Content for Search and Queries” for re-indexing content, you want to invoke a reprocess action against your new deployment context.

Step 5: Wait

You will see indexing activity in the deployment log as well as entries on the server(s) running Crafter Search and Solr. Indexing activity time is dependant on the amount of content which must be re-processed.

Step 6: Swap indexes

Now that indexing is complete you need to load the re-indexed content. Follow these steps * In the solr console for the core administration click swap cores and provide the paths to the new index. * Once the core has reloaded, move the original core to backup * Consider creating a copy of the re-indexed core with the original name and swapping again to preserve file/folder names.

Step 7: Unfreeze Content

Now that you are certain everything is working as it should, notify your authors that they may start editing and publishing activities.

Step 8: Clean up

Now that your process is complete you can clean up some of the artifacts created by the process. * The re-index core if swapped out * The new deployment context