guideInstallation with Node.js

A valid license key is needed in order to install Collaboration Server 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 Collaboration Server On-Premises is to use Docker. See Setting up the application using the Docker container.

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

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 recommeneded you change it
    "database_password": "password",                          // optional (default: "password"), but it is highly recommeneded 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_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_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 recommeneded you change it
    "license_key": "your_license_key",                        // required
    "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)
}

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
      },
      {
        "host": "127.0.0.1",
        "port": 7001,
        "password": "" // optional
      },
      {
        "host": "127.0.0.1",
        "port": 7002,
        "password": "" // 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"
    }
    

# Configuring the database

At the moment the following databases are supported:

  • MySQL in version 5.6 or 5.7
  • 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_unicode_ci;;

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

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

  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 file 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:
    sudo 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:
sudo 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:
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.