guideCKEditor Cloud Services On-Premises

The On-Premises version of CKEditor Cloud Services is an application designed to be installed and run on customer’s in-house servers and computing infrastructure, including private cloud. It is a highly scalable solution, designed to handle an unlimited number of concurrent connections. It contains all the features of Cloud Services available as SAAS.

The documentation below refers to a simplified version of CKEditor Cloud Services On-Premises, which was designed to be easy to setup and maintain (while maintaining all features), as well as lower the running costs, by reducing the number of servers required to run the whole application to the minimum.

If your usage scenario involves running CKEditor Cloud Services On-Premises for more than 50,000 concurrent connections, please contact us to discuss the most optimial setup for your needs.

The CKEditor Cloud Services On-premise installation requires two servers: one for running the application (“Application Server”) and another one for hosting the databases (“Database Server”).

# Preparing the Application Server

# Hardware requirements

For every 250 concurrent users CKEditor Cloud Services On-Premises requires 1 additional core of a CPU and 500MB of RAM.

  • 1 core and 500 MB RAM support up to 250 concurrent users.
  • 2 cores and 1 GB RAM support up to 500 concurrent users.
  • 4 cores and 2 GB RAM support up to 1,000 concurrent users.
  • 8 cores and 4 GB RAM support up to 2,000 concurrent users.
  • 16 cores and 8 GB RAM support up to 4,000 concurrent users.

The above calculations allow you to run CKEditor Cloud Services On-Premises without having to setup load balancers.

If you would like to run CKEditor Cloud Services On-Premises on multiple servers and use a load balancer, contact us for more details.


  • Concurrent user — a user who is active in a collaborative editing session. Idle users connected to the document do not increase much the server load.
  • The above configurations are able to handle even larger amount of active users, but due to the server load the response times will be significantly higher and as a result the user experience will be affected.
  • The CKEditor Cloud Services On-premise collaboration server performance was checked on Amazon AWS, using EC2 “t2” instances.

# 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 8 or newest:
  • pnpm – version 2.17 or newest: npm i pnpm@2.17 -g
  • pm2 – version 3.2.2 or newest: 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 newest
  • make

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 installation guide: .

# Preparing the Database Server

# Hardware requirements

The minimum database server requirements (for MySQL and Redis installation) to handle up to 8000 concurrent users is 2 cores and 4GB of RAM (a1.large equivalent on Amazon EC2).

If your installation has to support more than 8000 users, contact us to discuss the most optimal hardware setup for your needs.

# Software requirements

The database server should have two database engines installed: Redis and MySQL.

# Redis

  • Version 3.2.6 or newest.

  • Redis stores all temporary data related to collaboration and is used as cache. The storage requirements for Redis depend on the number of active documents.

  • The average size of one document is around 500 KB memory in Redis but this size depends on many factors — the document length, the number of users, the number of changes, etc. and it can grow to many megabytes.

  • Use Redis Cluster if the application needs to handle a large number of active users. Please contact us if this is the case.


  • Version 5.6 or 5.7.

  • Create the database and a user with the following permissions: ALTER, CREATE, DELETE, DROP, INDEX, INSERT, SELECT, TRIGGER, UPDATE, LOCK TABLES, REFERENCES. Example database creation script:

    CREATE DATABASE `cs-on-premises`
      DEFAULT COLLATE utf8mb4_unicode_ci;
  • Change the max_connections setting to allow more connections:

    set global max_connections = 1000;

    Every instance of CKEditor Cloud Services On-Premises uses a few connection pools. Therefore, it is necessary to increase the maximum number of connections to the database.

  • MySQL stores all persistent data like comments, users, environments information, etc. The storage requirements for MySQL depend on many factors.

  • If you want to use other SQL database like Microsoft SQL Server, PostgreSQL, etc. please contact us.

# Installation

Unpack the installation package on the Application Server.

  • Set execution permissions on the file.
  • Run sh

# Running the application

  • Create the configuration: copy app/config.json to a safe place and fill it with your configuration data. See the configuration example.
  • Configure logs directory - Logs.
  • Go to app/.
  • 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`
  • Check PM2 logs to verify if application working properly:
    sudo pm2 logs cs
  • Create the Environment with a SecretKey via Environments Management App and use this data to create TokenEndpoint.

# 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 – Restart all processes of the application.
  • pm2 reload cs – Reload all processes of application, 0-seconds downtime.
  • pm2 logs cs – Stream the logs file.
  • pm2 scale cs <number> – Scale the number of processes up or down.
  • pm2 delete cs all – Remove all processes.
  • pm2 list – List all processes.
  • pm2 -h – Help.

More information can be found in the PM2 documentation.

# Endpoints to communicate with CKEditor Cloud Services On-Premises

  • WebSockets endpoint
  • EasyImage upload endpoint
  • TokenEndpoint
    You should implement your own token endpoint using the data generated by Environment Management. Refer to the implementation example.

# Environments Management

Manage the Environments in CKEditor Cloud Services On-Premises using the Environments Management console application.

# Environments Management features

  • Create, modify and delete Environments.
  • Add a Service to the existing Environment or remove it.
  • Add a SecretKey to the existing Environment or remove it.

# Running the application

  • Fill the environments-management/config.json file with the configuration data. Example:
  "environmentsApiUrl": "",
  "environments_management_secret_key": "secret"
  • Go to the environments-management/src directory.
  • Run: node app.js.
  • Manage the Environments by choosing available options from the menu by using Arrow and Enter keys from your keyboard.

# Configuration example

    "mysql_host": "",
    "mysql_user": "root",
    "mysql_password": "password",
    "mysql_database": "cs-on-premises",
    "redis_host": "localhost",
    "redis_port": 6379,
    "redis_db": 1,
    "redis_password": "password", // optional
    "easyimage_storage_root_location": "/var/cs/easyimage/"
    "application_http_port": 8000,
    "logging_level": "error",
    "environments_management_secret_key": "secret"

# Logs

Make sure that write permissions are granted for 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`

# Generating a startup script