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 v6.
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).
The process starts with installing the latest version of ActiveCollab on a new server. The next step is to move only the data from ActiveCollab 4 and importing it.
This is because v6 of ActiveCollab 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.
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 6 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 its value. If not, write down the 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.
- 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:
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:
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:
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.