Converting BillMax to Debian Installation Steps

  1. Deploy a new server running Debian 12.x. See Install BillMax. Request a new license key making sure to let BillMax support know that this key is for your new Debian host. Remember your choice for the Database Password (on the BillMax information tab). You will need to supply this password later.
  2. Note:
    You will need a license key prior to upgrading the BillMax database schema.
    Login into the new BillMax staff interface. Go to System Administration > License. Copy and paste (save) the License Key.
  3. As root and in the /root directory, run the following command: diff -r /usr/local/billmax /opt/billmax/software | grep -v -E '\.svn$|\.o$|\.d$' | grep -v -E '/usr/local/billmax/(documents|efp|logs|tmp|uploadedfiles|cdrfiles|backups|prepaidcards|snapshots|importtools|uploadedfiles)' > upgradedifferences.dat
  4. Examine the results in upgradedifferences.dat. Any pertinent changes will have to be done on the new server.
  5. Stop mariadb, httpd and edge on the CentOS 7® server. As root execute: systemctl stop mariadb httpd bx_edge
  6. On the CentOS 7® server, make a copy of the entire database instance (this includes billmax as well as all other databases). As root execute:
    1. cd /var/lib
    2. tar czf mysql.yyyy-mm-dd.tgz mysql (where yyyy-mm-dd is the current date).
  7. Restart mariadb, httpd and edge on the CentOS 7® server. As root execute: systemctl start mariadb httpd bx_edge. Do not restart if this is your final data migration.
  8. Copy the mysql.yyyy-mm-dd.tgz file to the Debian host: scp mysql.yyyy-mm-dd.tgz admin@<Debian ip or host name>:
  9. Note:
    The rest of these steps are on the Debian server.
    Stop mariadb. As root execute: systemctl stop mariadb
  10. Move the existing mysql instance out of the way. As root execute: cd /var/lib; mv mysql mysql.original
  11. Restore the database files from the CentOS 7® server. As root execute:
    1. cd /var/lib
    2. tar xzf /home/admin/mysql.yyyy-mm-dd.tgz
  12. Restart mariadb. As root execute: systemctl start mariadb
  13. Note:
    You will need the root password from the CentOS server for this step. You can retrieve this password from /usr/local/billmax/local/billmax.conf (MYSQL_ADMIN_PASSWD setting).
    Fix a few mariadb settings. Execute:
    1. mysql -u root -p mysql
    2. CREATE USER 'mariadb.sys';
    3. ALTER USER root@localhost IDENTIFIED VIA unix_socket;
    4. FLUSH privileges;
    5. quit
  14. Run mariadb command for upgrading databases to a new version. As root execute: mysql_upgrade --force
  15. Restart mariadb. As root execute: systemctl restart mariadb
  16. Check the system log for any mariadb logs on startup: journalctl -xeu mariadb
  17. Restore license key. Copy the license key to the clipboard. Paste key when prompted. As the billmax user execute: /usr/local/billmax/bin/license_install
  18. Note:
    Be sure you have tuned the database before converting it.
    Convert BillMax tables to InnoDb and UTF8 character set. As the billmax user execute: /usr/local/billmax/bin/convert2InnoDB -p 15
  19. Update BillMax database schema and run upgrade scripts. You will be prompted to enter the BillMax version that is running on the CentOS server. You can get this value via the Help > About menu. Supply the full version string (4.0.XXXXXX). As the billmax user cd /usr/local/billmax/pkg and execute: /usr/local/billmax/pkg/upgrade_db_only.pl
  20. Verify that the database has no errors. As the billmax user execute: /usr/local/billmax/bin/dbck
  21. Make sure that the nightly processes are not configured to run. Go to System Administration > > Batch Processing and disable all active batch groups. If performing the final migration, re-enable the same batch process groups. This process ensures that the crontab is updated properly.
  22. While testing, you should change credit card processor to the dummy processor called ‘Loopback’. Set the State value for all active Credit Card and Bank Account lists to ‘Not Active’. Set the State value for the Loopback lists to ‘Active’. Also you should disable printing and email by setting the appropriate commands in the Global Options to /bin/true. These steps should not be done for the final data migration.
  23. Consider using BillMax test tools to run the system forward to test batch processing. Contact support for details.
  24. Copy the runtime files from your CentOS server to the Debian server. Run time files include any data file, custom configuration files, provisioning scripts and so on. The following commands copy the required (bare minimum) files. Depending on your use, you may need additional files. For example, you will want any customizations you have made like changes to templates, source files, etc. On the CentOS server. As root:
    1. cd /usr/local/billmax
    2. tar czf runtime.yyyy-mm-dd.tgz backups documents efp local logs html\images portal.v2/config/edge.php uploadedfiles (where yyyy-mm-dd is the current date)
    3. scp runtime.yyyy-mm-dd.tgz admin@<Debian ip or host name>:
  25. Redo any local customizations that were noted in upgradeddifferences.dat.
  26. On the Debian server as root:
    1. Note:
      This step omits the local directory. For the local directory, extract it separately to a work directory. Then selectively copy the needed customized files.
      cd /usr/local/billmax
    2. tar xzf /home/admin/runtime.yyyy-mm-dd.tgz backups documents efp logs html\images portal.v2/config/edge.php uploadedfiles (where yyyy-mm-dd is the current date)
  27. Review, configure and test all subsystems: backups, email, printing, customer portal (server side), remote portal (client side), ticket email gateway, provisioning, etc) that BillMax relies on. In particular:
    1. For the customer portal's server side configuration, it is possible to copy and install all the configuration files from the CentOS server. However, this task is easier to perform by re-configuring this subsystem. This is done via the setup_edge command.
      You will still need to capture and install your changes to the edge.php. This file is found in the portal's config directory.
    2. For the ticketing email gateway, execute the setup_ticketing command. Then using the Staff interface, edit any email enabled queue. Modify the Server Options field to any string. Save the queue, then reset the Server Options field to it's original value. Then save the queue one more time. This process will create the needed /home/billmax/.fetchmail.rc file.
  28. Once satisfied that everything is working correctly and all subsystems are configured and tested, schedule the final data migration. Repeat steps 3-18 but do not enable processing on the CentOS server. If everything goes to plan, be sure to disable all services on the CentOS server. Make DNS changes as needed, etc.