Upgrading from ActiveCollab 4
Upgrading the self-hosted version isn’t direct or automatic, but it's not too complicated. You'll have to set up the new ActiveCollab separately from your existing installation - and then import the data. Just make sure they're both on the same server.
The good part is you can have both versions running side by side. That means you'll still be able to use your old ActiveCollab while you're installing and testing the new version.
If you have ActiveCollab v3 or earlier, you first need to upgrade to v4 and then to v5.
Keep a few things in mind:
- You can only move your data to the new version (and not vice versa).
- Partial migration is not possible (eg. having only some projects moved to the new version).
There are two approaches to upgrade:
- Installing fresh copy of ActiveCollab 5.13 on the same server where ActiveCollab 4 runs. Once you install the new version, you can clone the data from the old one,
- Installing the latest version of ActiveCollab on a new server. Next step is to move only the data from ActiveCollab 4 and import it.
Option #1 was preferer while v4 and the latest version of ActiveCollab could run on the same server. This changed with ActiveCollab 5.14. This release has system requirements that ActiveCollab 4 is not compatible with. Because of that latest version of ActiveCollab and v4 can't run on the same server.
Approach #1: Upgrade on the Same Server
- Make sure you're running ActiveCollab 4.2.17 or later (learn more).
- Do a clean install of ActiveCollab 5.13.133 to a separate location. Version 5.13.133 can run alongside ActiveCollab 4 on the same server, while newer releases require version of PHP that is not compatible with ActveCollab 4. This release is available as additional download on license page of your accounts.activecollab.com profile:
- Installation instructions are available here.
- Check that the ActiveCollab 5 database user has permissions to connect to the ActiveCollab 4 database as well.
- SSH to your server, navigate to the directory where your ActiveCollab 5 is installed, make sure that config/config.php is writable, and run this command:
- php tasks/activecollab-cli.php clone_legacy_data /path/to/activecollab-4/config/config.php
- To rebuild the activity logs, run this command:
- php tasks/activecollab-cli.php rebuild_activity_logs
- To rebuild the search index, run this command:
- php tasks/activecollab-cli.php rebuild_search_index
Steps #3, #4 and #5 can take a while, especially if your ActiveCollab 4 has a lot of data.
If you’re having trouble, it’s possible you have more than one PHP executable installed on the server (eg. php, php5, phpcli).
It's possible your PHP is not CLI or the version is lower than PHP 5.6:
- to check the version, run php -v (or php5 -v depending on the name of executable).
- find all the executables by running whereis php
If you find a PHP executable (CLI + PHP5.6) that's called php-cli (eg. under /usr/local/bin), then you’ll need to run the upgrade this way:
- /usr/local/bin/php-cli tasks/activecollab-cli.php clone_legacy_data /path/to/activecollab-4/config/config.php
After you've upgraded, head off to the ActiveCollab 5 login page, and enter your ActiveCollab 4 username and password. All your projects should be there and you'll be able to continue where you left off.
Now that you have ActiveCollab 5.13.133 installed, and you confirmed that everything's working correctly, you can proceed with upgrade of your PHP and MySQL to meet the system requirements of the latest stable ActiveCollab release. Once this upgrade is done, you can use ActiveCollab's built in upgrade feature to upgrade to the latest release.
Approach #2: Move to a New Server
- Make sure you're running ActiveCollab 4.2.17 or later (learn more).
- Do a clean install of the latest stable ActiveCollab release. Confirm that it works correctly by logging in.
- Create an empty database for ActiveCollab 4 data on the new server, and write down the access credentials. You'll need them in step #6 of the process. Make sure that ActiveCollab 5 database user has permissions to connect to this database as well!
- Open config/config.php of your ActiveCollab 4 system, and look for APPLICATION_UNIQUE_KEY. If you find it, write down it's value. If not, write down value of LICENSE_KEY. You'll need them in step #6 of the process.
- Pack and move ActiveCollab 4 data. In this step we will not move the whole legacy system. All we are doing is moving the data and making it available in form that the new ActiveCollab can import.
Getting the Modules Ready
Before you continue, go to Administration » Modules page of your ActiveCollab 4. Check and make sure that all modules developed by A51 are installed. New ActiveCollab will check for them, and stop the import if it does not find them. It's better to make sure that everything's included in this step, than later, on the new server.
Lets start by packing the data. First, connect to the old server using SSH and cd to a directory where ActiveCollab 4 is installed. We'll do everything from that directory.
Next, export the database contents:
- mysqldump -h DB_HOST -u DB_USER -p --default-character-set=utf8 DB_NAME > db_data.sql
Replace DB values with the correct credentials. If you don't have them written down, you can find them in config/config.php file of your ActiveCollab 4.
mysqldump command will prompt you to enter your database password. You can find the in config/config.php, as DB_PASS. mysqldump command will export all the data in db_data.sql file in the current directory.
Now, create an archive that packs database data with files that your team uploaded:
- zip -r data_export.zip db_data.sql upload public/avatars
This command creates data_export.zip file in the current directory. Everything that you need is in it: database contents, and files that your team uploaded.
Transfer this file to the new server.
Quickest way is to make it available for download on the old server, by moving to /public directory. If you do that, you will be able to use wget or curl to download it on the server:
When you transfer the data, delete it from the old server. You don't want all your data to be available for download like that.
- wget https://my.activecollab4.com/public/data_export.zip
- Getting the data over to the new server is big part of the work. Now we need to prepare a structure that ActiveCollab 5 can read and import data from.
Start by unpacking the data_export.zip archive. We recommend that you cd to a /work directory of your new ActiveCollab, create a subdirectory, and extract the archive there:
- unzip data_export.zip
cd to the export directory, so you are on the same level where db_data.sql file is. Lets import the data in the database that you created in step #3:
- # Connect to database
- mysql -h DB_FOR_V4_HOSTNAME -u DB_FOR_V4_USERNAME -p --default-character-set=utf8 DB_FOR_V4_NAME
- # Set connection encoding and import the data
- mysql > SET NAMES 'utf8';
- mysql > SOURCE db_data.sql;
While you are connected to MySQL, run this query to list database tables and confirm that everything's imported:
- SHOW TABLES;
Disconnect from MySQL by running the exit command:
Next step is to create a fake config/config.php. New ActiveCollab will use this file to connect to the database where we just imported the data. Create a file using your favorite text editor:
- vi config/config.php
with the following content:
- const DB_HOST = 'localhost';
- const DB_USER = '';
- const DB_PASS = '';
- const DB_NAME = '';
- const TABLE_PREFIX = 'acx_';
- const APPLICATION_UNIQUE_KEY = '';
Set access credentials of the database that contains ActiveCollab 4 data (step #3) and APPLICATION_UNIQUE_KEY (step #4).
- Navigate back to the directory where your new ActiveCollab is installed, and run this command:
- php tasks/activecollab-cli.php clone_legacy_data /path/to/activecollab-4-export/config/config.php
- To rebuild the activity logs and search index, run these command:
php tasks/activecollab-cli.php rebuild_activity_logs
php tasks/activecollab-cli.php rebuild_search_index
After you've upgraded, head off to the login page of the new ActiveCollab, and enter your ActiveCollab 4 username and password. All your projects should be there and you'll be able to continue where you left off.
If you're having difficulties, reach out to firstname.lastname@example.org and we'll help you out.