guideNode.js

A valid license key is needed in order to install CKEditor Cloud Services On-Premises.
Contact us for a trial license key.

# Setting up the application directly on the server

Note: This approach to installing the application is more complicated and requires many dependencies. Therefore, the recommended way to install CKEditor Cloud Services On-Premises is to use Docker. See Setting up the application using the Docker container.

# Software prerequisites

In order to install CKEditor Cloud Services On-Premises on the application server, the following software must be installed on the server first:

  • node.js – version 10.x.
    Download it from: https://nodejs.org/en/download/package-manager/
  • pnpm – version 2.25.x:
    npm i pnpm@2.25 -g
    
  • pm2 – version 3.2.2 or newer:
    npm i pm2 -g
    
  • libpng-dev:
    sudo apt install libpng-dev
    
  • python – version 2.7 is recommended, version 3.x is not supported
  • gcc – version 4.9.x or newer
  • make
  • autoconf – 2.69 or newer
  • libtool – 2.4.2 or newer
  • pkg-config – 0.26 or newer
  • nasm – 2.10.09 or newer

On Ubuntu you can install gcc and make with build-essential:

sudo apt install build-essential

# Problem with node-gyp

In case of problems with node-gyp, please check the node-gyp installation guide.

# Installation

Unpack the installation package on the Application Server.

  1. Set execution permissions on the setup.sh file.
  2. Run:
    sh setup.sh
    

# Running the application

  1. Create the configuration.
    Copy app/config.json to a safe place and fill it with your configuration data. See the configuration example.
  2. Configure the logs directory — see Logs.
  3. Go to app/.
  4. Run:
    sudo CS_CONFIG_PATH=[path/to/your/config] pm2 start
    
    By default the application will be run using all available CPUs but it can be changed by setting the CS_INSTANCES variable:
    sudo CS_INSTANCES=1 CS_CONFIG_PATH=[path/to/your/config] pm2 start
    
  5. Check PM2 logs to verify if the application starts properly:
    sudo pm2 logs cs
    
  6. Create the Environment with a SecretKey via Environments Management App. Use this data to create the token endpoint and run tests.
  7. Run tests to verify if the system works properly — see Testing the CKEditor Cloud Services On-Premises application.
  8. Configure the server endpoints in the CKEditor Collaboration web application to communicate with the CKEditor Cloud Services On-Premises application — see Setting endpoints.

# Application management

We recommend using PM2 software for application management. Below you can find a list of some of the most important commands:

  • pm2 restart cs – Restarts all processes of the application.
  • pm2 reload cs – Reloads all processes of the application, 0-seconds downtime.
  • pm2 logs cs --lines 1000000 – Streams the logs file.
  • pm2 scale cs <number> – Scales the number of processes up or down.
  • pm2 delete cs all – Removes all processes.
  • pm2 list – Lists all processes.
  • pm2 -h – Help.

More information can be found in the PM2 documentation.

# Configuration example

{
    "mysql_host": "127.0.0.1",
    "mysql_port": "3306",                                     // optional (default: 3306)
    "mysql_user": "root",
    "mysql_password": "password",
    "mysql_database": "cs-on-premises",
    "redis_host": "localhost",
    "redis_port": 6379,                                       // optional (default: 6379)
    "redis_db": 1,
    "redis_password": "",                                     // optional (default: "")
    "redis_cluster_nodes": "",                                // optional (default: [])
    "easyimage_storage_root_location": "",                    // optional (default: "/var/cs/easyimage/")
    "application_http_port": 8000,
    "application_external_endpoint": "",                      // optional (default: "")
    "environments_management_secret_key": "secret",
    "license_key": "your_license_key"
}

Notes:

  • Please save you configuration outside the application package directory. This prevents from overwriting your configuration during the application update process.
  • Set easyimage_storage_root_location outside the application package directory. This prevents from unwanted changes or deletions in your images made during the application update process.
  • Without a correct license_key the application will not start.
  • Example of redis_cluster_nodes variable:
    [
      {
        "host": "127.0.0.1",
        "port": 7000,
        "password": "" // optional
      },
      {
        "host": "127.0.0.1",
        "port": 7001,
        "password": "" // optional
      },
      {
        "host": "127.0.0.1",
        "port": 7002,
        "password": "" // optional
      }
    ]
    

# Logs

Make sure that write permissions are granted for the logs directory.

By default all logs are stored in the /var/log/cs/cs.log file but it is strongly recommended to change this location by using the CS_LOGS_PATH variable:

sudo CS_LOGS_PATH=[path/to/logs] CS_CONFIG_PATH=[path/to/your/config] pm2 start

Set CS_LOGS_PATH outside the application package directory. This prevents from unwanted changes in your logs made during the application update process.

# Generating a startup script

See http://pm2.keymetrics.io/docs/usage/startup/.

# Upgrading to a new version

# Very safe

  1. Unzip the package with a new version to a separate directory, for example: new_version_dir.
  2. Compare your current configuration with new_version_dir/app/config.json. If the schema properties changed, apply these changes.
  3. Change application_http_port to some free port, not used in the currently running application.
  4. Go to new_version_dir/ and run the installation — see Installation.
  5. Go to new_version_dir/app and start the test application:
    sudo CS_CONFIG_PATH=[path/to/your/config] pm2 start src/index.js --name test_cs
    
  6. Run tests — see Testing the CKEditor Cloud Services On-Premises application.
  7. If the new version of the application works properly, shut it down:
    sudo pm2 delete test_cs
    
  8. Change application_http_port to the previous port used in the application.
  9. Go to new_version_dir/app/.
  10. Stop the current version of the application and run the new version:
sudo pm2 delete all && sudo pm2 kill && sudo CS_CONFIG_PATH=[path/to/your/config] pm2 start
  1. Verify if everything is working correctly.
  2. If yes, you can delete the previous version. If not, stop the new version and run the previous version again.

# Less safe

  1. Unzip the package with a new version to a separate directory, for example: new_version_dir.
  2. Compare your current configuration with new_version_dir/app/config.json. If the schema properties changed, please apply these changes.
  3. Remove all current version files and directories (your application will still work with PM2). Make sure that all sensitive data (logs, Easy Image images, configuration) is outside current_version_dir:
    sudo rm -rf current_version_dir/*
    
  4. Copy new files to current_version_dir:
    cp -a new_version_dir/* current_version_dir
    
  5. Restart your application:
    sudo pm2 delete all && sudo pm2 kill && sudo CS_CONFIG_PATH=[path/to/your/config] pm2 start
    
  6. Run tests — see Testing the CKEditor Cloud Services On-Premises application.