Upgrading to LedgerSMB 1.5

Submitted by ehu on

Before starting to update to 1.5, the following are differences to be aware of between 1.4 and 1.5:

  • JavaScript in the browser
  • Additional data constraints
  • PSGI / Apache configuration
  • Printed document templates (e.g. invoice templates)
  • Database schema maintenance

See below for explanations of each of these differences.

 

Important note: before trying to migrate your database to a new version of LedgerSMB, create a backup of the database!

Upgrading from 1.4

The upgrade process for from-tarball installs works the same as the upgrades between 1.4.x and 1.4.y versions (assuming installation in /usr/local/ledgersmb):

  • Stop the server processing LedgerSMB's web requests, by either
    • Stopping Apache (when using a CGI setup -- this is the usual case)
      $ sudo service apache2 stop
      or
      $ sudo /etc/init.d/apache2 stop
    • Stopping Starman (when using PSGI setup)
      $ sudo service starman-ledgersmb stop
  • Move the current software aside:
    $ sudo mv /usr/local/ledgersmb /usr/local/ledgersmb.backup
  • Untar the new software:
    $ sudo tar xf ledgersmb-1.5.x.tar.gz --directory /usr/local

From here, follow the general 1.5 installation instructions.

When done with the installation process, be sure to continue with the company database upgrade instructions.

Upgrading from 1.3

Please follow the instructions for upgrades from 1.4.

Data from 1.3 is migrated to 1.5 by creating a new database schema (new tables) and populating that from the existing 1.3 tables. As 1.4 and 1.5 have added numerous new data integrity constraints, a number of checks have been implemented to validate if a data migration can be successful: pre-migration checks.

Please note that edited data during the pre-migration checks is saved to the original 1.3 database (if you're not running the migration on your backup).

Even if the pre-migration checks succeed, it's happened that the migration still fails. If this is the case with your data, please contact the developers mailing list or the LedgerSMB channel on Matrix.

Upgrading from 1.2

Please follow the instructions for upgrades from 1.4.

Data from 1.2 is migrated to 1.5 by creating a new database schema (new tables) and populating that from the existing 1.2 tables. As 1.3 through 1.5 have added numerous new data integrity constraints, a number of checks have been implemented to validate if a data migration can be successful: pre-migration checks.

Please note that edited data during the pre-migration checks is saved to the original 1.2 database (if you're not running the migration on your backup).

Even if the pre-migration checks succeed, it's happened that the migration still fails. If this is the case with your data, please contact the developers mailing list or the LedgerSMB channel on Matrix.

There's an added complexity to migrations from 1.2 when compared to migrations from 1.3: the user accounts are not migrated. We'd like to address this issue but are unaware of any users currently in need of migrating from 1.2. Please contact the developers mailing list or LedgerSMB channel on Matrix if you experience this problem. We'd like to help and fix our migration code to help any others who still might need this migration.

Upgrading from 1.1 or earlier

There are no direct upgrades from 1.1 or 1.0. Please first upgrade to any version 1.2 through 1.4 before upgrading to 1.5.

Key areas where 1.5 and 1.4 differ

JavaScript in the browser

While JavaScript was mostly optional in all releases prior to 1.5, having it enabled is a hard requirement for the correct operation of LedgerSMB 1.5 and newer.

Additional data constraints

Unlike the 1.3 -> 1.4 upgrade, the upgrade from 1.4 to 1.5 works fully in-place, just as the patch version upgrades within release series. The following constraints have been added and data stored in the database in violation with these constraints may block a successful upgrade:

  • Number of items sold in sales, out of a purchase invoice, may not exceed the total number in the purchase
  • Items in an order are required to exist as parts or services
  • Items in the pricematrix are required to exist as parts or services
  • Make/model details are required to belong to an existing part

PSGI / Apache configuration

The 1.5 release for LedgerSMB doesn't support CGI installation, meaning that the top-level *.pl files have been removed. Instead, LedgerSMB now uses PSGI, a "glue" framework for Perl web applications and their web servers. PSGI allows LedgerSMB to handle requests with much better response times, because the large parts of the application are kept in memory between requests.

To run a PSGI web application, one needs a PSGI compatible web server. The goto PSGI compatible web server is Starman. For production setups exposed to the web, Starman suggests to run behind a so-called reverse proxy.

Apache or Nginx can serve as reverse proxies. Running behind a reverse proxy has two major benefits:

  1. The setup reduces the exposed code footprint to the (highly audited) code of Apache or Nginx
  2. The reverse proxies can handle static content (JavaScript, CSS, images) directly; they do this much more efficiently

In the conf/ directory, there are reverse proxy configuration files for Apache, Nginx and Varnish. There are systemd service configuration files for a ledgersmb starman service as well.

Full installation instructions for the reverse proxy setup can be found elsewhere on this site.

Printed document templates

As of version 1.5, printed document templates are entirely retrieved from the database, including INCLUDEd templates. This differs from 1.4 in the sense that INCLUDEd documents were retrieved from disk while the top-level templates were read from the database. Due to this change in handling, the following changes were required:

  • Inclusion of the letterhead
  • Included files are no longer included with extension

Inclusion of the letterhead

In 1.4, the LETTERHEAD template was included as:

<?lsmb LETTERHEAD ?>

For 1.5, this should be changed to

<?lsmb INCLUDE letterhead ?>

Included files are no longer included with extension

In 1.4, the base check template would be included into "check.tex" as:

  <?lsmb PROCESS check_base.tex ?>

This no longer works in 1.5, due to the fact that the extension isn't supported anymore. The new syntax has become:

  <?lsmb PROCESS check_base ?>

Database schema maintenance

In the 1.4 series, database schema maintenance was done by loading the file sql/modules/Fixes.sql. This process caused a confusing amount of spurious errors and has been replaced by the mechanism in sql/changes/ which separates each schema change out into its own file.

Topic
Upgrade
Installation
Release
1.5
FAQ Category
Installation