v3 to v4 Migration

EasyEngine v4 is complete rewrite in terms of many aspects. The key one being:

1. Programming Language: v3 had Python, v4 has PHP
2. Architecture: v3 was using native OS packages, v4 uses Docker images  
3. Focus: v3 was focused on system admin tasks, v4 is focused on developer workflow

That being said we tried our best to preserve semantics where possible so v3 users won’t have a steep learning curve when moving to EasyEngine v4.

This document outlines changes and answers some questions in details. Reading this will make moving to v4 easy.

v3 – End of Life

We do not support v3 in any way except fixing critical security vulnerabilities. The security fixes will be provided until January 31, 2019.

There won’t be new features or enhancements. The core team won’t be answering any v3 related support topics on forum or Github issue tracker. To keep forum/issue tracker clean, if a v3 related discussion gets no reply for 30 days, we will close it.

As v3’s end of life is near, you can consider migrating to v4 or any other alternatives you may like. We do not recommend using unsupported software, even if it was made by us.

Now let’s deep dive into v3 to v4 changes and get you ready to migrate.

Feature Changes

This section covers some of major feature changes in details. Not every change is breaking. We believe, you may like some changes in the following list, but nonetheless, we should tell you about them here to avoid surprises! 

Note: The emoji under each subsection represent an anticipated emotional response! 😉

Removal of Mail Hosting 😞

v3 had email hosting support with web interface powered by ViMbAdmin and RoundCube. If you never used that feature, you don’t need to worry about it.

Running a mail server is hard. We ourselves have been using Google Suite (Google Apps) for email hosting since the inception of rtCamp (from 2008).

The feature in v3 was added an as experiment. While it worked, we did not used it in production so it became very hard to manage & support it.

There are many tools to migrate emails between IMAP servers. We use larch all the time. It still works. even if it officially unmaintained by author.

Limit on number of EE sites 😞

As v4 depends on docker, it is affected by Docker’s limitation of 31 network per machine.

v4 creates one network per site. Then v4 also needs few Docker networks for global services. So roughly we limit the number of sites to 27.

Please note, a WordPress multisite is counted as a single site. We highly recommend you use WordPress multisite more often. Aside site limit, multisite reduces overall burden and in a way enforce usage of quality codes.

While we already have a patch to overcome this 31 network limit, we will wait for a few months before we make a decision on this.

If you already have a v3 server with more than 27 sites, you may migrate them in chuks to multiple v4 servers. 

WordPress Cache Types 😐

v3 has four different cache types but we only used redis backed full page cache. It was also our recommended caching method.

Maintaining four ways to achieve the same thing is hard. So we removed all other cache types to make project lean and clean. Also, now we have only one cache type to focus on, we will be able to improve it in a much better way going ahead.

To be specific, we have dropped support for nginx fastcgi cache, wp super cache, and w3 total cache. But since Redis cache has all the features and supports many more use cases such as wildcard purging in linear time using Lua script, we hope you won’t get affected by this change.

If you use v3 to v4 migration script, it will automatically handle cache type change appropriately. So again nothing to worry here unless you depend on anything that wasn’t part of default v3 cache config. 

Complete Rewrite in PHP 🤷

v3 was written in Python. Python is a decent programming language but rtCamp – the company behind EasyEngine is primarily a WordPress agency. Also, most EasyEngine users are from WordPress ecosystem. It was getting difficult for us to hire decent Python developers and even harder was to get them motivated to fix problem of an ecosystem they are not part of!

So v4 is completely rewritten in PHP. Since PHP used by EasyEngine itself and PHP used by sites created via EasyEngine are not related, the EasyEngine itself is coded in PHP 7.2 to make most of the latest PHP version.

Uses WP-CLI as a Framework 🙂

You may have used WP-CLI in past. You are in for a good news. v4 uses WP-CLI as a base framework. 

If you are familiar with WP-CLI package development, you will be able to extend EasyEngine using similar packages.

PHP 7 is new default 🎉

In v4, all PHP and WordPress sites will be created using the latest PHP version by default. At the time of v4.0.0 release, PHP is (was) set to PHP 7.2 by default. You can also create site in PHP 5.6 if you want.

Admin Tools Port 22222 🎉

Earlier admin-tools were accessible from a dedicated port 22222. Now they will be accessible from example.com/ee-admin/. You can have a look at this issue to know more about why this change was made.

This will simplify networking and firewall as you don’t have to open ports in firewall. No more issues when putting site behind Cloudflare.

We believe you will love & welcome this change! ♥️

Command Changes

This section list EasyEngine command changes from v3 to v4. As many commands, have many flags, and then flags together can be used in almost endless permutations, for sake of readbility, we are covering commands & flags which are frequently used.

Site Create Command

Site creation – the biggest EasyEngine feature, has undergone some significant changes. Overall, there is no real loss in functionality but few things are removed and renamed.  As this is biggest command, it is documented here in detail here.

Removed Flags

v4 doesn’t support following site create flags. Following command will throw an error:

ee site create example.com --wpfc
ee site create example.com --wp3tc
ee site create example.com --wpsc
ee site create example.com --pagespeed
ee site create example.com --hhvm

Remapped Flags

For following v3 flags, v4 will internally convert them to their v4 equivalent:

Renamed Flags

In addition to above, for WordPress site creation, some v3 flags has been renamed. These are handled internally without any issue:

Other Commands

Following commands are permanently removed/replaced from EasyEngine.

Stack Command Removed

In v4, we do not install anything on the host. Hence the entire stack command from v3 is irrelevant. Following will simply throw an error:

stack install
stack migrate
stack purge
stack remove
stack upgrade

v4 has a new concept of services but it should not be seen as replacement for stack. 

Secure Command Replaced

Since admin-tools in v4 are not running on a special port such as 22222, ee secure <port> command is no longer needed, hence removed.

Other ee secure sub-commands are replaced by new auth command. ee auth is a lot more powerful and configurable,

Info Command Replaced

ee info command is replaced with:

1. ee cli info – displays easyengine own info and host machine info. 
2. ee site info – displays site-specific info

Update Command Replaced

v3’s ee update command to update EasyEngine itself is replaced by ee cli update.

Temporarily Removed Commands

Following commands have been temporarily removed but these will be added back soon:

ee site log
ee site show
ee site edit
ee debug
ee clean
ee log

New v4 Commands

v4 introduces many new commands as below:

• mailhog  – to capture outgoing emails for SMTP testing & debugging
• admin-tools – to selectively enable/disable admin tools per site
• cron – manage cronjobs per site and/or globally
• service – to manage shared services such as global mysql & global redis
• cli – stuff that is related to easyengine itself

You can check all v4 commands reference documentation here.

Automation Impact

If you are a hosting company provisioning EasyEngine v3 based server via some automation script, nothing will break.

If you use our famous one-line install – wget -qO ee rt.cx/ee && sudo bash ee in any script, it will fetch v3 only. v4 has a new short URL. 

Similarly, if you run ee update command on a v3 server periodically or via some script, it will only fetch EasyEngine v3 update, if a minor update is available. 

v3 doesn’t update to v4 automatically. We have a migration script for that, which you need to run manually.

Migration Script

First, thanks for reading this far! If you are excited about v4 but think moving more than a dozen sites you have created on v3 will take time, 

We understand you may have a lot many sites on v3. So we have created a migration script to move sites from v3 to v4. The script support migration on the same server as well a migration to new server.

Please read this for v3 to v4 Migration Script

Subpages

• v3 to v4 Migration Script