LedgerSMB.org Site Feed
Upgrade to LedgerSMB 1.11 (from 1.10 through 1.4)
There are two steps to upgrading a LedgerSMB 1.4.x - 1.10.x to 1.11:
- 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 softwareThese are the steps to follow, assuming an installation from tarball:
- Stop the LedgerSMB application server (e.g. Starman) $ sudo service starman-ledgersmb stop
- 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.11.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
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.10 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.
ehu Sun, 10/01/2023 - 12:15 Topic Installation Release 1.5 1.6 1.7 1.8 1.9 1.10 1.11
Installing LedgerSMB 1.11
This page contains the comprehensive version with the installation instructions for LedgerSMB 1.7 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, please 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, or packages for your Unix/Linux distribution, using those will be far quicker and easier than following the instructions below.
System requirementsRequirements are documented on the system requirements page.
ClientThere are no specific requirements for LedgerSMB clients (web browsers) other than that they should have JavaScript enabled and be able to run Dojo 1.17.
A broad range of browsers is supported (Chrome, FireFox, Opera, ...).
Browsers explicitly not supported are:
- Lynx
- w3m
- Internet Explorer
According to the Filesystem Hierarchy Standard, both /usr/local/ledgersmb and /opt/ledgersmb could be chosen as install locations. Unpack the tarball by running (as "root" user):
# tar xf ledgersmb-1.7.x.tar.gz --directory /usr/local/ Installing the LedgerSMB Perl module dependenciesPlease 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 as they should be available. For Fedora, this means you need to install the "perl-core" package.
The instructions below assume all dependencies will be installed from CPAN. It is however possible to install most modules from distribution repositories. The Docker image can be consulted for an example.
# Installation of LedgerSMB Perl dependencies 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=" to the above command line.
These features are supported:
Feature Description latex-pdf-ps Enable PDF and PostScript outputNote: 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. starman Starman Perl/PSGI (standalone) web server openoffice OpenOffice.org document output xls Microsoft Excel output edi (EXPERIMENTAL) X12 EDI support
# 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/
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:
- A database administrator user (in PostgreSQL called a 'role') for creation and administration of LedgerSMB company databases
- Authorization setup so the database administrator can log into the database through LedgerSMB's 'setup.pl' program
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: ************
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///pg_hba.conf
- RedHat derivatives: /var/lib/pgsql//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:
- PostgreSQL matches the lines first to last and uses the first matching line, so the order of the lines is very importance.
- For more information about the pg_hba.conf configuration options, see the PostgreSQL pg_hba.conf documentation
- 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- restart
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'
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 serverDepending 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
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/ledgersmb_starman.service \
| sudo tee /etc/systemd/system/ledgersmb-starman.service
$ systemctl enable ledgersmb-starman
$ service ledgersmb-starman 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 ledgersmb-starman.service --since="today" -l -e
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 can support HTTP/2 which multiplexes requests (performance)
- The proxy guards Starman against public exposure (security)
- The proxy adds TLS (security)
With TLS 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.
For simplicity, only the configuration of nginx as a reverse proxy is documented here.
Configuring nginxThe 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:
- 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
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 doc/conf/ledgersmb.yaml ledgersmb.yaml
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 stepsNow follow the instructions in the "Prepare LedgerSMB for first use" guide.
ehu Sun, 10/01/2023 - 11:04 Topic Installation Release 1.11Preparing LedgerSMB 1.11 for first use
This page explains how to set up LedgerSMB's first company after having completed installation, e.g. through the docker-compose.yml file. Please note that your full URL may differ depending on your installation method.
In case you just completed the quick-start instructions, the base URL at which LedgerSMB is accessible is http://localhost:5762 (If you have a full production setup, you shouldn't need the port indicator [the ":5762" part]). There are two URLs (entry-points) you can use to access the application, each with a specific purpose:
- /setup.pl [full URL: http://localhost:5762/setup.pl ] is the main tool for the database admin ("postgres" [or "lsmb_dbadmin" if you created it]); it serves to create new companies, create copies of companies, add users to companies and reset user's passwords;
- /login.pl [full URL: http://localhost:5762/login.pl ] provides access to all other types of users.
After browsing to setup.pl, the browser should show:
In case the screen only shows the "Database" field, this indicates problems with JavaScript not having loaded correctly. Fill out the fields as follows:
- Super-user login: lsmb_dbadmin
- Password:
- Database: testcompany
Confirm the screen by clicking "Create". When the server is done creating the database for the company, a new screen will be returned. This can take up to 20 seconds.
The resulting screen shows:
Click "Skip" in order to skip loading a pre-defined Chart of Accounts. Select a country and click Next to list the pre-defined charts of accounts.
The resulting screen then shows a list of available Charts of Accounts:
The screen above isn't shown when "Skip" was selected in the step before. Clicking "Skip" in this screen skips loading a pre-defined chart of accounts.
Regardless of whether CoA loading was skipped or performed, the following screen will be presented:
Select 'demo' templates for use with LaTeX; select 'xedemo' templates for use with XeLaTeX (which has better support for UTF-8 / accented characters and non-latin character sets). The exact choice made in this step is not highly important: templates can later be changed by loading new ones into the database. After confirming the selection by clicking "Load Templates", the following screen shows:
With this screen, the first user for this company gets created. There are two modes:
- Import (Yes): Assumes the username already exists in the database (e.g. because it is already used for another company; re-uses the existing username+password)
- Create (No): Assumes the username does not already exist; will create a new username
The "Assign Permissions" selection determines the rights assigned to the user:
- "Full Permissions": The user may perform any task in the application
- "Manage Users": The user has just enough rights to create new users who have appropriate rights
For the purpose of this quick-start guide, enter the following details:
- Username: first_user
- Password: first_user
- Import: No
- Salutation: Mr
- First Name: First
- Last Name: User
- Employee Number: 1
- Date of Birth: (today's date)
- Tax ID/SSN: 1
- Country: (your country)
- Assign Permissions: Full Permissions
After confirming these data by clicking the "Create User" button, the following screen shows:
First user loginThe "Start Using LedgerSMB" link opens the main application login screen, which can be used to log in using the initial user created above:
Confirming login results in the following page*:
* Note that the picture shows company name "test10", but when succinctly following the instructions, it should show "testcompany".
Database administration of first companyOnce the testcompany has been created, it can be logged into through setup.pl as well as through login.pl. When logging in through setup.pl, the following screen with database administration functions shows:
What's next?The system is now set up for evaluation and testing. The project has multiple channels to contact other users or the developers. Read all about that on the community project resources page.
Any comments as to this specific article? Please sign up to the site and leave your comments below!
ehu Fri, 09/01/2023 - 12:04 Release 1.11