Installing LedgerSMB 1.5

Submitted by ehu on

This content is outdated and kept here for reference only!

This page contains the comprehensive version with the installation instructions for LedgerSMB 1.5 (as of 1.5.0) targetting a production installation from release tarballs and deals with these steps:

  • Installing the LedgerSMB Perl module dependencies
  • Configuring the PostgreSQL server
  • Configuring a webserver
  • Configuring LedgerSMB

If you already have all of the above, proceed to the "Preparing for first use" guide.

These are not the Quick start instructions, but instructions for setting up a full production system. Also, please note that if you're in a position to use LedgerSMB's Docker images, using those will be far quicker than following the instructions below.

Please note that installation of version 1.5 is completely different from the installation of versions 1.4 or earlier: This version uses Plack to handle integration with front-end web servers. This means LedgerSMB can now be run on many web servers, including (but not limited to):

Of all the things that have become possible with the use of Plack, there's one thing that's no longer possible: running LedgerSMB as set of CGI scripts. This should not be a big concern, since Plack allows plugging LedgerSMB into Apache using mod_fcgid, mod_fastcgi or mod_proxy all of which have been available for versions 2.0 and up.

In order to install LedgerSMB 1.5 from the GitHub repository, a few additional steps need to be performed which fall out of the scope of this document -- these steps come close to being required to set up a development environment. Should you want to proceed regardless, here are the instructions to install LedgerSMB 1.5 from GitHub.

Feel free to log in and share your experiences in the comments at the end of the article.

System requirements

Server

Pre-installed software:

  • Perl 5.10 or newer (full core installation)
  • Perl's "cpanm" module installer
  • PostgreSQL 9.4 or newer
  • FCGI or PSGI compatible web server (as mentioned above)

There isn't any good advice on the RAM requirement; for very small installations, 512MB RAM could be enough.

As for storage requirements: the space required to store the company accounting data is pretty minimal (several 100MB can store years). When storing attachments in the database, storage requirements go up quickly.
Out of the box, there's one major storage requirement: if you want to be able to generate PDF output, LedgerSMB depends on (Xe)LaTeX. When installing (Xe)LaTeX on Debian, that pulls in close to 1GB of packages (unpacked).

Installation of the server side software on Windows isn't explicitly supported by the development team; it might or might not work. If it works for you, please submit your instructions for others to follow.

Client

There are no specific requirements for LedgerSMB clients (web browsers) other than that they should have JavaScript enabled and be able to run Dojo 1.10.

Although the server software isn't explicitly supported on Windows, there's no such restriction for the client software: a broad range of browsers is supported (Chrome, FireFox, Opera, ...), including Microsoft Internet Explorer (10 or newer) and Microsoft Edge.

Browsers explicitly not supported are:

  • Lynx
  • w3m
  • IE9 or earlier

Unpacking the release tarball

The content of the release tarball should be stored in a location accessible to the user which will be running the application server. Reading the Filesystem Hierarchy Standard, both /usr/local/ledgersmb and /opt/ledgersmb could be chosen. To instruct unpacking of the archive, run - from the directory holding the release tarball (as "root" user):

$ tar xf ledgersmb-1.5.x.tar.gz --directory /usr/local/

 

Installing the LedgerSMB Perl module dependencies

Please note that some distributions (e.g. Fedora) do not by default install all core modules, but rather, install a subset. LedgerSMB doesn't list core modules as dependencies but assumes modules to be available. To make sure you have the full list of core packages, please install the perl-core package.

Installing the available modules from your distribution

This section may be skipped, however, in that case, all modules will be installed from CPAN -- see the next section.

Most distributions provide at least part of the modules required to run LedgerSMB. Some administrators prefer installation of the available modules from the distribution, adding the ones missing from the distribution from Perl's own comprehensive source: CPAN.

The list of available modules - distributed at the right version by your distribution - varies from distribution version to distribution version. The section below lists only some of the distributions and their versions. If you have information to add for other versions and distributions, please comment and we'll integrate that.

Debian, Ubuntu/Mint

