Start free trial
en
Language
  • en
  • cs
  • hu
  • it
  • es
  • fr
  • de
  • ru
Easy Project
Documentation
09. Administration
Upgrading to version 11

Upgrading to version 11

Pre-intro

There are significant technological changes between version 10 and the following versions. While this article is written for v11, its steps are valid also for upgrades between v10 -> v13, or v14. In case of upgrading to these higher versions, make sure to prepare the necessary requirements for your version.

Introduction

This guide is intended for Server administrators. Cloud users may relax, put their feet up, and leave all these operations to us.

Version 11 is a significant technological leap compared to previous versions. Upgrading to this version requires a bit more preparation than a regular upgrade to avoid any upsets. Consider this guide a checklist for a smooth transition.

The most important changes in the technological stack are explained in the Release notes. It also contains important functional changes and plugin information. If you haven't already, please read them first.

Easy Virtual Machines to the rescue!

Some of the following points may apply to you and the combined effort to may seem more than you are willing to endure. In such case, there is always the easy option of getting a fully installed application on VMware/VirtualBox image (.ova format). Just ask our support, who will generate a VM for you and possibly even arrange data migration from your existing system. As a reward for such decision, you don't need to read the rest of this article :)

Useful resources

Instructions for most of the steps are already published in the knowledge base and directly in installation package (doc/INSTALL_DEBIAN). We will not be copying all of them into this one article. We will rather add the necessary context here and focus on the significant changes.

Model upgrade story

Before we disect each component in detail, we will show a model example of an upgrade, while remaining on the same server.

Existing server

  • Easy VM with Easy Project version 10.10.1
  • ruby -v = 2.5.3
  • mysql --version = 5.7.31
  • redis-server --version = 5.0.3
  • gem list | grep bundler = 1.16.6
  • node -v (non-existent)
  • puma application server
  • nginx web server

Since it is VM provided by Easy, big environment (OS, database) allows upgrade on the same server. Some components are fine as they are (mysql, redis-server, puma, nginx), some require upgrade (ruby, bundler), one requirement is completely missing (Node.js).

Steps

0) Download and install the latest LTS version (10.14.x) - upgrade is possible only from LTS.

1) Let's start with ruby upgrade
rvm install ruby 2.6.7 --patch railsexpress

(wait till new ruby is installed, it may ask you for sudo password)

rvm use ruby-2.6.7 --default

2) We recommend uninstalling previous ruby version to avoid possible collisions
rvm remove ruby-2.5.3

This command will uninstall ruby with all gems and other files. It is better than using rvm uninstall command.

3) Now we need to reinstall all needed gems for application. We start with bundler
gem install bundler

Let's check which bundler was installed
gem list | grep bundler

It should return a line like
bundler (2.1.4, 2.1.2)

Make sure there is version higher than 2.2.16

4) Now please go to /home/easy/your.vm.name
cd /home/easy/your.vm.name

5) Install nodejs
sudo apt update
sudo apt upgrade
curl -sL https://deb.nodesource.com/setup_14.x | sudo bash -
sudo apt install nodejs

And check it has correct version
node -v

It should return something like
v14.16.0

Make sure your version is 14.16 or higher.

6) Download package v11 package from client zone, copy it to your VM.

7) Stop puma server
sudo systemctl stop puma@your.domain.name

From this point you may choose would you like to continue with automatic procedure or with manual upgrade.

a) Automatic upgrade (recommended)
8a) Run upgrade via redmine installer
redmine upgrade name_of_package

9a) Follow the steps in the wizard.

b) Manual upgrade
8b) Rename your recent current/ folder
mv current/ current_old/

9b) Recreate current folder
mkdir current

10b) Go to current folder
cd current/

11b) Unpack package here
unzip /path/to/downloaded/package.zip

12b) Install gems
bundle install

13b) Run migrations
bundle exec rake easyproject:install RAILS_ENV=production

14b) If everything is ok, start puma back
sudo systemctl start puma@your.domain.name

Specifications checklist

Operating system

From version 11, the only supported operating system (where the application runs directly) is Debian, particularly 10 (Buster) and 11 (Bullseye).

If you are running Easy Project on our provided VMs, you most likely already have this requirement covered. If you have a non-supported OS, you need to migrate to a new server (preferably our VM). Reinstalling or upgrading OS beneath a production application is definitely not in your best interest.

Database server

