• Document Up to Date

Engine Multi-Target Configuration

There are some cases where the Engine configuration files need to have different values per publishing target. Say for a production environment where you have staging to test out your site and live , the site to be used by end users, you may need different SAML authentication mechanics or different URL rewrites.

The Engine Multi-Environment Configuration section detailed how to setup Engine configuration files per environment. CrafterCMS supports overriding Engine configuration files, not just per environment, but also per publishing target. It supports a base configuration per environment with the ability to override per publishing target.

The following engine configuration files can be setup for different publishing targets:

  • site-config.xml

  • application-context.xml

  • urlrewrite.xml

Here are the available publishing targets for the configuration files listed above:

  • preview

  • staging

  • live

Overriding Engine Configuration Files per Publishing Target

To override a configuration file in any of the publishing targets

  1. Add the new configuration file/s for overriding to Configurations under siteConfig -> Configuration

    Multi-target Configuration - Open Configurations

    The overriding configuration file should be named configuration-to-be-overridden.publishing-target.xml. Depending on the publishing target you wish the configuration file to override, the files should look like one of the following:

    • configuration-to-be-overridden.preview.xml

    • configuration-to-be-overridden.staging.xml

    • configuration-to-be-overridden.live.xml

    Say, to add a urlrewrite.xml file override for staging, add the following in the Configurations

    Configurations - SITENAME/config/studio/administration/config-list.xml
    <file>
  <module>engine</module>
  <path>urlrewrite.staging.xml</path>
  <title>Engine URL Rewrite (XML Style) Staging</title>
  <description>Engine URL Rewrite (XML Style) Staging</description>
  <samplePath>sample-urlrewrite.xml</samplePath>
</file>

    For more information on Configurations config file, see Site Config Configuration

  2. Fill in your desired additions/modifications to the override configuration file. Refresh your browser. The configuration file you added from above should now be available from siteConfig -> Configuration. Open the new configuration file and make the necessary additions/modifications for the override file then save your changes.

    Multi-target Configuration - New configuration files added to dropdown list

  3. If the configuration file to be overridden is not for preview, publish the configuration file to the intended publishing target, staging or live

Example

Let’s take a look at an example of overriding the Site Configuration used by Engine site-config.xml for the staging and live publishing targets so that each target has a different SAML authentication mechanics (different identity provider in staging and live). In our example, we will use a site created using the Website Editorial blueprint named mysite

  1. Add the new configuration file/s for overriding to Configurations under siteConfig -> Configuration. We will be overriding the site-config.xml file in the staging and live publishing targets, so we will add to the configuration a site-config.staging.xml and site-config.live.xml files.

    Configurations - SITENAME/sandbox/config/studio/administration/config-list.xml
     1<file>
 2  <module>engine</module>
 3  <path>site-config.staging.xml</path>
 4  <title>Engine Site Configuration Staging</title>
 5  <description>Site Configuration used by Engine for the Staging publishing target</description>
 6  <samplePath>sample-engine-site-config.xml</samplePath>
 7</file>
 8<file>
 9  <module>engine</module>
10  <path>site-config.live.xml</path>
11  <title>Engine Site Configuration Live</title>
12  <description>Site Configuration used by Engine for the Live publishing target</description>
13  <samplePath>sample-engine-site-config.xml</samplePath>
14</file>

  2. The configurations we added above will now be available from siteConfig -> Configuration.

    Multi-target Configuration - Site Config override configuration files now listed in "Site Config" -> "Configuration"

    Enable SAML2 in the configuration with identity provider My IDP1 for the site-config.staging.xml and use identity provider My IDP2 for the site-config.live.xml.

    SITENAME/sandbox/config/engine/site-config.staging.xml
     1<site>
 2  <version>2</version>
 3
 4  <security>
 5    <saml2>
 6      <enable>true</enable>
 7      <attributes>
 8        <mappings>
 9          <mapping>
10            <name>DisplayName</name>
11            <attribute>fullName</attribute>
12          </mapping>
13        </mappings>
14      </attributes>
15      <role>
16         <mappings>
17            <mapping>
18               <name>editor</name>
19               <role>ROLE_EDITOR</role>
20            </mapping>
21         </mappings>
22      </role>
23      <keystore>
24         <defaultCredential>my-site</defaultCredential>
25         <password>superSecretPassword</password>
26         <credentials>
27            <credential>
28               <name>my-site</name>
29               <password>anotherSecretPassword</password>
30            </credential>
31         </credentials>
32      </keystore>
33      <identityProviderName>My IDP1</identityProviderName>
34      <serviceProviderName>Crafter Engine</serviceProviderName>
35   </saml2>
36  </security>
37
38</site>

    For more information on SAML2 configuration, see Engine SAML2 Configuration

  3. Publish site-config.live.xml to live and site-config.staging.xml to staging.

    To publish the override configuration files setup above, open the Dashboard by clicking on the site name at the top left of the screen. Scroll to the My Recent Activity widget.

    Multi-target Configuration - New configuration files listed in the "My Recent Activity" widget in the Dashboard

    To publish the site-config.live.xml configuration file to publishing target live, put a check mark next to the file in the widget, then click on Approve & Publish from the context nav. Remember to set the Publishing Target to live in the Approve for Publish dialog

    Multi-target Configuration - Set "Publishing Target" to "live" in dialog for site-config.live.xml

    To publish the site-config.staging.xml file to publishing target staging put a check mark next to the file in the widget, then click on Approve & Publish from the context nav. Remember to set the Publishing Target to staging in the Approve for Publish dialog.

    The Engine site-config.live.xml configuration will now be loaded when viewing your site in live and the Engine site-config.staging.xml configuration will now be loaded when viewing your site in staging instead of the default Engine site-config.xml files