Docker-compose

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 the CKEditor 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-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:8.0.34
        platform: linux/amd64
        environment:
          MYSQL_ROOT_PASSWORD: password
        volumes:
          - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
        healthcheck: # Define healthcheck to be able to use the `service_healthy` condition.
          test: ["CMD-SHELL", "exit | mysql -h localhost -P 3306 -u root -p$$MYSQL_ROOT_PASSWORD" ]
          interval: 10s
          timeout: 30s
          retries: 5
    
      redis:
        image: redis:6.2.7
    
      ckeditor-cs:
        image: docker.cke-cs.com/cs:[version]
        depends_on:
         redis:
           condition: service_started
         mysql-database:
           condition: service_healthy # Make sure your database is ready for migration.
        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_bin;
    
  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
        healthcheck: # Define healthcheck to be able to use the `service_healthy` condition.
          test: pg_isready -U postgres
          interval: 10s
          timeout: 30s
          retries: 5
    
      redis:
        image: redis:6.2.7
    
      ckeditor-cs-postgres:
        image: docker.cke-cs.com/cs:[version]
        depends_on:
         redis:
           condition: service_started
         postgres-database:
           condition: service_healthy # Make sure your database is ready for migration.
        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
    

# Example with Collaboration Worker

The steps are similar to in the case of regular CKEditor Collaboration Server On-Premises installation.

We use docker-compose as an example configuration to explain how the services should be configured. In a production environment, we recommend using clusters managed by a container-orchestration system like Docker Swarm, Kubernetes, ECS, GKE, AKS, or OpenShift.

  1. If you have the docker-compose.yml file already, you can only add the worker-cs service and set the USE_BUILT_IN_COLLABORATION_WORKER environment variable to false in ckeditor-cs. Otherwise, create the file with the following content:
version: "3.7"
services:
  mysql-database:
    image: mysql:8.0.34
    platform: linux/amd64
    environment:
      MYSQL_ROOT_PASSWORD: password
    volumes:
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    healthcheck: # Define healthcheck to be able to use the `service_healthy` condition.
      test: ["CMD-SHELL", "exit | mysql -h localhost -P 3306 -u root -p$$MYSQL_ROOT_PASSWORD" ]
      interval: 10s
      timeout: 30s
      retries: 5

  redis:
    image: redis:6.2.7

  ckeditor-cs:
    image: docker.cke-cs.com/cs:[version]
    depends_on:
      redis:
        condition: service_started
      mysql-database:
        condition: service_healthy # Make sure your database is ready for migration.
    ports:
      - "8000:8000"
    restart: always
    init: true
    environment:
      DATABASE_DRIVER: mysql
      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
      USE_BUILT_IN_COLLABORATION_WORKER: "false"
    volumes:
      - ~/easyimage_files:/var/cs/easyimage

  worker-cs:
    image: docker.cke-cs.com/cs-worker:[version]
    depends_on:
      redis:
        condition: service_started
      mysql-database:
        condition: service_healthy # Make sure your database is ready for migration.
    restart: always
    init: true
    environment:
      DATABASE_DRIVER: mysql
      DATABASE_HOST: mysql-database
      DATABASE_USER: root
      DATABASE_PASSWORD: password
      REDIS_HOST: redis

The version of cs and cs-worker images should be the same.
You should also connect the services to the same Redis and SQL databases.

  1. Create the init.sql file:

      CREATE DATABASE `cs-on-premises`
      DEFAULT CHARACTER SET utf8mb4
      DEFAULT COLLATE utf8mb4_bin;
    
  2. Run:

    docker-compose up
    

# Notes

  • If you use a 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 environmental 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.

# 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 a 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 configuration 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.