Upgrading the Docker installation

We release a new Collaboration Server On-Premises version every 6 weeks. It comes with new features, bug fixes, and security updates. Some new CKEditor 5 features may not be compatible with older versions of Collaboration Server On-Premises, too. For these reasons, it is highly recommended to keep your Collaboration Server On-Premises server up-to-date.

Using Docker containers greatly simplifies the process of upgrading the Collaboration Server On-Premises version. The upgrade process may differ depending on the deployment tools and platforms used. Refer to the steps below for the correct order of actions.

All important changes are added to the Collaboration Server On-Premises changelog. You can find it in the CKEditor Ecosystem customer dashboard.

# Upgrading to a new version – fast

The approach described here requires upgrading Collaboration Server to version 4.14.0 or newer. If you plan to upgrade to an older version, please follow the zero downtime approach.

This approach is recommended if you can accept a temporary downtime of Collaboration Server On-Premises. The advantage of this approach is faster upgrading time as you can upgrade from a very old version way faster than in the zero downtime approach. The disadvantage of this approach is that we recommend disabling Collaboration Server On-Premises for the time of the upgrade. Operating on Collaboration Server On-Premises during the upgrade in this approach causes a risk of data inconsistency or application errors.

1. Backup your database – this will ensure that in the case of any issues after the upgrade you can restore the database and roll back to the previously used Collaboration Server On-Premises version.
2. Stop all instances of the Collaboration Server On-Premises servers.
3. Run a new instance of the Collaboration Server On-Premises servers using the latest available version.
4. Verify whether the Collaboration Server On-Premises servers are up and running.

# Upgrading to a new version – zero downtime

Use this approach in situations where any downtime of the Collaboration Server On-Premises services is not acceptable. The drawback of this approach is the longer update time. The described approach is also recommended if you plan to migrate to Collaboration Server version 4.13.0 or older. The method is based on the blue/green deployment approach that can be easily introduced to solutions based on Kubernetes or dedicated services such as AWS ECS.

1. Configure your infrastructure to proxy all traffic only to healthy Collaboration Server On-Premises instances. The configuration can rely on the results from the /health endpoint.
2. Backup your database – this will ensure that in the case of any issues after the upgrade you can restore the database and roll back to the previously used Collaboration Server On-Premises version. Backing up your DB after each upgrade will allow you to roll back only one minor version, in case when some upgrade went wrong.
3. Next to the currently working application, start the Collaboration Server On-Premises servers using a higher minor version – you should NOT skip any minor versions when upgrading. For example, if you are currently running Collaboration Server On-Premises version 3.12 and you would like to upgrade it to the latest version, you should start with an upgrade to v3.13. The traffic should not be proxied to the new instance until it will be healthy.
4. Once the new Collaboration Server On-Premises container is up and running (the /health endpoint returns a correct status), disable traffic and stop the Collaboration Server On-Premises container in the old version.
5. Repeat steps 2, 3, and 4 until you have the desired version of the Collaboration Server On-Premises running.

# Migrate only mode

The MIGRATE_ONLY environmental variable allows you to detach upgrading Collaboration Server On-Premises from upgrading the database structure. Once the variable value is set to true, the container will stop once the database migration finishes. It will allow you to improve your observability by disabling the healthcheck for the container in the MIGRATE_ONLY mode and re-enable it only for an actual application container that uses an already migrated database. As migrating from a very old version may take some time, especially if your database is large, it may happen that the application will not be available in the desired timeout which may cause a healthcheck failure. Detaching migration from an application start prevents the described situation. The MIGRATE_ONLY environmental variable is available for Collaboration Server On-Premises version 4.15.0 or newer.

# Example container configuration for detached migration process - Docker Compose

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
      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: 5s
        timeout: 20s
        retries: 5
    redis:
      image: redis:6.2.7
    ckeditor-cs-migrator:
      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.
      restart: "no" # Migrator should NOT restart when migration is done.
      init: "true"
      environment:
        MIGRATE_ONLY: "true"
        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
        LOG_LEVEL: 30
      volumes:
        - ~/easyimage_files:/var/cs/easyimage
    ckeditor-cs:
      image: docker.cke-cs.com/cs:[version]
      depends_on:
        redis:
          condition: service_started
        mysql-database:
          condition: service_healthy
        ckeditor-cs-migrator:
          condition: service_completed_successfully
      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

# Example container configuration for detached migration process – AWS ECS

For AWS ECS you can use the dependsOn setting to ensure the correct container start order:

ckeditor_cs_container_definition = {
    name              = "ckeditor_cs"
    image             = local.docker_image
    essential         = true
    environment       = local.environment_variables
    dependsOn = [
      {
        containerName = "${local.service_name}-migrator",
        condition     = "SUCCESS"
      }
    ]
    // The rest of container definition
  }
  ckeditor_cs_migrator_container_definition = {
    name         = "${local.ckeditor_cs_container_definition.name}-migrator"
    image        = local.ckeditor_cs_container_definition.image
    essential    = false
    healthCheck  = null
    environment  = concat(
      local.ckeditor_cs_container_definition.environment,
      [
        {
          name  = "MIGRATE_ONLY",
          value = "true"
        }
      ]
    )
    // The rest of container definition
  }

Make sure ckeditor_cs_migrator_container_definition has the healthCheck parameter set to null. A container in the MIGRATE_ONLY mode does not expose any HTTP endpoint and for larger databases, the run time may be long.