CKEditor Ecosystem Documentation
Search
Home/Cloud Services/On-Premises

guideInstallation with Node.js - Not recommended

This approach to installing the application is not recommended.

The CKEditor Collaboration Server On-Premises is developed, tested and maintained using a docker images.
Thanks to this your production environment is as close to this where we test our products as possible.
Docker images handle all dependencies, which guaranties compatibility with our products.
All that is not possible by using a pure Node.js installation, where you need to take care about the whole environment your application is running on.

However, if your case requires using an installation without Docker, please contact us.

A valid license key is needed in order to install Collaboration Server On-Premises.
Contact us for a trial license key.

For evaluation and testing purposes, you can follow the Quick-start guide, where we provide an easy-to-use script for setting up all necessary infrastructure for Collaboration Server On-Premises on your local machine.

This approach is not recommended. Please use the Docker approach if possible.

Click here to show the Node.js instructions anyway.

# 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 Collaboration Server On-Premises is to use Docker. See Setting up the application using the containerization.

# Requirements

For every 250 concurrent users, Collaboration Server On-Premises requires 1 additional core of 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.

These calculations allow you to run Collaboration Server On-Premises without having to set up load balancers.

# Software prerequisites

In order to install Collaboration Server On-Premises on the application server, the following software must be installed on the server first:

  • node.js – version 14.x.
    Download it from: https://nodejs.org/en/download/package-manager/
  • pnpm – version 4.3.x:
    npm i pnpm@4.3.0 -g
  • pm2 – version 3.2.2 or newer:
    npm i pm2 -g
  • libpng-dev:
    sudo apt install libpng-dev
  • python – version 3.x is recommended, version 2.7 is deprecated
  • 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
  • dependencies for Chrome

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

sudo apt install build-essential

To install Chrome dependencies on Ubuntu you can use the following command:

sudo apt install libgbm-dev gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget

# 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 file config.json in 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:
    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:
    CS_INSTANCES=1 CS_CONFIG_PATH=[path/to/your/config] pm2 start
  5. Check PM2 logs to verify if the application starts properly:
    pm2 logs cs
  6. Create the Environment with a Access Key via Cloud Services Management Panel. Use this data to create the token endpoint and run tests.
  7. Run tests to verify if the system works properly — see Running tests without Docker.
  8. Configure the server endpoints in the CKEditor Collaboration web application to communicate with the Collaboration Server 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.

Please ensure that you have all needed privileges to use needed PM2 commands.
More information can be found in the PM2 documentation.

# Configuration example

{
    "database_driver": "mysql",                                // optional (default: "mysql")
    "database_host": "127.0.0.1",                              // required
    "database_port": "3306",                                   // optional (default: 3306)
    "database_user": "root",                                   // optional (default: "root"), but it is highly recommended you change it
    "database_password": "password",                           // optional (default: "password"), but it is highly recommended you change it
    "database_database": "cs-on-premises",                     // optional (default: "cs-on-premises")
    "database_schema": "cs-on-premises",                       // optional (default: "cs-on-premises", used for Postgres driver)
    "database_ssl_enable": "",                                 // optional
    "database_ssl_ca": "",                                     // optional
    "database_ssl_key": "",                                    // optional
    "database_ssl_cert": "",                                   // optional
    "redis_host": "localhost",                                 // required
    "redis_port": 6379,                                        // optional (default: 6379)
    "redis_db": 1,                                             // optional (default: 1)
    "redis_password": "",                                      // optional
    "redis_user": "",                                          // optional
    "redis_tls_ca": "",                                        // optional
    "redis_tls_key": "",                                       // optional
    "redis_tls_cert": "",                                      // optional
    "redis_tls_enable": false,                                 // optional (default: false), set to true when connecting to AWS ElastiCache with TLS enabled
    "redis_disable_dns_lookup": false,                         // optional (default: false), set to true when connecting to AWS ElastiCache Cluster with TLS enabled
    "redis_cluster_nodes": "",                                 // optional
    "application_http_port": 8000,                             // optional (default: 8000)
    "application_external_endpoint": "",                       // optional
    "environments_management_secret_key": "secret",            // optional (default: "secret"), but it is highly recommended you change it
    "license_key": "your_license_key",                         // required
      "migrate_only": false,                                     // optional (default: false)
    "storage_driver": "filesystem",                            // optional (default: "filesystem")
    "storage_location": "/var/cs/easyimage",                   // optional (default: "/var/cs/easyimage", required for file system driver)
    "storage_region": "",                                      // optional (required for AWS S3 driver)
    "storage_access_key_id": "",                               // optional (required for AWS S3 driver)
    "storage_secret_access_key": "",                           // optional (required for AWS S3 driver)
    "storage_bucket": "",                                      // optional (required for AWS S3 driver)
    "storage_endpoint": "",                                    // optional (required for AWS S3 driver)
    "storage_account_name": "",                                // optional (required for Azure Blob Storage driver)
    "storage_account_key": "",                                 // optional (required for Azure Blob Storage driver)
    "storage_container": "",                                   // optional (required for Azure Blob Storage driver)
    "collaboration_storage_driver": "database",                // optional (default: "database")
    "collaboration_storage_location": "/var/cs/collaboration", // optional (default: "/var/cs/easyimage", required for file system driver)
    "collaboration_storage_access_key_id": "",                 // optional (required for AWS S3 driver)
    "collaboration_storage_secret_access_key": "",             // optional (required for AWS S3 driver)
    "collaboration_storage_region": "",                        // optional (required for AWS S3 driver)
    "collaboration_storage_endpoint": "",                      // optional (required for AWS S3 driver)
    "collaboration_storage_bucket": "",                        // optional (required for AWS S3 driver)
    "collaboration_storage_account_name": "",                  // optional (required for Azure Blob Storage driver)
    "collaboration_storage_account_key": "",                   // optional (required for Azure Blob Storage driver)
    "collaboration_storage_container": "",                     // optional (required for Azure Blob Storage driver)
    "use_built_in_collaboration_worker": true,                 // optional (default: true)
    "enable_metric_logs": false                                // optional (default: false)
}

