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

guideInstallation with Docker

To provide stability and scalability, we recommend using container orchestration in production.
Check the examples to learn how to run the Collaboration Server On-Premises in production.

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.

# Setting up the application using the Docker container

Follow the steps below to install Collaboration Server On-Premises using the Docker container.

  1. Use the instructions from the CKEditor Ecosystem customer dashboard to log into the Collaboration Server On-Premises Docker Registry and pull the Docker image.
  2. Containerize the application using docker or docker-compose.
  3. Create the Environment with an Access Key via the Cloud Services Management Panel. Use this data to create the token endpoint and run tests.
  4. Run tests to verify if the system works properly — see the Running tests using Docker guide.
  5. Configure the server endpoints in the CKEditor Collaboration web application to communicate with the Collaboration Server On-Premises application — see the Setting endpoints guide.

# Containerize example using docker

Launch the Docker container:

docker run --init -p 8000:8000 -v /path/to/your/dir:/var/cs/easyimage -e DATABASE_HOST=[your_mysql_host] -e DATABASE_USER=[your_mysql_user] -e DATABASE_PASSWORD=[your_mysql_password] -e REDIS_HOST=[your_redis_host] -e LICENSE_KEY=[your_license_key] -e STORAGE_DRIVER=filesystem -e STORAGE_LOCATION=/var/cs/easyimage docker.cke-cs.com/cs:[version]

Notes:

  • If you use file system for image storage, you should always mount the docker volume -v /path/to/your/dir:/var/cs/easyimage to preserve uploaded files in case your Docker container gets removed. You can find more information about the storage of the Easy Image feature here.
  • Use environment variables to configure the application. See the Docker container environment variables guide. Examples:
    • If an SQL database and Redis are hosted on 192.168.118.27, you should pass the address through the DATABASE_HOST and REDIS_HOST variables:
      docker run --init -p 8000:8000 -v ~/easyimage_files:/var/cs/easyimage -e DATABASE_HOST=192.168.118.27 -e REDIS_HOST=192.168.118.27 -e DATABASE_USER=root -e DATABASE_PASSWORD=root_password -e LICENSE_KEY=[your_license_key] -e STORAGE_DRIVER=filesystem -e STORAGE_LOCATION=/var/cs/easyimage docker.cke-cs.com/cs:[version]
    • If you want to change the port on which the application will be served to 5000, override the APPLICATION_HTTP_PORT variable and change exposed ports:
      docker run --init -p 5000:5000 -v ~/easyimage_files:/var/cs/easyimage -e APPLICATION_HTTP_PORT=5000 -e DATABASE_HOST=192.168.118.27 -e REDIS_HOST=192.168.118.27 -e DATABASE_USER=root -e DATABASE_PASSWORD=root_password -e LICENSE_KEY=[your_license_key] -e STORAGE_DRIVER=filesystem -e STORAGE_LOCATION=/var/cs/easyimage docker.cke-cs.com/cs:[version]
  • You should override the ENVIRONMENTS_MANAGEMENT_SECRET_KEY variable using a unique and hard to guess string due to security reasons.
  • The application will not start without a correct LICENSE_KEY.

# Containerize example using docker-compose

Use the steps below to containerize the application using docker-compose.

Please bear in mind that docker-compose is useful for development purposes. This, however, does not fulfill our architecture recommendations for production environments. This is why we created the example scripts and added information about the recommended infrastructure for AWS.

# Example with MySQL

  1. Create the docker-compose.yml file:
    version: "2.2"
services:
  mysql-database:
    image: mysql:5.7.38
    platform: linux/amd64
    environment:
      MYSQL_ROOT_PASSWORD: password
    volumes:
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro

  redis:
    image: redis:6.2.7

  ckeditor-cs:
    image: docker.cke-cs.com/cs:[version]
    depends_on:
      - redis
      - mysql-database
    ports:
      - "8000:8000"
    restart: always
    init: true
    environment:
      DATABASE_HOST: mysql-database
      DATABASE_USER: root
      DATABASE_PASSWORD: password
      REDIS_HOST: redis
      ENVIRONMENTS_MANAGEMENT_SECRET_KEY: secret
      LICENSE_KEY: your_license_key
      STORAGE_DRIVER: filesystem
      STORAGE_LOCATION: /var/cs/easyimage
    volumes:
      - ~/easyimage_files:/var/cs/easyimage
  2. Create the init.sql file:
    CREATE DATABASE `cs-on-premises`
  DEFAULT CHARACTER SET utf8mb4
  DEFAULT COLLATE utf8mb4_unicode_ci;
  3. Run:
    docker-compose up

