Static content bundling service

Static content includes *.js-files and *.css-files that are located in the Creatio file system and are required to display the Creatio UI in the browser. *.js files might contain client module code or other JavaScript data. Static content has several distinct features covered in a separate article: Packages file content. By default, static content is enabled in Creatio, which improves performance.

If the browser must initially load a large amount of static content, this can significantly affect the loading time.

Ways to optimize the page loading time:

• Minification. Reduces the size of *.css, *.js, and *.html files. This implies removal of commented out code as well as superfluous line breaks, leading and trailing spaces. This reduces the size of the original file by 10-20%.
• Bundling, i. e., generation of bundle files. Optimizes the performance by combining the static files of the same type into a single bundle file. Reduces the number of requests.

Minification and bundling are both performed by the static content bundling service. Most web apps are delivered with minified and bundled files. Since the Creatio configuration and static content can change during the life cycle, the service runs minification and bundling automatically when necessary.

Components of the bundling service:

• ContentService. The service that minifies and bundles Creatio files. Deployed independently of Creatio.
• ContentWatcher. A utility that interacts with Creatio files and ContentService to ensure timely minification and bundling.

To improve performance, the app is configured to generate minified bundle files by default.

View the bundling service flowchart in the figure below.

View the static content bundling workflow in the figure below.

Requirements for the correct operation of the bundling service:

• Uninterrupted operation of ContentService and ContentWatcher.
• ContentService and ContentWatcher access to static content.
• Ability to access static content from ContentService to ContentWatcher via HTTP.
• A valid configuration of ContentService and ContentWatcher.

You must configure the bundling service for Creatio on-site. Creato cloud has the bundling service configured out-of-the-box.

ContentService 

ContentService is the service that minifies and bundles Creatio static content. Deployed independently of Creatio.

ContentService endpoints 

ContentService can be paired with ContentWatcher or work independently. If the ContentService works independently, access the endpoints manually or using a third-party automation, for example, when deploying or updating Creatio.

The / endpoint takes no parameters. Other endpoints accept various parameters passed within the request body in JSON.

Configure ContentService 

The bundling service does not require a change in the ContentService configuration to work correctly. By default, the bundling service comes optimally configured, but you can change the settings to boost performance or enable additional functionality.

Parallelism speeds up minification and bundling. The UseParallelism setting toggles parallelism. If parallelism is enabled, file processing operations are split into independent blocks. Depending on the infrastructure, this can speed up the bundling service significantly. Parallelism significantly increases the load on the CPU as well as network and/or drives.

Automatic cancellation of operations prevents overusing resources when repeatedly requesting static content if the previous request has not been completed. The UseCancellation setting, which is enabled by default, toggles automatic cancellation of operations. If automatic cancellation is enabled and the bundling receives a request to process static content that is already being processed, the bundling service schedules the next operation and tries to cancel the current operation.

On a standard exit (for example, by pressing Ctrl + C in the console or stopping the pool via IIS), the bundling service stops receiving new requests as well as tries to end the ongoing processing safely. The safe termination option that the service uses depends on the value of the UseCancellation setting.

Safe termination options:

• If the UseCancellation setting is enabled, Creatio terminates the execution of cancelable tasks.
• If the UseCancellation setting is disabled or a task is not cancelable, Creatio awaits until the started tasks are complete.

Dictionary is the schema bundling order. Use it to optimize the creation of bundle files. Schemas not in the dictionary are included in the bundle files in alphabetical order. Specify the path to the BundlesDictionary.txt file of the dictionary in the DictionaryPath setting of the BundleGeneration block. The BundlesDictionary.txt file is pre-generated and delivered with ContentService. We recommend generating a custom dictionary for heavily customized instances.

To generate a custom dictionary:

1. Download the *.zip archive that contains the FileListGetter utility. The *.zip-archive is available via this link. Please note that the utility requires the .NET Framework package version 4.7.2 or later in the Creatio instance to generate a custom dictionary.
2. Open the app page to generate a dictionary.
3. Open the developer tools and go to the Network tab. Learn more about developer tools in a separate article: Front-end debugging.
4. Refresh the page to load static content files.
5. Right-click the downloaded file area and save the *.har file to the HarFiles directory of the FileListGetter utility.
6. Repeat steps 1 through 4 for all app pages to generate a dictionary.
7. Copy the BundlesDictionary.txt file to the Output directory of the FileListGetter utility.
8. Run the FileListGetter.exe utility file.

As a result, the BundlesDictionary.txt file in the Output directory will contain a custom dictionary.

Ignoring files lets you specify files that must not be bundled. The IgnoredFileNamePatterns setting of the BundleGeneration block manages files to ignore.