It's strongly recommended to do new installs of LedgerSMB on a currently stable distribution. As Debian Jessie is "oldstable", it's not included in this list (but that will be available elsewhere). Since Buster is still in flux, the dependency list for it will be updated when its release is imminent. Below then is the list of the example commands to execute in order to install the relevant packages on Debian v9 ("Stretch"):

# Core packages
apt-get install libcarp-always-perl libclass-c3-xs-perl
apt-get install libcgi-emulate-psgi-perl libcgi-simple-perl
apt-get install libcpanel-json-xs-perl libconfig-inifiles-perl
apt-get install libdatetime-perl libdatetime-format-strptime-perl
apt-get install libdbd-pg-perl libdbi-perl libhttp-exception-perl
apt-get install libfile-mimeinfo-perl libjson-maybexs-perl
apt-get install liblocale-maketext-lexicon-perl
apt-get install liblog-log4perl-perl libmime-lite-perl
apt-get install libmath-bigint-gmp-perl libmoose-perl libmoosex-nonmoose-perl
apt-get install libnamespace-autoclean-perl libnumber-format-perl
apt-get install libpgobject-perl libpgobject-simple-perl libpgobject-simple-role-perl
apt-get install libpgobject-type-bigfloat-perl libpgobject-type-bytestring-perl
apt-get install libpgobject-type-datetime-perl
apt-get install libpgobject-util-dbadmin-perl libpgobject-util-dbmethod-perl
apt-get install libplack-perl libplack-builder-conditionals-perl
apt-get install libtemplate-perl libtry-tiny-perl libxml-simple-perl

# Stand-alone Perl server
apt-get install starman

# Packages for PDF/Postscript output
apt-get install libtemplate-plugin-latex-perl libtex-encode-perl
apt-get install texlive-latex-recommended
## Packages for PDF/Postscript output with UTF-8
apt-get install texlive-xetex

# Image size detection in templates
apt-get install libimage-size-perl

# OpenOffice output document
apt-get install libopenoffice-oodoc-perl

# X12 EDI support
apt-get install libx12-parser-perl

After installing the dependencies above, you should continue with the "Installing Perl dependencies directly from CPAN" steps to install any further missing packages.

Fedora, RHEL, CentOS

LedgerSMB  1.5 requires PostgreSQL 9.4+, which isn't avaliable on all RHEL/CentOS distributions. Packages are distributed for these distributions through PostgreSQL's YUM repository. Their site also provides installation instructions.

Note: In recent versions, yum has been replaced by dnf. Other than that, the commands below have remained the same.

# Core packages provided by Fedora 24
yum install perl-CGI-Emulate-PSGI perl-CGI-Simple perl-Config-IniFiles
yum install perl-DBD-Pg perl-DBI perl-DateTime perl-DateTime-Format-Strptime
yum install perl-Digest-MD5 perl-File-MimeInfo perl-JSON-XS
yum install perl-Locale-Maketext perl-Locale-Maketext-Lexicon
yum install perl-Log-Log4perl perl-MIME-Base64 perl-MIME-Lite perl-Math-BigInt-GMP
yum install perl-Moose perl-Number-Format perl-Plack perl-Template-Toolkit
yum install perl-namespace-autoclean perl-MooseX-NonMoose perl-XML-Simple

# Packages provided by Fedora 24 for PDF/Postscript output
yum install perl-TeX-Encode texlive
## Packages provided by Fedora 24 for PDF/Postscript output with UTF-8 support,
## Not found; use the CPAN downloads

# Packages provided by Fedora 24 for standalone Perl server
yum install perl-Starman

# Packages provided by Fedora 24 for OpenOffice output
# Not found; use the CPAN downloads

Installing all required modules directly from CPAN

How to use the modules provided by your distribution is explained in a section below. This section explains how to install (all or all remaining) modules directly from CPAN.

If you want to keep the CPAN-installed modules separate from whatever is in your distribution, you could make use of local::lib. Note that packages installed that way won't be available globally -- a specific environment needs to be set up to make them available.

To install the bare minimum of modules required for LedgerSMB 1.5, issue the following command:
(From the directory where you unpacked ledgersmb.)

