Upgrading tarball installations
There are two steps to upgrading a LedgerSMB 1.4.x - 1.11.x to 1.12:
- Upgrade the software
- Upgrade the company database
The last step must be executed for each company database that's set up.
Attention when upgrading from before 1.7! Due to the complexity in the upgrade related to the "multiple currency rate support" (MC support), it's of the greatest importance that you create a backup of your data before starting the upgrade. In setup.pl, for every database, you need to download a database backup and a roles backup.
These steps also apply when upgrading a 1.4 installation running Starman. To upgrade 1.4 installations not running on Starman, or to upgrade from earlier versions, please see Upgrading to Ledgersmb 1.5. Note that the default configuration for 1.4 runs CGI, not Starman.
Again, before upgrading: backup your databases.
Note that all the steps below are prefixed with the 'sudo' command, but can be executed as 'root' user directly without the sudo prefix.
Upgrading the software
These are the steps to follow, assuming an installation from tarball:
-
Stop the LedgerSMB application server (e.g. Starman) $ sudo service starman-ledgersmb stop # or, when running a systemd-based Linux distribution: $ sudo systemctl stop ledgersmb
-
Back up the old software by moving it out of the way (assuming you installed in /usr/local/ledgersmb): $ sudo mv /usr/local/ledgersmb /usr/local/ledgersmb.backup
-
Untar the tarball into /usr/local/ledgersmb: $ sudo tar xf ledgersmb-1.12.x.tar.gz --directory /usr/local
-
Copy the configuration file from the old installation: $ sudo cp /usr/local/ledgersmb.backup/ledgersmb.conf /usr/local/ledgersmb/
-
Upgrade the LedgerSMB Starman SysV or systemd scripts (the new scripts can be found in /usr/local/ledgersmb/doc/conf/systemd/ ) $ sudo cp /usr/local/ledgersmb/doc/conf/systemd/ledgersmb_starman.service \ /etc/systemd/system/ledgersmb.service $ sudo systemctl daemon-reload -
Start the LedgerSMB application server again (Starman example given, as before): $ sudo service starman-ledgersmb start # or, when running a systemd-based Linux distribution: $ sudo systemctl start ledgersmb
Upgrading the company database
After the software has been upgraded, the company database(s) must be upgraded. Without this step, a "Database version mismatch" error will be generated on user-login.
To upgrade the company database from the Web UI, navigate to the setup.pl page (e.g. when you're hosting your LedgerSMB on https://localhost/ and normally log in through https://localhost/login.pl, navigate to https://localhost/setup.pl). Log into setup.pl with the database admin credentials (the "lsmb_dbadmin" user, if you followed the installation instructions, or "postgres" if you used the Quickstart Guide).
After login, setup.pl will show a screen with the following at the top:
Logged in as lsmb_dbadmin
LedgerSMB 1.11 db found
Rebuild/Upgrade?
By clicking the "Yes" button, the company database upgrade process will be executed. This is an interactive process which consists of a number of steps. Each step of the upgrade process consists of two phases. In the first phase, the application will verify that the data as available in the database has sufficient quality to be upgraded. If this isn't the case, the user will be asked for input to address quality problems. Once data has acceptable quality, the actual database upgrade will be executed. When all steps in the upgrade have been successfully executed, setup.pl will report complete migration. The database is now available for use again.
Repeat this process for all company databases.
For power-users who need to do scripted upgrades, there's a scripting API available which replaces the interactive process with pre-defined inputs. Contact the developers mailing list for more information.