Updated On 4.1.2

Configuration

This section describes how to configure CrafterCMS.

General Configuration 

Security 

To secure your CrafterCMS install, please see the article Security.

Setup Project in a Delivery Environment 

Setting up a project or site for delivery can be done for traditional deployments or serverless deployments. Furthermore, a project or site can be set up as staging or live.

For traditional delivery, follow the article Setup Engine to Deliver a Project, and for serverless delivery, follow the article Serverless Delivery.

Ports and Hostnames 

Default Ports and Hostnames 

CrafterCMS uses the following default ports and hostnames:

Module	Port	Hostname
Studio	8080 33306 5701	localhost
Engine	8080 9080	localhost
Deployer	9191 9192	localhost
Search	9201 9202	localhost
Profile	8080 9080	localhost
Social	8080 9080	localhost

Change Ports and Hostnames 

There are times when you need to change the ports and/or hostnames in your CrafterCMS installation. Changes to the ports and/or hostnames may be required in the following cases:

If you need to change the port that an application in the current installation binds to.
If you need the applications in the current installation to communicate with another application that’s in a different host and/or port.

All the hostnames and ports used for communication by CrafterCMS applications are defined in CRAFTER_HOME/bin/crafter-setenv.sh. You can either modify the file directly or set the environment variables (which is much cleaner). The environment variables are noted in the file, for example, MAIL_HOST and MAIL_PORT are used to set the hostname and port for the mail server and CrafterCMS will use those environment variables if present before using the defaults.

Authoring Environment Ports and Hostnames

The following is an example of the default values for the hostnames and ports used by the CrafterCMS authoring applications AUTHORING_INSTALL_DIR/bin/crafter-setenv.sh

AUTHORING_INSTALL_DIR/bin/crafter-setenv.sh hostnames and ports with defaults

export MAIL_HOST=${MAIL_HOST:="localhost"}
export MAIL_PORT=${MAIL_PORT:="25"}
export SEARCH_HOST=${SEARCH_HOST:="localhost"}
export SEARCH_PORT=${SEARCH_PORT:="9201"}
export DEPLOYER_HOST=${DEPLOYER_HOST:="localhost"}
export DEPLOYER_PORT=${DEPLOYER_PORT:="9191"}
export MONGODB_HOST=${MONGODB_HOST:="localhost"}
export MONGODB_PORT=${MONGODB_PORT:="27020"}
export MARIADB_HOST=${MARIADB_HOST:="127.0.0.1"}
export MARIADB_PORT=${MARIADB_PORT:="33306"}
export TOMCAT_HOST=${TOMCAT_HOST:="localhost"}
export TOMCAT_HTTP_PORT=${TOMCAT_HTTP_PORT:="8080"}
export TOMCAT_HTTPS_PORT=${TOMCAT_HTTPS_PORT:="8443"}
export TOMCAT_AJP_PORT=${TOMCAT_AJP_PORT:="8009"}
export TOMCAT_SHUTDOWN_PORT=${TOMCAT_SHUTDOWN_PORT:="8005"}
export TOMCAT_DEBUG_PORT=${TOMCAT_DEBUG_PORT:="8000"}

Delivery Environment Ports and Hostnames

The following is an example of the default values for the hostnames and ports used by the CrafterCMS delivery applications DELIVERY_INSTALL_DIR/bin/crafter-setenv.sh:

DELIVERY_INSTALL_DIR/bin/crafter-setenv.sh hostnames and ports with defaults

# -------------------- hostnames and ports --------------------
export MAIL_HOST=${MAIL_HOST:="localhost"}
export MAIL_PORT=${MAIL_PORT:="25"}
export SEARCH_HOST=${SEARCH_HOST:="localhost"}
export SEARCH_PORT=${SEARCH_PORT:="9202"}
export DEPLOYER_HOST=${DEPLOYER_HOST:="localhost"}
export DEPLOYER_PORT=${DEPLOYER_PORT:="9192"}
export MONGODB_HOST=${MONGODB_HOST:="localhost"}
export MONGODB_PORT=${MONGODB_PORT:="28020"}
export TOMCAT_HOST=${TOMCAT_HOST:="localhost"}
export TOMCAT_HTTP_PORT=${TOMCAT_HTTP_PORT:="9080"}
export TOMCAT_HTTPS_PORT=${TOMCAT_HTTPS_PORT:="9443"}
export TOMCAT_AJP_PORT=${TOMCAT_AJP_PORT:="9009"}
export TOMCAT_SHUTDOWN_PORT=${TOMCAT_SHUTDOWN_PORT:="9005"}
export TOMCAT_DEBUG_PORT=${TOMCAT_DEBUG_PORT:="9000"}

Logging 

Learn more about how to configure CrafterCMS Logging.

Reverse Proxy (Apache HTTPd / NGINX)

It’s often times desirable to use a reverse proxy like Apache HTTPd, NGINX, or a CDN to front the CrafterCMS Studio and Engine web applications. This can be helpful for faster serving of static assets, caching, and SSL termination among other benefits. In this section, we discuss how to configure a reverse proxy using Apache 2 HTTPd vhost configuration for authoring and delivery. A similar approach can be used for other HTTPd servers.

Below are the directives used for setting up a reverse proxy with Apache:

Authoring Configuration

<VirtualHost *:80>
     ServerName authoring.example.com

     ProxyPreserveHost On

     # Proxy Authoring and Preview (Crafter Studio and Engine Preview)
     ProxyPassMatch ^/(studio/events)$  ws://localhost:8080/$1
     ProxyPass / http://localhost:8080/
     ProxyPassReverse / http://localhost:8080/

     # Configure the log files
     ErrorLog ${APACHE_LOG_DIR}/crafter-studio-error.log
     CustomLog ${APACHE_LOG_DIR}/crafter-studio-access.log combined