# Installation of LedgerSMB Perl dependencies directly from CPAN
cpanm --quiet --notest --with-feature=starman --installdeps /usr/local/ledgersmb/

Then, there are a number of features which need additional modules.
The above command includes the Starman Feature which is required for most installations.
The modules required for each feature can be installed by appending "--with-feature=<feature-name>" to the above command line.

These features are supported:

Feature Description
latex-pdf-ps Enable PDF and PostScript output
Note: In order to make use of this functionality, the server must also have 'latex' or 'xelatex' installed. On many distributions, these packages are called 'texlive-latex' and 'texlive-tetex' respectively.
latex-pdf-images Image size detection for PDF output
starman Starman Perl/PSGI (standalone) web server
openoffice OpenOffice.org document output
edi (EXPERIMENTAL) X12 EDI support
rest (EXPERIMENTAL) RESTful web services

In order to install the starman and pdf/postscript output, the command becomes:

# Installation of LedgerSMB Perl dependencies directly from CPAN
# With Starman and PDF & Postscript output
cpanm --quiet --notest --with-feature=starman --with-feature=latex-pdf-ps \
--installdeps /usr/local/ledgersmb/

Configuring the PostgreSQL server

There are only two requirements for the PostgreSQL database server. This section instructs how to configure an pre-installed PostgreSQL installation to meet those requirements. It's assumed that the LedgerSMB server and PostgreSQL are being run on the same system. The requirements to meet are:

  1. A database administrator user (in PostgreSQL called a 'role') for creation and administration of LedgerSMB company databases
  2. Authorization setup so the database administrator can log into the database through LedgerSMB's 'setup.pl' program

Creating the company database administrator account

The database administrator user account needs to have at the bare minimum:

  • The right to create databases (CREATEDB)
  • The right to create roles (CREATEROLE)
  • The right to log in (LOGIN)
  • A password to authenticate logins