More information about the storage configuration of the Easy Image feature you can find here.

Notes:

  • Please save you configuration outside the application package directory. This prevents from overwriting your configuration 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
    "user": "" // optional
  },
  {
    "host": "127.0.0.1",
    "port": 7001,
    "password": "", // optional
    "user": "" // optional
  },
  {
    "host": "127.0.0.1",
    "port": 7002,
    "password": "", // optional
    "user": "" // optional
  }
]
  • If your database server is configured to require SSL connections, you can use database_ssl_ca, database_ssl_key and database_ssl_cert to pass certificates to the database driver. You can pass certificates directly with certificate content or as path/to/certificate.crt. Example:
    {
  "database_ssl_ca": "-----BEGIN CERTIFICATE-----\nMIIEBjCCAu6gAwIBAgIJAMc0ZzaSUK51MA0GCSqGSIb3DQEBCwUAMIGPMQswCQYD\nVQQGEwJVUzEQMA4GA1UEBwwHU2VhdHRsZTETMBEGA1UECAwKV2FzaGluZ3RvbjEi\n............\nzPW4CXXvhLmE02TA9/ZeCw3KkHIwicNuEfa=\n-----END CERTIFICATE-----",
  "database_ssl_cert": "/var/cs/ssl/client-certificate.pem"
}
  • If your database server is configured to require SSL connections and the certificate of the database server is signed by a trusted third party, you can set DATABASE_SSL_ENABLE=true instead of passing the certificates.

# Configuring the database

At the moment the following databases are supported:

  • MySQL in version 5.7 (minimal supported version) or 8.0 (recommended).
  • PostgreSQL in version 12

# MySQL

MySQL is selected as default so you do not need to explicitly specify this driver. Example configuration:

{
    "database_host": "127.0.0.1",
    "database_port": "3306",
    "database_user": "root",
    "database_password": "password",
    "database_database": "cs-on-premises",
    "database_ssl_ca": "server-certificate-content or path/to/server-certificate.crt",
    "database_ssl_key": "client-key-content or path/to/client-key.key",
    "database_ssl_cert": "client-certificate-content or path/to/client-certificate.crt",

    // ...
}

The values above are examples and should be changed.

The database should be created before running the application. It can be created with the following init.sql script:

CREATE DATABASE `cs-on-premises`
    DEFAULT CHARACTER SET utf8mb4
    DEFAULT COLLATE utf8mb4_bin;

# PostgreSQL

To use PostgreSQL you have to set database_driver to postgres. Example configuration:

{
    "database_driver": "postgres",
    "database_host": "127.0.0.1",
    "database_port": "5432",
    "database_user": "postgres",
    "database_password": "password",
    "database_database": "cksource",
    "database_schema": "cs-on-premises",
    "database_ssl_ca": "server-certificate-content or path/to/server-certificate.crt",
    "database_ssl_key": "client-key-content or path/to/client-key.key",
    "database_ssl_cert": "client-certificate-content or path/to/client-certificate.crt",

    // ...
}

The values above are examples and should be changed.

The database and schema should be created before running the application. It can be created with the following init.sql script:

CREATE DATABASE "cksource";
\connect "cksource";
CREATE SCHEMA "cs-on-premises";

# 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:

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

  1. Install the software prerequisites if some versions have changed or if new ones have been added — see Software prerequisites.
  2. Unzip the package with a new version to a separate directory, for example: new_version_dir.
  3. Check the changelog for breaking changes and adjust the configuration if needed.
  4. Create a new test SQL database or schema (if you are using a PostgresSQL database) and use it in the configuration file. See the database_database variable for MySQL or database_schema variable for PostgresSQL — refer to the Configuring the database section.
  5. Change the Redis database in the configuration file to the one that is not used in the currently running application — see the redis_db variable.
  6. Change application_http_port to some free port that is not used in the currently running application.
  7. Go to new_version_dir and run the installation — see Installation.
  8. Go to new_version_dir/app and start the test application:
    CS_CONFIG_PATH=[path/to/your/config] pm2 start src/index.js --name test_cs
  9. Run tests — see Running tests without Docker.
  10. If the new version of the application works properly, shut it down:
pm2 delete test_cs
  1. Change database_database/database_schema and redis_db to the previous values used in the application.
  2. Change application_http_port to the previous port used in the application.
  3. Go to new_version_dir/app/.
  4. Stop the current version of the application and run the new version:
pm2 delete all && pm2 kill && 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.