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.
If possible, you should first try to upgrade a non-production instance of the Collaboration Server On-Premises using a copy of the production data.
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.
- 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.
- Stop all instances of the Collaboration Server On-Premises servers.
- Run a new instance of the Collaboration Server On-Premises servers using the latest available version.
- 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.
- 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. - 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.
- 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.
- 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. - 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: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-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.