The following command issued as root user, creates a user named "lsmb_dbadmin" (which isn't a super user):

$ su - postgres -c 'createuser -S -d -r -l -P lsmb_dbadmin'
Enter password for new role: ****
Enter it again: ****

Or - alternatively - this command, issued as a user which has 'sudo rights' for user "postgres":

 

$ sudo -u postgres createuser -S -d -r -l -P lsmb_dbadmin
Enter password for new role: ****
Enter it again: ****

 

Configuring database access rights

PostgreSQL takes its access configuration through a file called 'pg_hba.conf'. The location of this file may differ per distribution:

  • Debian derivatives: /etc/postgresql/<version>/<cluster>/pg_hba.conf
  • RedHat derivatives: /var/lib/pgsql/<version>/data/pg_hba.conf

On most systems, this file has four effective lines:

local   all             postgres                                peer
local   all             all                                     peer
host    all             all             127.0.0.1/32            peer
host    all             all             ::1/128                 peer

These lines mean that each system user can connect to the database system with an equally named database user; the connecting source doesn't make a difference: unix and TCP/IP sockets have the same configuration.

The LedgerSMB software needs to be able to connect to the database system as 'lsmb_dbadmin' or as a LedgerSMB user, not as the user that runs the server process. The new content should look like:

local   all             postgres                         peer
local   all             all                              peer
host    all             postgres         127.0.0.1/32     reject
host    all             postgres        ::1/128      reject
host    postgres,template0,template1   lsmb_dbadmin         127.0.0.1/32     md5
host    postgres,template0,template1   lsmb_dbadmin         ::1/128      md5
host    postgres,template0,template1   all          127.0.0.1/32     reject
host    postgres,template0,template1   all          ::1/128      reject
host    all             all             127.0.0.1/32     md5
host    all             all             ::1/128          md5

This configuration takes advantage of the fact that each connection method (unix sockets vs TCP/IP sockets/addresses) can be separately configured. While the default connection method of the 'psql' tool is to connect over the 'local' (unix socket method), the default connection method for LedgerSMB is to use 'localhost' (127.0.0.1/32 or ::1/128).

The above configuration means that the user 'postgres' can't be used any longer to connect from 'localhost', no user can connect to the 'postgres' database through 'localhost' [reject] and all other combinations of users and database names need password authentication [md5].

Notes:

  1. PostgreSQL matches the lines first to last and uses the first matching line, so the order of the lines is of the highest importance.
  2. For more information about the pg_hba.conf configuration options, see the PostgreSQL pg_hba.conf documentation
  3. The databases 'template1' and 'template0' are system databases available in every cluster; this configuration blocks those for access from LedgerSMB as well.

After reconfiguring pg_hba.conf, the PostgreSQL service needs to be restarted. this works with one of the following commands (depending on your distribution):

# restarting postgresql service (as root)
$ service postgresql restart
# - or -:
$ service postgresql-<version> restart

Or similarly, for users with 'sudo' rights, but no root access:

# restarting postgresql service (as user with sudo rights)
$ sudo service postgresql restart
# - or -:
$ sudo service postgresql-<version> restart

Verifying database access

To verify access for the database admin user 'lsmb_dbadmin', an accessible database - not named 'postgres', 'template0' or 'template1' - is required. On new installs, these are the only databases. So the next example creates one. Here's how to verify the setup:

# Verify access configuration (run as root)
$ su - postgres -c 'createdb lsmb_access_test_db'
$ psql -h localhost -U lsmb_dbadmin -d lsmb_access_test_db -c "select version()"
PostgreSQL 9.4.7 <--- this line indicates success("9.4.7" is just an example version number)
$ su - postgres -c 'dropdb lsmb_access_test_db'


# - or - as user with sudo rights:
$ sudo -u postgres createdb lsmb_access_test_db
$ psql -h localhost -U lsmb_dbadmin -d lsmb_access_test_db -c "select version()"
PostgreSQL 9.4.7 <--- this line indicates success ("9.4.7" is just an example version number)
$ sudo -u postgres dropdb lsmb_access_test_db

Configuring a web server

Regardless of your web server setup, configuration of an "application server" is required. The application server used with LedgerSMB can be any PSGI compatible server. The default application server is Starman, which is widely considered the fastest available. The Starman server process lives behind a reverse proxy. While Starman deals specifically with those HTTP requests which require "application logic", all other requests (mostly static content, such as images or CSS) are dealt with by the proxy.

Configuring the Starman application server

Depending on the distribution, a startup method must be installed; this can be one of:

  • SysV init script
  • Upstart configuration
  • Systemd configuration

At the time of writing, the only configuration that comes with LedgerSMB's tarball is the systemd configuration. The following common setup is required regardless of the system used to manage services on the target system.

To support priviledge separation, the Starman server should be running as a user which meets these criteria:

  • Not the same user as the web server
  • Does not have write access to the LedgerSMB directories

To that extent, identify an existing (unused) system user, or create one with this command:

# create 'ledgersmb' user for Starman server to run
$ useradd -d /non-existent -r -U -c "LedgerSMB/Starman service system user" ledgersmb

Configuring systemd for Starman

In the directory conf/systemd/ from the tarbal, there is a preconfigured systemd service file, which needs to be copied into place. In case you decided to install dependencies into a local::lib, the service file needs to be edited to set a PERL5LIB environment variable before you can succesfully start the service.

# 'copy' systemd service configuration, enable and start
$ sed -e "s#WORKING_DIR#$PWD#" conf/systemd/starman-ledgersmb.service \
| sudo tee /etc/systemd/system/starman-ledgersmb.service
$ systemctl enable starman-ledgersmb
$ service starman-ledgersmb start

Note that the above assumes that the commands are being run from the root of the unpacked tarball. It also assumes that the tarball has been unpacked at its installation path.

To verify that the service started up correctly, run:

# verify that the Starman/LedgerSMB server started correctly
$ journalctl -u starman-ledgersmb.service --since="today" -l -e

Configuring a reverse proxy

For a quick test-run or demo setup running on localhost only, configuration of a proxy isn't mandatory. However, for a production setup with LedgerSMB being network or even web-exposed, it's ill-advised to run without the reverse proxy for - at least - the following reasons:

  • The proxy can serve static content [much] more efficiently (performance)
  • The proxy guards Starman against public exposure (security)
  • The proxy adds TLS/SSL (security)

The reverse proxies documented below all have been and continuously are being tested and reviewed for correctly handling various kinds of malicious network traffic.

With TLS/SSL certificates being completely free these days through Let's Encrypt, and only a few dollars for the simplest of certificates from commercial vendors, there's really no reason not to secure traffic to the server. Further documentation below assumes you have such a certificate. As for getting Let's Encrypt certificates, use their Getting Started guide.

Of the following sections (Configuring nginx, Configuring Apache, Configuring lighttpd), there's only the need to follow instructions of one section: the one for the proxy of choice.

Configuring nginx

The tarball contains an example virtual host configuration file to set up a reverse proxy with nginx. It needs to be included in the 'http { }' block in your nginx configuration. On Debian derived systems, this is done by copying the file to /etc/nginx/sites-available/ledgersmb.conf. On RedHat/Fedora derivatives, the copying goes to /etc/nginx/conf.d/ledgersmb.conf. After editing the file, replacing the following variables:

  • WORKING_DIR
    Same replacement as before
  • SSL_CERT_FILE
    Should be where your certificate file is stored; probably /etc/certs/your_host.example.com.pem
  • SSL_KEY_FILE
    Probably the same as the SSL_CERT_FILE, but with '.key' extension
  • YOUR_SERVER_NAME
    If nothing else, should be replaced by the output of the command 'hostname -f'

 

NOTE: by default snakeoil certificates will be used by at least our nginx sample config files.
These certificates are locally created and will normally require your browser clients to override something before they can be used.

On Debian derivatives, activate this file after it has been edited, using:

# On Debian/Ubuntu/Mint activate the virtual host
$ ln -s /etc/nginx/sites-available/ledgersmb.conf /etc/nginx/sites-enabled/

On RedHat/Fedora derivatives, no symlinking is necessary: the configuration is active immediately. Now, verify that the configuration is acceptable:

# (Re)start nginx service to make nginx reconfigure itself and validate configuration
$ service nginx restart

Configuring Apache

The tarball contains an example virtual host configuration file to set up a reverse proxy with Apache. It needs to be included in the Apache configuration. On Debian derived systems, this is done by copying the file to /etc/apache2/sites-available/ledgersmb.conf. On RedHat/Fedora derivatives, the copying goes to /etc/httpd/conf.d/ledgersmb.conf. After editing the file, replacing the following variables:

  • WORKING_DIR
    Same replacement as before
  • SSL_CERT_FILE
    Should be where your certificate file is stored; probably /etc/certs/your_host.example.com.pem
  • SSL_KEY_FILE
    Probably the same as the SSL_CERT_FILE, but with '.key' extension
  • SSL_CHAIN_FILE
    The chain file provided by your SSL vendor, with a '.pem' extension
  • YOUR_SERVER_NAME
    If nothing else, should be replaced by the output of the command 'hostname -f'

On Debian derivatives, activate this file after it has been edited, using:

# On Debian/Ubuntu/Mint activate the virtual host
$ a2ensite ledgersmb.conf

# On Debian/Ubuntu/Mint activate the required modules
$ a2enmod rewrite
$ a2enmod proxy
$ a2enmod proxy_http

On RedHat/Fedora derivatives, no symlinking is necessary: the configuration is active immediately. Now, verify that the configuration is acceptable:

# (Re)start service to make apache reconfigure itself and validate configuration
$ service apache2 restart # Debian/Ubuntu/Mint
$ service httpd restart # RedHat/Fedora/CentOS

Configuring lighttpd

<to be done>

Configuring LedgerSMB

The tarball has a default LedgerSMB configuration file conf/ledgersmb.conf.default. Install the configuration file with:

# Install the default ledgersmb.conf configuration file
$ cp conf/ledgersmb.conf.default ledgersmb.conf

That is it.

In case the in-app e-mail feature is going to be used, check the values in the [mail] section and optionally adjust for the mail setup of the target system.

Next steps

Now follow the instructions in the "Prepare LedgerSMB for first use" guide.

Topic
Installation
Obsolete
Release
1.5