Skip to content

Upgrade Guide

This guide describes common upgrade preparation steps that are valid for upgrades to the current Easy8 version. Version-specific release notes remain in Major releases.

Common Upgrade Process

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

Editor Formatting

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

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

Source Versions Before LTSv10

Do not upgrade directly from pre-LTSv10 versions to current Easy8 !

Upgrade to LTSv10 first, then run formatting conversion in LTSv10. After conversion is verified, continue with next supported upgrade step.

Source Versions LTSv10 - LTSv12

Use command easyproject:textile:migrate_all for conversion to HTML.

First check current formatting:

In administration > general settings > text formatting, verify current formatting

OR

bundle exec rails r "puts Setting.text_formatting"

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

If formatting is textile, run:

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

If formatting is markdown, run:

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

If CRM is installed and used, contact support before upgrade. Since v12 CRM changed data structure completely and migrated data is required.

If Knowledge Base is installed and used, follow the same process: contact support before upgrade. Since v12 Knowledge Base must be migrated to new application (BS).

Source Versions LTSv13 and Newer

LTSv13 and current Easy8 use easy:convert_wiki_formatting.

Supported source formats are:

  • textile
  • markdown
  • common_mark

Run only when current formatting is not HTML:

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

Use matching source_formatting for the source data. For example:

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.

This conversion is irreversible. It asks for confirmation and warns when existing HTML-like journal content is detected. Treat this warning as a possible mixed-format database and stop unless support confirms it is safe to continue.

Upgrade Verification Checklist

After formatting conversion and before continuing with version upgrade:

  • 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.