You will need to use Percona/MySQL 5.7+. There are roughly three cases:

  • You have an older Percona version -> upgrade via official instructions, such as
    https://www.percona.com/doc/percona-server/5.7/upgrading_guide_56_57.html
  • You have a different MySQL distribution (such as MariaDB) -> we recommend migrating to new server (preferably our VM).
  • You have PostgreSQL -> we recommend migrating to new server (preferably our VM). Before the migration itself, database needs to be converted. We tested various conversion tools and provided instructions for the most suitable ones. We are also ready to perform the conversion for you.

Ruby

The language behind the application needs to be kept up-to-date such as the language that people communicate by. Upgrading Ruby is described here. Unless your existing Ruby is very old, you can continue on the same server.

Bundler

A ruby gem to manage ruby gems. Since Easy Project uses more than 200 of those, bundler is a crucial component.

To install
gem install bundler

To verify version
gem list | grep bundler

Version 2.2.x should install automatically. In case it doesn't, please follow the official documentation.

Redis

To streamline some of the new features and performance improvements in v11, we use Sidekiq with redis-server. Easy VMs already contain these components. Be careful about the version, ER11 requires redis-server 5+.

Here is an excerpt from the main installtion guide located in your v11 package under doc/INSTALL_DEBIAN

  1. Setup redis and sidekiq

Switch to user easy.

vim /home/easy/current/config/additional_environment.rb

if Rails.env.production? config.active_job.queue_adapter = :sidekiq

redis_namespace = Rails.root.join("..").basename.to_s redis_url = "redis://#{ENV["REDIS_HOST"] || "127.0.0.1"}:#{ENV["REDIS_PORT"] || 6379}/1" Sidekiq.configure_server do |config| config.redis = { url: redis_url, namespace: redis_namespace }

end

Sidekiq.configure_client do |config| config.redis = { url: redis_url, namespace: redis_namespace }

end end

vim /home/easy/current/config/sidekiq.rb

:verbose: false :pidfile: ../sidekiq.pid :logfile: ./log/sidekiq.log :concurrency: <%= ENV["SIDEKIQ_WORKERS"] || 2 %> :queues:

  • critical
  • default
  • recalculate_custom_fields
  • easy_git
  • easy_actions
  • easy_mail_campaigns
  • easy_integrations
  • mailers
  • easy_rake_tasks
  • low

Node.js

Finally, the last major requirement. Installation is rather simple

sudo apt update
sudo apt upgrade
curl -sL https://deb.nodesource.com/setup_14.x | sudo bash -
sudo apt install nodejs

Make sure that you have version 14.16. Documentation available here.

WebSockets

While not a strict requirement that blocks the application from running, two features use this technology (showing live online/offline state in avatar of user; in-app notice about finished export). It will be expanded in the future.

Action Cable needs to be enabled. It is dependent on Redis. If you want to use these features, but are not familiar with Redis/ActionCable configuration, we recommend migrating to new VM where these are preconfigured.

Enforced HTTPS protocol

Version 11 enforces HTTPS protocol of the application URL. Please check webserver (nginx) configuration to make sure that your application will be accessible via https://[easyproject_url] from your web browser or from any integrations that connect to your Easy Project. The URLs http://[easyproject_url] will not work in v11!

End of sub-uri

As the front-end receives advanced enhancements, it is no longer feasible to keep supporting sub-uri configuration. This kind of configuration is sensitive to Javascript components and often causes disfunction. Please reconfigure your server to regular domain.

After upgrade

Textile/Markdown texts migration

As written in release notes we dropped support of different text editors. If you previously used textile or markdown text editing, you will need to run the migration of formatted texts to HTML.

Use this command to convert mapped database entries from unsupported formatting to the HTML (version 13.8.2 and higher):

bundle exec rails easy:convert_wiki_formatting source_formatting=markdown

source_formatting= env variable can be textile, markdown or common_mark. textile is default.

The utility will check database and will inform you if it identifies some HTML content already.

Converted entities

  • "Comment" => [:content]
  • "Document" => [:description]
  • "Issue" => [:description]
  • "Journal" => [:notes]
  • "Message" => [:content]
  • "News" => [:description]
  • "Project" => [:description]
  • "WikiContent" => %i[comments text]
  • "WikiContentVersion" => [:text]
  • "EasyAttendance" => [:description]
  • "EasyContact" => [:description]
  • "EasyCrmCase" => [:description]

Try Easy Project in 30 days free trial

Access all features, SSL protected, no credit card required.