# Example with PostgreSQL

  1. Create the docker-compose.yml file:
    version: "2.2"
services:
  postgres-database:
    image: postgres:12.12
    environment:
      - POSTGRES_PASSWORD=password
    volumes:
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro

  redis:
    image: redis:6.2.7

  ckeditor-cs-postgres:
    image: docker.cke-cs.com/cs:[version]
    depends_on:
      - redis
      - postgres-database
    ports:
      - "8000:8000"
    restart: always
    init: true
    environment:
      DATABASE_DRIVER: postgres
      DATABASE_HOST: postgres-database
      DATABASE_PORT: 5432
      DATABASE_USER: postgres
      DATABASE_PASSWORD: password
      DATABASE_DATABASE: cksource
      DATABASE_SCHEMA: cke-cs
      REDIS_HOST: redis
      ENVIRONMENTS_MANAGEMENT_SECRET_KEY: secret
      LICENSE_KEY: your_license_key
      STORAGE_DRIVER: filesystem
      STORAGE_LOCATION: /var/cs/easyimage
    volumes:
      - ~/easyimage_files:/var/cs/easyimage
  2. Create the init.sql file:
    CREATE DATABASE "cksource";
\connect "cksource";
CREATE SCHEMA "cke-cs";
  3. Run:
    docker-compose up

# Notes

  • If you use file system for image storage, you should always mount the Docker volume to preserve uploaded files in case your Docker container gets removed. You can find more information about the storage of the Easy Image feature here.
  • Use environment variables to configure the application. See the Docker container environment variables guide.
  • You should override the ENVIRONMENTS_MANAGEMENT_SECRET_KEY variable using a unique and hard to guess string due to security reasons.
  • The application will not start without a correct LICENSE_KEY
  • If you use collaboration features (like document storage, import and export, or connection optimizer) intensively, we recommend using Collaboration Worker to improve reliability.

# Configuring the database

The following databases are currently supported:

  • MySQL in version 5.7
  • PostgreSQL in version 12

# MySQL

MySQL is selected as default so you do not need to explicitly specify this driver. Environment variables for database configuration that can be used with this driver:

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"

These values are only examples and should be changed.

The database should be created before running the application. It can be created using 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. Environment variables for database configuration that can be used with this driver:

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"

These values are only examples and should be changed.

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

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

# Docker container environment variables

These are the environment variables that are used to configure the application when the container is started.

DATABASE_DRIVER                          - optional (default: "mysql")
DATABASE_HOST                            - required
DATABASE_PORT                            - optional (default: 3306)
DATABASE_USER                            - optional (default: "root"), but it is highly recommeneded you change it
DATABASE_PASSWORD                        - optional (default: "password"), but it is highly recommeneded you change it
DATABASE_DATABASE                        - optional (default: "cs-on-premises")
DATABASE_SCHEMA                          - 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                               - required
REDIS_PORT                               - optional (default: 6379)
REDIS_DB                                 - optional (default: 1)
REDIS_PASSWORD                           - optional
REDIS_TLS_CA                             - optional
REDIS_TLS_KEY                            - optional
REDIS_TLS_CERT                           - optional
REDIS_TLS_ENABLE                         - optional (default: false)
REDIS_DISABLE_DNS_LOOKUP                 - optional (default: false)
REDIS_CLUSTER_NODES                      - optional
REDIS_IP_FAMILY                          - optional (required only when using an IPv6 domain as `REDIS_HOST` or `REDIS_CLUSTER_NODES`)
APPLICATION_HTTP_PORT                    - optional (default: 8000)
APPLICATION_EXTERNAL_ENDPOINT            - optional
ENVIRONMENTS_MANAGEMENT_SECRET_KEY       - optional (default: "secret"), but it is highly recommeneded you change it
LICENSE_KEY                              - required
STORAGE_DRIVER                           - optional (default: "filesystem")
STORAGE_LOCATION                         - 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             - optional (default: "database")
COLLABORATION_STORAGE_LOCATION           - 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        - optional (default: true)
ENABLE_METRIC_LOGS                       - optional (default: false)

You can find more information about the storage configuration of the Easy Image feature in the configuration guide.

