Home/CKBox/Getting started

CKBox Migration Tool

This guide will show you how to transfer assets from your old system like CKFinder or Easy Image to CKBox. You will also find information on how to replace the old URLs in your system with CKBox links after the migration.

# Using the Migration Tool

The Migration Tool is a CLI application designed to migrate your assets between systems. It has built-in support for Easy Image and CKFinder, and you can also create a custom adapter to migrate files from any source.

# Installation

Before installing the Migration Tool, ensure that you have NodeJS version 18.x or later installed. For instructions on installing NodeJS, visit [https://nodejs.org/en/download/package-manager this page].

You can then download and build the Migration Tool from source:

git clone git@github.com:ckbox-io/migration-tool.git
cd migration-tool
npm install
npm run build

# Preparing the migration

In order to migrate your assets, you will need to configure a connection to your source storage and to the CKBox. First, prepare the configuration of the CKBox connection.

# Configuration of CKBox connection

Create a config.json file in the directory where you downloaded the migrator tool. You can copy and use config.template.json as a template for your own configuration.

You will need to provide the access credentials (namely the environment ID and access key). You can read more about CKBox credentials in the Authentication guide. You should also provide the serviceOrigin URL. If you are a SaaS client, it should point to https://api.ckbox.io. For the on-premises version, you need to set this value to the URL pointing to the REST API of your CKBox On-Premises application.

{
    "ckbox": {
        "accessCredentials": {
            "environmentId": "<ENVIRONMENT_ID>",
            "accessKey": "<ACCESS_KEY>"
        },
        "workspaceId": "<WORKSPACE_ID>",
        "serviceOrigin": "<SERVICE_ORIGIN>"
    }
}

Optionally, you can also specify a workspaceId. If you do not, all files will be uploaded to a default workspace. Read more about workspaces in the Workspaces guide.

List of configuration options for CKBox connection

Option name	Description
ckbox.assetsCredentials.environmentId	Target environment for the migration.
ckbox.assetsCredentials.accessKey	Access Key used to sign authorization token.
ckbox.workspaceId	Target workspace for the migration (optional).
ckbox.serviceOrigin	Sets the origin to use for the CKBox REST API.

# Preparing the source storage

The source storage configuration depends on the type of system you are migrating from. If you are migrating from CKFinder or Easy Image, you can use the built-in support and use the examples below. For other systems, you will need to implement your own SourceStorageAdapter. More information about migrating from custom storage can be found in this article.

# CKFinder

To migrate assets from CKFinder, you must set a type for ckfinder, set the URL to the connector, and add the headers used for authentication.

{
    "source": {
        "type": "ckfinder",
        "options": {
            "connectorPath": "http://localhost:8080/ckfinder/connector",
            "authentication": {
                "headers": {
                    "Cookie": "PHPSESSID=e0baf7e705e40f7e7dea7fa3d04a5a79"
                }
            }
        }
    },
    "ckbox": {
        ...
    }
}

List of configuration options for CKFinder connection

Option name	Description
source.type	Must be set to `ckfinder`.
source.options.connectorPath	Sets the origin to use for the CKFinder REST API.
source.options.authentication.headers	Sets headers needed for authentication.

# Easy Image

To migrate assets from Easy Image, you must set the type to easy-image, set the REST API origin URL, and add access credentials.

You can find more about Easy Image credentials in the CKEditor Cloud Services authorization guide.

{
    "source": {
        "type": "easy-image",
        "options": {
            "accessCredentials": {
                "environmentId": "<ENVIRONMENT_ID>",
                "accessKey": "<ACCESS_KEY>"
            },
            "serviceOrigin": "<SERVICE_ORIGIN>"
        }
    },
    "ckbox": {
        ...
    }
}

List of configuration options for Easy Image connection

Option name	Description
source.type	Must be set to `easy-image`.
source.options.assetsCredentials.environmentId	Source environment for the migration.
source.options.assetsCredentials.accessKey	Access Key used to sign authorization token.
source.options.serviceOrigin	Sets the origin to use for the Easy Image REST API.

# Checking the configuration

Before migration it is advisable to verify the configuration first by running the migrator in the dry run mode. This command will verify connections and scan the source storage to see if it has access to resources.

npm start -- --dry-run

# Running the migration

To start the migration you need to execute the command below:

npm start

This command will create categories, folders and upload assets to your CKBox instance.

# Replacing the old URLs with the new ones in your application

Once the migration process is complete, the migrator generates a file that maps the old URLs to the new URLs. The file name will have the format ckbox_mapped_URLs_[migration time].txt. You can use this file to replace the old URLs with the new ones in your application.

The file contains pairs of URLs, with each pair on a new line. The URL of the source file and the migrated file are separated by a tab character.

# Troubleshooting

In the event of any issues, the migrator will generate logs in the ckbox_migrator_[migration time].log file. It includes comprehensive details about the issues that occurred.

You should also be aware that the migrator will try to migrate remaining resources even if one of them fails. You’ll get a message about this in the console so you can check the logs for more information. If you find that some resources failed to migrate, but others did not, you must first check and fix the problem (for example adjust permissions for the source system or CKBox). Then, you can:

You could try uploading the failed assets manually.
Alternatively, you could revert the migration by removing the resources from CKBox and trying the migration again.