</VirtualHost>

Delivery Configuration

<VirtualHost *:80>
     ServerName example.com

     # Remember to change {path_to_craftercms_home} to CrafterCMS installation home
     # Remember to change {myproject} to your actual project name

     # Path to your CrafterCMS project
     DocumentRoot /{path_to_craftercms_home}/data/repos/sites/{myproject}

     RewriteEngine On
     # Assign CrafterCMS project for this vhost

     RewriteRule (.*) $1?crafterSite={myproject} [QSA,PT]

     # Block outside access to management services
     RewriteRule ^/api/1/cache / [NC,PT,L]
     RewriteRule ^/api/1/site/mappings / [NC,PT,L]
     RewriteRule ^/api/1/site/cache / [NC,PT,L]
     RewriteRule ^/api/1/site/context/destroy / [NC,PT,L]
     RewriteRule ^/api/1/site/context/rebuild / [NC,PT,L]

     # Take all inbound URLs and lower case them before proxying to Crafter Engine
     # Crafter Studio enforces lower-case URLs.
     # Using the rewrite rule below, the URL the user sees can be mixed-case,
     # however, what's sent to CrafterCMS is always lower-case.
     RewriteCond %{REQUEST_URI} !^/static-assets/.*$ [NC]
     RewriteCond %{REQUEST_URI} !^/api/.*$ [NC]
     RewriteMap lc int:tolower
     RewriteRule ^/(.*)$ /${lc:$1}

     ProxyPreserveHost On

     # Don't proxy static-asset, instead, serve directly from HTTPd
     ProxyPass /static-assets !

     # Proxy the rest to Crafter Engine
     ProxyPass / http://localhost:9080/
     ProxyPassReverse / http://localhost:9080/

     # Configure the log files
     ErrorLog ${APACHE_LOG_DIR}/crafter-engine-error.log
     CustomLog ${APACHE_LOG_DIR}/crafter-engine-access.log combined
 </VirtualHost>

The ProxyPreserveHost directive indicates whether it uses incoming Host HTTP request header for proxy request

The ProxyPass and ProxyPassReverse directives in the above example specify that traffic to the server name specified in your config should be proxied to http://localhost:8080/ for your authoring install and http://localhost:9080/ for your delivery install. The ProxyPassReverse distinguishes your configuration as a reverse proxy setup.

Below are the directives used for setting up a reverse proxy with NGINX:

NGINX Authoring Configuration

server {
    listen 80;
    server_name authoring.example.com;

    # Proxy Authoring and Preview (Crafter Studio and Engine Preview)
    location ~ ^/(studio/events)$ {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Configure the log files
    error_log ${NGINX_LOG_DIR}/crafter-studio-error.log;
    access_log ${NGINX_LOG_DIR}/crafter-studio-access.log combined;
}

NGINX Delivery Configuration

server {
    listen 80;
    server_name example.com;

    # Remember to change {path_to_craftercms_home} to CrafterCMS installation home
    # Remember to change {myproject} to your actual project name

    # Path to your CrafterCMS project
    root /{path_to_craftercms_home}/data/repos/sites/{myproject};

    location /static-assets/ {
        # Serve static assets directly from NGINX
        # Adjust the path as needed based on your setup
        alias /{path_to_craftercms_home}/data/repos/sites/{myproject}/static-assets/;
    }

    location / {
        rewrite ^/(.*)$ /$1?crafterSite={myproject} break;

        # Block outside access to management services
        rewrite ^/api/1/cache / break;
        rewrite ^/api/1/site/mappings / break;
        rewrite ^/api/1/site/cache / break;
        rewrite ^/api/1/site/context/destroy / break;
        rewrite ^/api/1/site/context/rebuild / break;

        # Take all inbound URLs and lower case them before proxying to Crafter Engine
        # Crafter Studio enforces lower-case URLs.
        # Using the rewrite rule below, the URL the user sees can be mixed-case,
        # however, what's sent to CrafterCMS is always lower-case.
        if ($request_uri !~ ^/static-assets/.*$ ) {
            if ($request_uri !~ ^/api/.*$ ) {
                rewrite ^/(.*)$ /${lc:$1} break;
            }
        }

        proxy_pass http://localhost:9080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Configure the log files
    error_log ${NGINX_LOG_DIR}/crafter-engine-error.log;
    access_log ${NGINX_LOG_DIR}/crafter-engine-access.log combined;
}

Depending on your setup, the following CrafterCMS properties may need to be setup:

crafter.engine.forwarded.headers.enabled property under Forwarded Headers in the server-config.properties file
studio-config-forwarded-headers property under Forwarded Headers in the studio-config-override.yaml file

Note

When configuring the delivery environment, it is possible to specify an HTTP header called X-Crafter-Site set to the value of {myproject} instead of using a URL rewrite as shown in the examples above.

Studio 

Crafter Studio helps create and manage content and code in a project/site. Learn more about Crafter Studio configuration and administration in the articles Studio Configuration and Studio Administration.

Engine 

Crafter Engine delivers the content to consumers/users. Learn more about Crafter Engine configuration and administration in the article Engine Configuration.

Deployer 

Crafter Deployer ties Studio and Engine together and is responsible for publishing content from Studio to Engine. Learn more about Crafter Deployer configuration and administration in Deployer Administration and Configuration.

Profile 

Crafter Profile provides a user identity augmentation capability. It allows the project/site developers to add metadata to existing identity (managed in LDAP for example) and add arbitrary metadata to it, or, it can manage the identity entirely if desired. Learn more about Crafter Profile configuration and administration in Profile Configuration and Administration.