Upgrade from Turnkey ProcessMaker 13 to 14.2

ethanthekiwi's picture

I'm looking to upgrade a ProcessMaker appliance from Turnkey version 13 to 14.2. My two goals are to upgrade the OS and underlying stack for security and to upgrade from ProcessMaker version 2.8 to 3.2 for the features. From what I understand TKLBAM is the recommended way to backup then restore to a new install of Turnkey as you can't do an inplace OS upgrade. I've never used it before and I'm wondering how it would handle the ProcessMaker application side of the upgrade, there's a lot that happens in the application itself when you run an upgrade from 2.8 to 3.x. Does that get factored into the backup and restore?

ethanthekiwi's picture

So I went ahead and tried running TKLBAM. I cloned my VM server, ran a backup to a local data source. (No, I did not use AWS because I don't have an account with the space.)

tklbam-backup --address file:///backup_disk/tklbam/backup --force-profile=empty

Then I restored it to a ProcessMaker Turnkey version 14.2 VM with this:

tklbam-restore --address file:///backup_disk/tklbam/backup --keyfile=/backup_disk/tklbam/key

Both the backup and restore said they went fine. The login screen on ProcessMaker loaded, but when I logged in, I received this error. It kept going for a while so I just grabbed the top bit. I'm guessing TKLBAM isn't very application aware as far as ProcessMaker is concerned. I assume 'wf_58f83c4543eed'@'localhost' is a service user that was not brought over in the backup. Is there something I might have missed here or is TKLBAM not a good solution for what I am trying to do?

PropelException Object
(
    [cause:protected] => SQLException Object
        (
            [userInfo:protected] => wf_58f83c4543eed
            [nativeError:protected] => Access denied for user 'wf_58f83c4543eed'@'localhost' (using password: YES)
            [message:protected] => connect failed [Native Error: Access denied for user 'wf_58f83c4543eed'@'localhost' (using password: YES)] [User Info: wf_58f83c4543eed]
            [string:Exception:private] => 
            [code:protected] => 0
            [file:protected] => /var/www/processmaker/gulliver/thirdparty/creole/drivers/mysql/MySQLConnection.php
            [line:protected] => 89
            [trace:Exception:private] => Array
                (
                    [0] => Array
                        (
                            [file] => /var/www/processmaker/gulliver/thirdparty/creole/Creole.php
                            [line] => 254
                            [function] => connect
                            [class] => MySQLConnection
                            [type] => ->
                            [args] => Array
                                (
                                    [0] => Array
                                        (
                                            [database] => wf_workflow
                                            [encoding] => utf8
                                            [hostspec] => localhost
                                            [password] => 7b8f715404ba791ee1736a4770c5047c
                                            [phptype] => mysql
                                            [port] => 
                                            [protocol] => 
                                            [socket] => 
                                            [username] => wf_58f83c4543eed
                                        )

                                    [1] => 0
                                )

                        )
Jeremy Davis's picture

Underneath the covers, what it does is collects a list of installed packages, dumps all the DBs and collects together files from pre-determined subset of the filesystem. It then runs a diff aof the installed packages and collected files against what the vanilla appliance has (but not the DB AFAIK). It then bundles them into an archive.

On restore, it copys out the existing DB and files (so you can rollback if you wish), installs any required pacakges, extracts the backup archive over the top of the relevant file locations and restores the DB.

It's primary purpose is to backup and restore to the same server. It's secondary purpose is a migration tool and/or disaster recovery to a new appliance (exact same version). As a general rule, it should work fairly flawlessly between minor versions too (e.g. restore v14.0 backup to v14.2 server). Although there are specific appliances where that may not work that well.

When migrating between major versions (e.g. v13.0 -> v14.2) things can sometimes get a bit messy. That is especially the case when migration a server using Apache between v13 & v14. Significant changes occurred within Apache between 2.2 (in v13) and 2.4 (in v14). FWIW, we actually have a doc page that provides a suggested workflow for using TKLBAM to migrate data into v14.x, plus a number of specific considerations. It's not exhaustive, but may be useful?

Personally I would recommend that you do this work within a local VM and as per the doc page guidance; treat it as disposable. So long as you take good notes along the way, that will allow you to be fearless as you go. Worst case scenario, you can rinse and repeat (using your notes to get you back to where you were up to).

With regards to Process Maker itself, I haven't used it much so I can't really be sure. But on face value, you do appear to be correct. The first thing that I would recommend doing after restore, is re-running the Process Maker inithooks. I can't guarantee it will solve all your issues, but hopefully it will allow you to move forward. To rerun the PM DB user setup, try running this:

/usr/lib/inithooks/firstboot.d/20regen-processmaker-secrets
If you experience issues logging into Process Maker via the webUI, you may also want to reset the Process Maker user accounts email and password. I would recommend you wait and see if you need to do this before you just run it. But if you want to try, do this:
/usr/lib/inithooks/bin/processmaker.py
It may also be worth restarting Apache after doing all that. Do that like this:
service apache2 restart
As I noted, I'm not very familiar with Process Maker, but please feel free to post back if you continue to have issues. I can't guarantee that I will have all the answers, but I'm sure that I could at least head you in the right direction.

Please note, that it is still possible to do an in-place upgrade. I.e. upgrade the underlaying OS from Debian Wheezy (v13) to Debian Jessie (v14). However, the issue with that is that if things go pear shaped you may find yourself in a worse situation than you are now! The beauty of using TKLBAM, is that your current server can continue to run as is, until you have ironed out all the wrinkles!

Sorry I don't have something clearer and more concrete, but please post back as you go and I'll do my best to help you out.

ethanthekiwi's picture

Thanks for your reply, I really appreciate your help. I'm thinking the best path would be to upgrade the ProcessMaker Application from 2.8 to 3.2 on the current VM, then spin up a new Turnkey 14.2 VM and migrate the database and support files over. 

Since I started working on this, we decided to upgrade to the cloud hosted edition of ProcessMaker so that made it all easy for me. :)

Jeremy Davis's picture

That certainly sounds like a reasonable plan. I'd recommend that you make sure you have a backup first though so if things go pear shaped you can back out and try again...

If you hit any issues, I can't guarantee I'll have the answers, but hopefully I might at least have some ideas!

Good luck!

Post new comment