Files when bundling:

• Static content files that are not valid RequireJS modules. Browsers cannot load these files from bundle files.
• Static content configuration files that are loaded in a special way and must not be bundled.

ContentWatcher 

ContentWatcher is a utility that interacts with Creatio files and ContentService to ensure timely minification and bundling.

Actions that ContentWatcher performs:

• Monitors the specified static content files to see if their content changes.
• Notifies ContentService that the file contents are updated and passes the appropriate parameters to the service.

ContentWatcher watches for changes to the _MetaInfo.json file, which changes when static content is updated. ContentWatcher then sends a notification to ContentService about a pending bundling. ContentWatcher can track changes to any file and send a notification to any URL. For the correct orchestration of Creatio, ContentWatcher, and ContentService, configure ContentWatcher.

ContentWatcher can monitor multiple Creatio instances.

http://[Address of ContentService]/process-content

If ContentWatcher and ContentService are deployed on Linux (including Docker) and the Creatio file system is shared with ContentWatcher and ContentService, specify the paths to the directories where the Creatio file system is mounted in the Directory and ContentPath settings. For example, if the \conf directory of the Creatio instance is mounted into a container in the /app/content/ path, specify /app/content/ in the Directory setting and /app/content/content in the ContentPath setting.

{
    "ContentServiceUrl": "http://host.docker.internal:29572/process-content",
    "ConfigurationRefreshInterval": "86400000",
    "DefaultFileFilter": "_MetaInfo.json",
    "ContentWorkers": [
        {
            "Name": "Site 1",
            "Directory": "/path_to_creatio_conf_folder/",
            "ContentWorkerArguments": {
                    "key": "ContentPath",
                    "value": "/path_to_creatio_conf_folder/content"
                }
            ]
        }
    ]
}

Below is a diagram of the interaction of ContentService, ContentWatcher and Creatio, which are deployed using the default configuration. The diagram takes into account the general settings.

InfluxDb metrics 

ContentWatcher and ContentService enable recording the metrics of successful and unsuccessful operations in InfluxDb. The InfluxDb documentation is available on the official InfluxDb website. Configure the connection to InfluxDb in the appsettings.json file using the parameter values of the InfluxDbConnectionString connection string.

"InfluxDbConnectionString": "url=http://1.2.3.4:5678; db=content; user=User1; password=QwErTy; version=v_1_3"

View the parameters of the InfluxDbConnectionString connection string in the table below.

View the InfluxDb metrics that ContentService and ContentWatcher record in the table below.

Deploy the static content bundling service 

Deploy the static content bundling service in Docker. Docker documentation is available on the official Docker website.

To deploy the bundling service, use a server running a Linux OS (we recommend using stable versions of Ubuntu or Debian), with a stable version of Docker installed and configured. The server must be allowed to query the Docker Hub image library. The server serves as a host machine for the components of the bundling service.

To deploy the bundling service:

1. Download the *.zip archive that contains the service configuration files. The *.zip-archive is available via this link.

2. Unpack the archive to an arbitrary directory (for example, \opt\services).

   Service configuration structure:

   • \etc\content-watcher\appsettings.json is the ContentWatcher configuration file.
   • docker-compose.yml is the configuration file of the docker-compose utility.
   • *.env is the file that contains the environment variables to run the components.

3. Specify the following parameters in the .\docker-compose\*.env file:

   • ContentServicePort. The port where ContentService runs.
   • ContentPath. The container’s built-in directory of sites and their contents specified.
4. Configure the list of sites to track using ContentWatcher.

5. Download the required docker service images to the directory where the configuration files are deployed, for example, \opt\services.

   Command that downloads the required docker service images

   docker-compose pull
   

   As a result of executing the command, Docker will download the necessary docker service images from the official Docker Hub website.

   steps to download docker service images if online access is disabled on the server:

   1. Download the necessary images manually on a public machine (see the docker-compose.yml configuration file).

   2. Transfer the downloaded docker images to the target machine as files.

      Command that transfers the downloaded docker service images

      docker export/import
      

6. Start the services.

   Command that starts the services

   docker-compose up -d 
   

   As a result, Docker will start the services.

7. Verify that the bundling service is deployed correctly. To do this, make a GET request to the address below.

   {Server IP address}: {CONTENT_SERVICE_PORT}
   

   17.17.17.7:9999
   

   Server IP address is the IP address of the server that contains the installed services.

   CONTENT_SERVICE_PORT is the port where ContentService runs. Matches the port specified in the .\docker-compose\.*env file on step 2.

   As a result of the command, you will receive the Service is running response.