Installation 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.
- Use the instructions from the CKEditor Ecosystem customer dashboard to log into the
Collaboration Server On-Premises
Docker Registry and pull the Docker image. - Containerize the application using
docker
ordocker-compose
. - Create the
Environment
with anAccess Key
via the Cloud Services Management Panel. Use this data to create the token endpoint and run tests. - Run tests to verify if the system works properly — see the Running tests using Docker guide.
- 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 theDATABASE_HOST
andREDIS_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 theAPPLICATION_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]
- If an SQL database and Redis are hosted on
- 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
- 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
- Create the
init.sql
file:CREATE DATABASE `cs-on-premises` DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_unicode_ci;
- Run:
docker-compose up
# Example with PostgreSQL
- 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
- Create the
init.sql
file:CREATE DATABASE "cksource"; \connect "cksource"; CREATE SCHEMA "cke-cs";
- 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
andDATABASE_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.