guideInstallation with Docker

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 using the Docker container

Follow the steps below to install CKEditor Cloud Services On-Premises using the Docker container.

  1. Use instructions from the CKEditor Ecosystem customer dashboard to log into the CKEditor Cloud Services On-Premises Docker Registry and pull the Docker image.
  2. Containerize the application using docker or docker-compose.
  3. Create the Environment with a Access Key via 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 Running tests using Docker.
  5. Configure the server endpoints in the CKEditor Collaboration web application to communicate with the CKEditor Cloud Services On-Premises application — see Setting endpoints.

# 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 to storage image, 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. More information about the storage of the Easy Image feature you can find here.
  • Use environment variables to configure the application. See Docker container environment variables. 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.
  • Without a correct LICENSE_KEY the application will not start.

# Containerize example using docker-compose

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

# Example with MySQL

  1. Create the docker-compose.yml file:
    version: "2.2"
    services:
      mysql-database:
        image: mysql:5.6.38
        environment:
          MYSQL_ROOT_PASSWORD: password
        volumes:
          - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    
      redis:
        image: redis:3.2.6
    
      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.0
        environment:
          - POSTGRES_PASSWORD=password
        volumes:
          - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    
      redis:
        image: redis:3.2.6
    
      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 to storage image, you should always mount the Docker volume to preserve uploaded files in case your Docker container gets removed. More information about the storage of the Easy Image feature you can find here.
  • Use environment variables to configure the application. See Docker container environment variables.
  • You should override the ENVIRONMENTS_MANAGEMENT_SECRET_KEY variable using a unique and hard to guess string due to security reasons.
  • Without a correct LICENSE_KEY the application will not start.
  • If you use intensively collaboration features (like document storage, import and export, or connect compressor) we recommend to use Collaboration Worker to improve reliability.

# 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 don’t 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"

The values are examples and should be changed.

The database should be created before running the application. It can be created by 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"

The values are examples and should be changed.

The database and schema should be created before running the application. It can be created by 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_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_CLUSTER_NODES                      - optional
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)

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

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.

# Examples

# Redis Cluster configuration

REDIS_CLUSTER_NODES=192.168.0.5:7000,192.168.0.5:7001,192.168.0.5:7002
REDIS_CLUSTER_NODES=192.168.0.5:7000:password1,192.168.0.5:7001:password2,192.168.0.5:7002:password3

# 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 with 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 new lines characters encoding by Cloud Hosting platforms.