Notes:

  • 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.
  • 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.

# Configuration examples

# The database SSL connection configuration

Passing certificates as files using volumes:

version: "2.2"
services:
  ckeditor-cs:
    # ... The rest of the On-Premises Server configuration.
    environment:
      # ... The rest of the environment variables.
      DATABASE_HOST: mysql-database
      DATABASE_USER: root
      DATABASE_PASSWORD: password
      DATABASE_SSL_CA: /var/cs/ssl/server-certificate.pem
    volumes:
      - ~/certificates/ssl/server-certificate.pem:/var/cs/ssl/server-certificate.pem

Notes:

  • The path passed to the DATABASE_SSL_CA variable should be the target (second) part of the volume configuration.

Passing certificates as text:

version: "2.2"
services:
  ckeditor-cs:
    # ... The rest of the On-Premises Server configuration.
    environment:
      # ... The rest of the environment variables.
      DATABASE_HOST: mysql-database
      DATABASE_USER: root
      DATABASE_PASSWORD: password
      DATABASE_SSL_CA: "-----BEGIN CERTIFICATE-----\nMIIEBjCCAu6gAwIBAgIJAMc0ZzaSUK51MA0GCSqGSIb3DQEBCwUAMIGPMQswCQYD\nVQQGEwJVUzEQMA4GA1UEBwwHU2VhdHRsZTETMBEGA1UECAwKV2FzaGluZ3RvbjEi\n............\nzPW4CXXvhLmE02TA9/ZeCw3KkHIwicNuEfa=\n-----END CERTIFICATE-----"
      DATABASE_SSL_CERT: |
        -----BEGIN CERTIFICATE-----
        MIIEBjCCAu6gAwIBAgIJAMc0ZzaSUK51MA0GCSqGSIb3DQEBCwUAMIGPMQswCQYD
        ...rest_of_certificate_content
        zPW4CXXvhLmE02TA9/ZeCw3KkHIwicNuEfa=
        -----END CERTIFICATE-----
      DATABASE_SSL_KEY: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVCakNDQXU2Z0F3SUJBZ0lKQU1jMFoKelBXNENYWHZoTG1FMDJUQTkvWmVDdzNLa0hJd2ljTnVFZmE9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=

Notes:

  • A certificate can be passed as a one-liner, where new lines should be represented by a newline character (\n).
  • A certificate can be passed in the original certificate format using the Literal Block Scalar character (|).
  • A certificate can be passed as a base64 encoded string. It could solve problems related to newline character encoding by cloud hosting platforms.

# Connecting to Redis

If you provide an IP address as the REDIS_HOST value, the Collaboration Server On-Premises will detect whether it is IPv4 or IPv6.

However, if you are using a database that only supports IPv6 and you want to refer to that database via its domain name, then the IP version needs to be selected manually.

To do so, you need to set the REDIS_IP_FAMILY environment variable to 6. It will force Collaboration Server On-Premises to use an IPv6 connection.

version: "2.2"
services:
  ckeditor-cs:
    # ... The rest of the On-Premises Server configuration.
    environment:
      # ... The rest of the environment variables.
      REDIS_HOST: "example.ipv6.redis.server.com"
      REDIS_IP_FAMILY: 6

# Connecting to Redis Cluster

You can connect to the Redis Cluster by providing a domain or an IPv4 or an IPv6 address.

Using an IPv4 address:

version: "2.2"
services:
  ckeditor-cs:
    # ... The rest of the On-Premises Server configuration.
    environment:
      # ... The rest of the environment variables.
      REDIS_CLUSTER_NODES: "192.168.0.5:7000,192.168.0.5:7001,192.168.0.5:7002"
      # or when the Redis server requires passwords
      REDIS_CLUSTER_NODES: "192.168.0.5:7000:password1,192.168.0.5:7001:password2,192.168.0.5:7002:password3"

Using an IPv6 address:

In the case of IPv6, you need to wrap the address in square brackets [ and ] as shown in the example bellow.

version: "2.2"
services:
  ckeditor-cs:
    # ... The rest of the On-Premises Server configuration.
    environment:
      # ... The rest of the environment variables.
      REDIS_CLUSTER_NODES: "[0:0:0:0:0:0:0:1]:7000,[0:0:0:0:0:0:0:1]:7001,[0:0:0:0:0:0:0:1]:7002"
      # or when the Redis server requires passwords
      REDIS_CLUSTER_NODES: "[0:0:0:0:0:0:0:1]:7000:password1,[0:0:0:0:0:0:0:1]:7001:password2,[0:0:0:0:0:0:0:1]:7002:password3"

