Installation/Appliance/Migration
 |
This document refer to the current appliance based on Ubuntu 18.04.
The migration guide for the old version 14.04 published in 2015 can be found here. |
Contents
- 1 Introduction
- 2 Migrate to appliance 18.04
- 3 Restore
- 4 Things to do after the migration
Introduction
| |
Always test the migration in testing servers, before doing the real migration. |
A good idea is, if possible, to keep the old system around for a time. This way if something goes very wrong during or shortly after this migration it is possible to revert to the initial system.
Migrate to appliance 18.04
Currently, it is supported to migrate to the Appliance 18.04 from:
- Openbravo Appliance 14.04
It is NOT possible to directly migrate from the following very old options:
- Openbravo Appliance 12.04
- Old appliance based on rPath
- Ubuntu package: Openbravo installed with the Openbravo package for Ubuntu (sudo apt-get install openbravo-3)
Before the migration, it is highly recommended to have a running instance in a consistent state. This means that no local changes should be present in the database and that the application should compile without any issues.
This is recommended as it allows for clear and easy separation of any potential issue during the migration.
Check compatibility of Openbravo version
To migrate to the new appliance 18.04 it is required to have at least the following Openbravo version (or higher):
- PR / RR 18Q3.3
In general, it is best to use the latest minor release published for both ERP & Retail to have the best version available including the latest important fixes.
Check known incompatible functionality
If you use the Axis Library SOAP Server in any module in your installation then this will NOT work with the new Appliance 18.04 version. The reason is that the axis library version used will not work correctly with the new Java.
However, we are not aware of any user of that functionality so consider it deprecated/obsolete at this time.
Should you use this in your project/installation please reach out to Openbravo Support to let us know.
Check compatibility of modules used in your Installation
As the new Appliance 18.04 updates a lot of stack components in some it is required to update modules to be compatible with it.
Any modules not created by you
In this case please ask the module owner to verify/test if the module is compatible.
Note: Any standard modules from Openbravo itself have been updated and should work with the new Appliance. Should you notice any problem please raise a support ticket/issue with Openbravo.
Modules created by you as a developer
This section is for developers to give some help on how to check compatibility for the new stack.
The main stack changes comparing older Appliance 14.04 with the new Appliance 18.04 are OpenJDK 7 -> 11 and PostgreSQL 9.3 -> 10.
Apart from module compiling and functionality testing the following gives some extra information on specific things to test:
The PostgreSQL project maintains a list of changes and known incompatibilities for each major release. Most of the time those are transparent to most modules. However to check in more detail please check:
- PostgreSQL Release Notes 9.4
- PostgreSQL Release Notes 9.5
- PostgreSQL Release Notes 9.6
- PostgreSQL Release Notes 10
Apart any customization should be reviewed if it requires the tad user to be a database superuser as this is no longer the case as described in the next section. In reviewing our own Openbravo modules we did not find any example of such a customization. If you find a valid case of this and require help in upgrading it, please reach out to Openbravo support.
For the updated OpenJDK / Java version you should verify at the minimum that your code compiles without errors with the new version and also run your functionality using the newer Java. Just compile testing will not catch every possible issue.
Special care should be taken when your module contains extra jar libraries, especially if the versions used have not been updated for a long time. In many cases, those will just work fine with newer java but there are cases where libraries will need to be updated to support the newer java.
Additionally, we recommend reviewing and if possible fixing new compiler or eclipse warnings which are triggered by the newer Java. For example, if some function was marked as deprecated in Java 8, it is likely to be removed on a future Java release. To avoid then later to have your module not compiling you should look out for those deprecations and if possible, fix them when they are added directly to have your code more future proof.
The most common problem is caused by code making use of components that were included out of the box in older JDK versions and finally got removed in JDK 11. Note when the code in modules directly uses those components, it will fail at compile time; but if there are other libraries using them, it will only fail at runtime when trying to execute that specific code.
To see an overview of the changes done in the newer OpenJDK / Java releases, please check on the following:
Check config / system because tad is no longer superuser
Since the 18Q1 release, Openbravo is able to function without having the tad database user being a superuser as was necessary before.
The new Appliance 18.04 now uses a non-superuser tad by default for new installations and upgrades.
That requires to verify three topics which could have been wrongly configured before without bad side-effect.
None of the below issues will be present by default in a clean installation but have been seen in customer installations so they are listed here to aid other migrations.
If any of those issues are found, it should be fixed before migrating to the new Appliance 18.04.
In the Openbravo.properties configuration file:
- The bbdd.systemUser and bbdd.systemPassword values must be set correctly and working
- The bbdd.systemUser must be a superuser, typically postgres. You cannot use tad here also, as tad is no longer a superuser itself.
In the Openbravo database:
- All database objects must be owned by the tad user. It is not possible to have some objects owned by a different user.
This could happen when someone changes the bbdd.user value to different users or even postgres an then ran update.database leading to a mix of database object owners.
Preparation checklist for migration
- Prepare new server, configure the timezone, install updates, reboot
- Check the tomcat and postgres config and migrate to the new server
- /etc/profile.d/tomcat.sh # check if you have changed the xmx of tomcat, etc
- /etc/postgresql/9.3/main/postgresql.conf # check if you have changed the shared buffers, the track functions, etc
- Note: Ensure that the change is still needed, since maybe the new default value is equal or greater than old one.
- Note: Any custom config should be done in the new /etc/postgresql/10/main/conf.d/91-local-custom.conf file.
- Check that you don't have any other databases different that the Openbravo standard one, the backup will ignore it and you need to copy manually in case that you still need it.
- Copy the needed keys of the /home/openbravo/.ssh/authorized_keys.
- Move the backups config
- /etc/openbravo-backup.conf
- crontab -l # as openbravo user will show the backups schedule
- Do a migration test to ensure that everything continues working in the new system
- When you do the final migration, remember that the first step is stop the production tomcat.
From Openbravo appliance 14.04
Attachments, check that you have the backups in the usual path, if not you need to manually copy to new instance, for appliance: /opt/OpenbravoERP/attachments
Appliance 18.04 has PostgreSQL 10 and in appliance 14.04 is PostgreSQL 9.3, the migration process will update the database, usually there are no problems in this migration but if you have custom developments, remember to check that they continue working.
Backup for migrate from appliance 14.04:
- Create a backup in the appliance.
If the new server is configured with public key, then you can follow this process.
Connect to the new server using a private key that is also valid for the old server:
ssh -A openbravo@<ip_new_server>
The '-A' option kind of exports the private key so allows to connect from the new serer to the old one using it. Care should be taken when using the '-A' option as to only use it when connecting to trusted servers.
Then copy the backup from there to the new server:
sudo mkdir -p /backups/manual # create folder to store manual backups sudo chown -R openbravo:openbravo /backups # fix owner of backups folder recursively scp openbravo@<ip_old_server>:/backups/manual/backup-xxx.tar /backups/manual/ # copy the backup from the old machine into the manual backups dir of the new instance. # Note: Change backup-xxx.tar with the name of the backup just created.
Restore
Then you can connect by ssh to the new server and the backup will be in /backups/manual/ folder.
From this point you can follow the normal restore process.
Things to do after the migration
After the migration, a good practice is take a look regularly to the system to check that everything continues fine:
- Check all the logs for errors.
- Check that the backups are done in the configured schedule.
