Thumbnail generation

NodeServices folder contains JavaScript files that are using to generate thumbnails.
Litium invokes JavaScript code from .Net to generate page and block thumbnails on the server side.
Thumbnail generation on the server side allows to avoid doing it in the browser, which has some limitations and known issues.

Requirements

1. Node.js:

• For installation in server environments we recommend the LTS version of Node.js.
• Make sure that node and npm are available as environment variables so that .Net can find and invoke them.

Installation

Litium automatically installs, deploys and configures everything by default. No additional action is required. The JavaScript files are deployed to Src\Files\NodeServices, under a folder named after the Litium version in question. Litium also executes npm install against that folder to make sure all dependencies are installed. The feature GenerateThumbnailsAtServerSide is also activated be default.

Manual installation

As mentioned above, the default installation deploys JavaScript files to Src\Files\NodeServices, under a folder named after the current Litium version. To use another folder:

1. Copy the NodeServices folder in packages\Litium.Web.Setup.Core\tools to the desired folder.

2. Open the command prompt and navigate to this folder, which should contain package.json files. Then you execute the command npm install. Be careful and make sure you do this correctly.

3. Make sure AppPool is running under an account that has read-permission to the folder.

4. Configure ProjectPath in appsettings.json to point to the folder:

"NodeService": {
      "GenerateThumbnailsAtServerSide": true,
      "ProjectPath": "path\\to\\NodeServices\\folder\\that\\contains\\packagejson"
    }

Configuration

Deactivate GenerateThumbnailsAtServerSide

This feature is activated by default. To deactivate it, find the NodeService configuration in appsettings.json and set GenerateThumbnailsAtServerSide to false:

"NodeService": {
      "GenerateThumbnailsAtServerSide": false,
      "InvocationTimeoutMilliseconds": 60000
    }

InvocationTimeoutMilliseconds

InvocationTimeoutMilliseconds is the maximum duration in milliseconds that .NET code should wait for Node.js RPC calls to return. If Node.js does not return within this time, the .Net application will throw an exception. The default value is 60 seconds. This is to make sure the request has enough time for the cold-start of the website, to render it and capture the thumbnail.

NavigationTimeoutMilliseconds

NavigationTimeoutMilliseconds is the maximum navigation time in milliseconds that Node.js should wait for a browser to finish a navigation. If the load event is not fired within this time, an exception will be thrown. The default value is 30 seconds. Pass 0 to disable.

ProjectPath

This path should be used to have one common NodeServices folder for multiple web instances. The value of ProjectPath should be the path to the folder that contains the package.json file. Make sure all required steps are covered as described in Manual installation.

Note: the content of NodeServices should match the Litium version, since they depend on each other. Running mismatched versions may lead to unexpected errors.

ServerUri

ServerUri must be used when Litium is running inside the container with port mapping, ServerUri should have the port number on that the Litium is running. For example, it can be Docker. In case if Litium is running on port 443,
and Docker is mapped on the host to port 8443, then ServerUri must have port 443.

BrowserExecutablePath

Path to a Chromium or Chrome executable to run instead of the bundled Chromium. This should be used in case you want to use a specific version of Chrome, or Chromium. One particular case is when you need to generate thumbnails for Video at the server side. Litium uses Puppeteer under the hood to generate pages and blocks' thumbnails. There is an issue where MP4 video for example, cannot be played on Chromium. Some other features might not work with Chromium, as described here.

To be able to generate thumbnails for video, at the server side, we can configure Puppeteer to use Chrome instead, for example:

"NodeService": {
      "GenerateThumbnailsAtServerSide": true,
      "InvocationTimeoutMilliseconds": 60000,
      "BrowserExecutablePath": "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe"
    }

Make sure the compatible version of Chrome is used as described in this article. To check what version of Chrome we have, open chrome://version/ in Chrome. For example, this says we are using Chrome 75:

Then edit Src\Files\NodeServices/package.json file, or the one in your custom folder if Manual installation was used, to remove puppeteer dependency, then execute this command to install puppeteer-core which is compatible with Chrome 75:

npm install puppeteer-core@chrome-75

Note: if BrowserExecutablePath is not used, by setting it as empty, puppeteer should be used instead of puppeteer-core.

Troubleshooting

Debug and error messages can be found in the Event log page, or the log file. Common problems are:

• node or npm could not be found: make sure they can be found by setting the system environment variable PATH correctly.
• Unable to create or access folder: make sure Application Pool is running under an account that has read and write permission to the ProjectPath folder. Running Application Pool under ApplicationPoolIdentity can be a problem when the npm command is executed.
• Error: EPERM: operation not permitted, mkdir 'C:\Windows\system32\config\systemprofile\AppData\Roaming\npm': make sure Load User Profile is enabled for ApplicationPool.

If an error occurs during the installation process, thumbnail generation on the server side will be disabled, generateThumbnailsAtServerSide will be set to false and thumbnails will be generated by the browser.