Using a domain:

If the domain points to a server with only an IPv6 address, you will need to set REDIS_IP_FAMILY to 6.

version: "2.2"
services:
  ckeditor-cs:
    # ... The rest of the On-Premises Server configuration.
    environment:
      # ... The rest of the environment variables.
      REDIS_CLUSTER_NODES: "example.redis.server.com:7000,example.redis.server.com:7001,example.redis.server.com:7002"
      # or in case of domain pointing to a domain with only an IPv6 address support
      REDIS_IP_FAMILY: 6
      REDIS_CLUSTER_NODES: "example.ipv6.redis.server.com:7000,example.ipv6.redis.server.com:7001,example.ipv6.redis.server.com:7002"

# Redis TLS connection configuration

Passing certificates as files using volumes:

version: "2.2"
services:
  ckeditor-cs:
    # ... The rest of the On-Premises Server configuration.
    environment:
      # ... The rest of the environment variables.
      REDIS_TLS_CA: /var/cs/tls/ca.crt
      REDIS_TLS_CERT: /var/cs/tls/redis.crt
      REDIS_TLS_KEY: /var/cs/tls/redis.key
    volumes:
      - ~/certificates/tls:/var/cs/tls/

Passing certificates as text:

version: "2.2"
services:
  ckeditor-cs:
    # ... The rest of the On-Premises Server configuration.
    environment:
      # ... The rest of the environment variables.
      REDIS_TLS_CA: "-----BEGIN CERTIFICATE-----\nMIIEBjCCAu6gAwIBAgIJAMc0ZzaSUK51MA0GCSqGSIb3DQEBCwUAMIGPMQswCQYD\nVQQGEwJVUzEQMA4GA1UEBwwHU2VhdHRsZTETMBEGA1UECAwKV2FzaGluZ3RvbjEi\n............\nzPW4CXXvhLmE02TA9/ZeCw3KkHIwicNuEfa=\n-----END CERTIFICATE-----"
      REDIS_TLS_CERT: |
        -----BEGIN CERTIFICATE-----
        MIIEBjCCAu6gAwIBAgIJAMc0ZzaSUK51MA0GCSqGSIb3DQEBCwUAMIGPMQswCQYD
        ...rest_of_certificate_content
        zPW4CXXvhLmE02TA9/ZeCw3KkHIwicNuEfa=
        -----END CERTIFICATE-----
      REDIS_TLS_KEY: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVCakNDQXU2Z0F3SUJBZ0lKQU1jMFoKelBXNENYWHZoTG1FMDJUQTkvWmVDdzNLa0hJd2ljTnVFZmE9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
    volumes:
      - ~/certificates/tls:/var/cs/tls/

Notes:

  • A certificate can be passed as a one-liner where new lines should be represented by a newline character (\n).
  • A certificate can be passed in the original certificate format using the Literal Block Scalar character (|).
  • A certificate can be passed as base64 encoded string. It could solve problems related to newline character encoding by cloud hosting platforms.

# TLS connection with AWS ElastiCache

If you are connecting Collaboration Server On-Premises with a Redis instance hosted on AWS ElastiCache and Encryption in-transit is enabled, then you need to set the REDIS_TLS_ENABLE environment variable to true. There is no need to pass TLS certificates to make an encrypted connection.

version: "2.2"
services:
  ckeditor-cs:
    # ... The rest of the On-Premises Server configuration.
    environment:
      # ... The rest of the environment variables.
      REDIS_HOST: "your.url.cache.amazonaws.com"
      REDIS_PORT: 6379
      REDIS_TLS_ENABLE: "true"

Note: If you are connecting to AWS ElastiCache Cluster with TLS enabled you also need to set this:

REDIS_DISABLE_DNS_LOOKUP: "true"

# Connecting to Redis Enterprise Cloud

Redis Enterprise Cloud expects users to use Redis database index of 0. By default, Collaboration Server On-Premises uses Redis database index 1. You may thus encounter the ERR DB index is out of range error. To fix it, change the database index using the environment variable:

REDIS_DB: 0

# Upgrading to a new version

Refer to the upgrading guide for instructions.