Skip to content

Upgrade Easy8

These steps apply to upgrades to the current Easy8 version. Version-specific changes are in Major releases.

Common upgrade process

  1. Identify the source and target Easy8 versions (the source may be Easy Project or Easy Redmine).
  2. Read the release notes between the source and target versions.
  3. Verify the database and file storage backups before any data conversion. The current Easy8 supports Percona Server 8.4 only.
  4. Run format and data migrations in the source version whenever possible.
  5. Verify the converted data in the source version before upgrading the application code.
  6. Upgrade one supported LTS step at a time when the source version is old.
  7. Run the normal Easy8 setup after the application upgrade.
  8. Verify critical user data after the upgrade.

Editor formatting

The current Easy8 supports only HTML formatting through CKEditor. Older versions (including Easy Project and Easy Redmine) could store formatted text as Textile, Markdown or CommonMark. Convert non-HTML content to HTML before you upgrade to the current Easy8.

Do not upgrade first and convert later unless there is no other option.

Source versions before LTSv10

Do not upgrade directly from a version before LTSv10 to the current Easy8.

Upgrade to LTSv10 first and run the formatting conversion there. After you verify the conversion, continue with the next supported upgrade step.

Source versions LTSv10 to LTSv12

Run easyproject:textile:migrate_all in the source version to convert to HTML. The task does not exist in the current Easy8.

First check the current formatting, either in Administration > General settings > Text formatting or with:

bundle exec rails r "puts Setting.text_formatting"

If the formatting is already HTML, do not run the conversion again.

If the formatting is textile, run:

bundle exec rake easyproject:textile:migrate_all source_formatting=textile RAILS_ENV=production --trace

If the formatting is markdown, run:

bundle exec rake easyproject:textile:migrate_all source_formatting=markdown RAILS_ENV=production --trace

If you use CRM, contact support before the upgrade: since v12 CRM has a different data structure and the data must be migrated.

If you use Knowledge Base, contact support before the upgrade as well: since v12 it must be migrated to a new application (BS).

Source versions LTSv13 and newer

LTSv13 and the current Easy8 use easy:convert_wiki_formatting.

Supported source formats are:

  • textile
  • markdown
  • common_mark

Run it only when the current formatting is not HTML:

bundle exec rails easy:convert_wiki_formatting source_formatting=textile RAILS_ENV=production

Set source_formatting to match your data:

bundle exec rails easy:convert_wiki_formatting source_formatting=markdown RAILS_ENV=production
bundle exec rails easy:convert_wiki_formatting source_formatting=common_mark RAILS_ENV=production

The task writes progress to log/convert_text_format.log.

The conversion is irreversible. It asks for confirmation and warns when it finds HTML in existing journal notes. Treat the warning as a possible mixed-format database and stop unless support confirms that it is safe to continue.

Upgrade verification checklist

After the formatting conversion and before you continue with the version upgrade, check that:

  • Setting.text_formatting is HTML.
  • Random issue descriptions render correctly.
  • Random journal notes render correctly.
  • Wiki pages and old wiki versions render correctly.
  • Project descriptions render correctly.
  • CRM case descriptions render correctly when CRM is installed.
  • Knowledge Base articles render correctly when KB is installed.
  • No conversion warning remains unresolved.
  • Backup is still available until post-upgrade verification is complete.