Short answer: add the "--preload-app" flag to the Starman command line.

Long answer: As of LedgerSMB 1.8, session information is stored in an encrypted cookie. To make sure the encryption key is unique for every installation, a new encryption secret is being generated each time LedgerSMB is started. However, Starman (without the "--preload-app" flag) loads the application in each forked worker separately, leading to different encryption secrets in each worker with the indicated behaviour as a result.

There are two steps to upgrading a LedgerSMB 1.8.x installation to 1.8.y (x smaller than y):

1. Upgrade the software
2. Upgrade the company database

The second step has to be executed for each company database that's set up.

Upgrade the software

The steps to upgrade the software differ between Docker or tarball (from source) installations.

Upgrading Docker installations

In case the installation was created using the docker-compose infrastructure provided by the project, the upgrade should be as simple as running

$ docker-compose pull
$ docker-compose up -d

in the directory where you initially ran the "docker-compose up -d" command. The above commands should produce this output:

Recreating ledgersmb-docker_postgres_1 ... done
Recreating ledgersmb-docker_lsmb_1     ... done

Note that the "ledgersmb-docker" prefix may differ, depending on the name of the directory your docker-compose.yml file is stored in (in this case it was called "ledgersmb-docker/").

Upgrading tarball installations

Note that all the steps below are prefixed with the 'sudo' command, but these can be executed as 'root' directly as well.

# 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.6.y.tar.gz --directory /usr/local
 
# Copy the configuration file from the old installation:
$ sudo cp /usr/local/ledgersmb.backup/ledgersmb.conf /usr/local/ledgersmb/
 
# Start the LedgerSMB application server again (Starman example given, as before):
$ sudo service starman-ledgersmb start

Upgrading the company database

After the software has been upgraded, the company database(s) have to be upgraded. When a user logs in on a database which is of a version different from the software that's used to access the database, a "Database version mismatch" error will be generated.

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, now you need to 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).

After login, setup.pl will show a sccreen with the following at the top:

 

Logged in as lsmb_dbadmin
LedgerSMB 1.8 db found
Rebuild/Upgrade?

By clicking the "Yes" button, the company database upgrade process will be executed.

Repeat this process for all company databases.

Short answer: Due to differences in the database schema in relation to storing foreign currency transactions.

Long answer: The database schema before 1.7 required 2 database rows in the acc_trans table to store functional currency and foreign currency amounts. As of 1.7, the schema stores these two amounts - which relate to the same journal line - into one database row. When migrating data from the old schema to the new one, the migration routine tries hard to identify pairs of rows which can be combined into a single row in the new schema.

Upgrading tarball installations

There are two steps to upgrading a LedgerSMB 1.5.x installation to 1.5.y (x smaller than y):

1. Upgrade the software
2. Upgrade the company database

The last step has to be executed for each company database that's set up.

Note that all the steps below are prefixed with the 'sudo' command, but these can be executed as 'root' directly as well.

Upgrading the software

This is by far the easiest part. These are the steps to go through, 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.5.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/
• Start the LedgerSMB application server again (Starman example given, as before):
  $ sudo service starman-ledgersmb start

Upgrading the company database

After the software has been upgraded, the company database(s) have to be upgraded. When a user logs in on a database which is of a version different from the software that's used to access the database, a "Database version mismatch" error will be generated.

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, now you need to 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).

After login, setup.pl will show a sccreen with the following at the top:

 

Logged in as lsmb_dbadmin
LedgerSMB 1.5 db found
Rebuild/Upgrade?

By clicking the "Yes" button, the company database upgrade process will be executed.

Repeat this process for all company databases.

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.

The table below lists the compatibility of LedgerSMB versions with Perl versions. Products for which support has ceased due to End-of-Life date being reached are not listed and should not be used.

Versions 1.8 and earlier are not in this table due to the fact that they're past End of Life.

* These Perl versions are distributed with a version of Math::BigFloat which is incompatible with LedgerSMB 1.9.
** There's a bug in 1.10 which prevents its modules to be loaded with Perl 5.40

## At the terminal, and from your LedgerSMB directory:
### Start Starman

starman  tools/starman.psgi

Default port is 5000.

starman -l :8080 tools/starman.psgi

Start with 8080 specified as the port.

Note: some documentation specifies the switch

--preload-app

It has been sugggested that this may give performance advantages in a production environment but isn't recommended while developing.
The manpage has more to say on this.

man starman

Based on that we currently would not recommend using --preload-app even on a production server

### While Starman is running

#### Reload Starman

pkill -HUP -f "starman master"

#### Restart Starman {#RestartStarman}

pkill -TERM -f "starman master"

#### Release the port if Starman is terminated
NOTE: try [Restart Starman](#RestartStarman) before doing this.

pkill -KILL -f "starman master"

First of all, you need to backup all your company databases followed by an upgrade of your PostgreSQL installation. There are plenty of places on the web to explain how to do that. The high-level process is to install the two versions in parallel and run the pg_upgradecluster command.

When the technical upgrade has succeeded, however, you're not ready to see the performance improvements promised by the 8.4+ versions of PostgreSQL with respect to the menu-generation. This is because the database doesn't automatically use the new 8.4+ code definitions.

To take advantage of the performance improvements of 8.4+, you'll need to re-run setup.pl on all your company databases. With each of the databases, you can clean up after having run setup.pl: the tablefunc contrib is no longer required, meaning you can

psql -U ledgersmb -d -f /uninstall_tablefunc.sql

On my own database I needed to run the above command three times to make it stop reporting "ERROR: Can't DROP because other objects depend on it." (On each round the number of other errors increased: on each round the number of objects successfully being dropped increased.)

That should do it. You should have a clean 8.4+ PostgreSQL database with LedgerSMB.

In general: neither. The advice is to have the full source tree in /opt/ledgersmb/<version>.

Installing the LedgerSMB modules in the standard Perl search path works, but interferes with running different versions side-by-side.

To undo installation in /usr/local:

• remove /usr/local/share/perl/5.XX.X/LedgerSMB/
• delete /usr/local/share/perl/5.XX.X/LedgerSMB.pm; and
• find and remove the .pl files that come in LedgerSMB's project root directory and bin/ and LedgerSMB/Scripts/ directories.

The default configuration limits access to the /ledgersmb/login.pl page to connections from localhost (127.0.0.1) only for maximum security.

If you want to allow connections from other locations, it's highly advisable to use encrypted (VPN) connections to access your ledger in order to maintain good security.

Q: This particular merchant runs Windows. I don't think they have a pole display, though I can check. Ideally, it would be great to accommodate, with or without pole display. If it runs better on Linux, going forward I would propose Linux workstations for new merchants.

Ok. Let's first explain what the problems we have to solve are, then discuss the solutions that are bundled.

In general web browsers are engineered so that malicious sites can't access your computer's hardware. In general we don't want to change the browser (for example with an add-on) to make it do this because there might be a capacity for abuse elsewhere. So things like receipt printers, pole displays, cash drawers, and barcode scanners cannot be directly be accessed by the browser. This makes a web-based point of sale rather challenging, but we have solutions to these problems. The solutions though are only tested on Linux. On Windows they will require slight modification and I would recommend some extra testing. Backup/fallback methods are discussed below as well. What we do instead preferably is to turn the point of sale terminal into a server for the point of sale hardware. Scripts to do this (written in Bash) are in the utils/pos directory of the LedgerSMB installation. the client-side script is pos-hardware-client-startup-script which basically fires up netcat and listens for data to redirect to a hardware port. You probably want to use firewall software to limit this traffic to approved servers. The ports are configurable on both ends. On the LedgerSMB side, see the pos.conf.pl. The other is directnet.pl which is used to send printable documents over this (and to the POS printer on the other side). This is designed to be a low-latency alternative to using CUPS and the like. It redirects pole display logic usually to a serial port, and the printer logic to a parallel port. This means you can use any printer that accepts ESC/POS and it will send signals to open the cash drawer (programmable in the pos.conf.pl) if the cash drawer is the kind that plugs into the printer. You can also use a pole display although currently we only have drivers for the LC3000 by Logic Controls. The drivers are really easy to write though. Feel free to ask for help or contribute one. Barcode scanners and magnetic stripe readers need to come into the computer as keyboard input. Typically this means a keyboard wedge interface for magstripe readers, and either a keyboard interface for a barcode scanner, or a barcode scanner attached to a POS keyboard with a built-in barcode decoder. I have had better luck with the latter in terms of long-term maintenance, but they both work. On to the pos.conf.pl. The default values here are in the pos.conf.pl.template, so please cp pos.conf.pl.template pos.conf.pl For the miost part this defines a single variable for storing the information called $pos_config. Keys for this and their significance are: rem_host: Remote host to send pole display/printer info to. By default this is the remote host. However if you are running X11 applications remotely you may have to change this. pd_host; Host for the pole display. Defaults to rem_host pd_port: Port for the pole display. Defaults to 6601 pd_proto: Protocol for pd. Either 'tcp' or 'udp' defaulting to udp. rp_host rp_port rp_proto Same as pd_* above but for printer rp_cash_open: The code to open the printer. Defaults to those for the Epson U220D iirc, which is binary string of values 27, 112, 0, 25, 250 coa_prefix: prefix for the till amounts. If you have a till '16' and a coa_prefix of 1300, the till account will be 1300.16. This account must exist or you will get errors. close_cash_accno: Cash account to put closing cash into. Must exist by closing time. $pos_sources is used to define memo fields for different types of payment. You can customize this as you want. $pos_source_default is the default for the sources drop down. curren is the currency breakdown covers your currency denominations. Used in closing. I dont know if you want to add a 0.5 as 50 cent piece there since those are rare. till_type is either the 'cashier' meaning the employee id becomes the till number or 'terminal' in which the last octet of the IP address becomes the till number. If you need to customize this handling you can do so underneath the request to stop editing at a certain point. Advanced options include source_accno_override used to override cash account handling of various sources (such as gift certs for example) disable_tables is no longer necessary. But you can use this if you aren't using projects and/or departments. It defaults to disabling everything. If the directnet approach for printing does not work for you you can comment out the printer definition at the bottom of the pos.conf.pl and set up cups to process and send the file to the workstation to be printed. This adds a few seconds often, however, so where directnet works, it is preferred especially in time-critical point of sale environments.

I manage several companies on LedgerSMB, can I login to any of these companies with one user?
Applies to LedgerSMB 1.3.x -->
V. 0.1 - 22. Nov 2011

I have 100 companies though on my system and decide to change my password, wouldn't I have to change it a 100 times (one for each company)? What would be the best approach to setting up a user that could be used on several companies (databases)?

In LedgerSMB all your users are database users in PostgreSQL. All PostgreSQL users do not have access to login with LedgerSMB on each company database(s). LedgerSMB has to give access to each user as an LedgerSMB application user, even if the user have PostgreSQL superuser rights on the database level.

You can add the Postgresql user to be a LedgerSMB application user when you make an new database or after the database is created. If you import the account into all the other databases, the password management is consistent cross the databases. However, you are not guaranteed the same permissions on all databases. You could have one set on one database and another set on another.

Fast route: User get "Manage Users" or "Full Permissons" access to LedgerSMB
Use setup.pl to create company database number 1 with ledgersmbdbadm user.
Add a normal application user in the proses ("Enter User" screen) example: your_100_db_user_name

Use setup.pl to create company database number 2, 3, 4... with ledgersmbadm user (or a special admin user for each db).
Import the normal application user you made in database 1 ("Enter User" screen in setup.pl)
Username: your_100_db_user_name
Password: Do not set a password. Leave it blank
Import : Yes
Fill inn first name, last name and select Country and assign permissions.

You can also add the user to the db later:
System->Admin Users->Add Users
Username: your_100_db_user_name
Password: Only set a password in the firstdb. Leave it blank in db 2, 3, 4..
Import : Yes
Fill inn first name, last name and select Contry and assign permissions.

If you add the users later you have the opions to add only the permissions the user needs to do a spesific task.

Technical solution:
From LedgeSMB use this user to setup the database you create a databaseuser with Superuser priviliges.
CREATE USER ledgersmbdbadm WITH superuser password 'somepassword';

Create a normal user
CREATE USER your_100_db_user_name WITH password 'somepassword';
(normal user with no drop db rights)

When you create the db:
Use setup.pl to make the company database(es). Use the ledgersmbdbadm user to login to create the company database (first screen) and add a new user on the ("Enter User" screen)
Username: your_100_db_user_name
Password: Do not set a password. Leave it blank
Import : Yes
Fill inn first name, last name and select Contry and assign permissions.

You can add the user to the db later:
System->Admin Users->Add Users
Username: your_100_db_user_name
Password: Do not set a password. Leave it blank
Import : Yes
Fill inn first name, last name and select Contry and assign permissions.

If you add the users later you have the opions to add only the permissions the user needs to do a spesific task.

Direct login to correct company, take a look at this:
/faq/can-ledgersmbloginpl-take-arguments

Compiled from this e-mail treads:
http://permalink.gmane.org/gmane.comp.finance.ledger.smb.user/5334
http://permalink.gmane.org/gmane.comp.finance.ledger.smb.user/5356
Question from: Steven Marshall
Answer from Håvard Sørli and Chris Travers

Short error:
Math::BigInt: couldn't load specified math lib(s), fallback to Math::BigInt::FastCalc

Full error message:
[Thu Nov 10 22:53:58 2011] [error] [client 127.0.0.1] Math::BigInt: couldn't load specified math lib(s), fallback to Math::BigInt::FastCalc at /usr/local/share/perl/5.10.1/LedgerSMB/Form.pm line 61, referer: http://localhost/ledgersmb/menu.pl?login=username&menu=1&id=103&open=:

What should you do with this? Nothing or install math libs

From irc:
ehu: you can run without it, just slower.
ehu: but you can install it and rid yourself of the error reported.

Install Math:BigInt:GMP to get rid of the message.

Debian:
apt-get install libmath-bigint-gmp-perl

Ubuntu 10.4 LTS:
sudo apt-get install libmath-bigint-gmp-perl

RPM (Centos, Redhat...)
perl-Math-BigInt-GMP is available from the rpmforge repository - http://repoforge.org/

From irc:
haso: The setup script do not check for it. ... Should it ?
ehu: well, since you can run without, I don't think so.
ehu: do you?
haso: It could be an informed option.
ehu: well, that's indeed an idea.
ehu: it's in the install file for debian and RH, I think.

Q: How could I set it up ledgersmb to support SSL connection?

SSL support on Apache is handled by configuring Apache. For having LedgerSMB connect to PostgreSQL using SSL, you can set the PGSSLMODE environment variable to 'require' in the ledgersmb.conf. Note that by default, LedgerSMB will try to connect to PostgreSQL via SSL and fall back to unsecured connections if this is not available.

We highly recommend using SSL for any access to LedgerSMB over the network.

Adding support for other database management systems would require that the database logic be coded to the least common denominator. We have decided that we want to eventually allow add-ons in different languages, and thus the database becomes the only point where we can enforce accounting logic consistantly across all parts of the application. Porting and maintaining such logic across database systems is not feasible for this project.

Additionally PostgreSQL is an outstanding RDBMS and we have no desire to move from it.

The table below lists the compatibility of LedgerSMB versions with PostgreSQL versions. Products for which support has ceased due to End-of-Life date being reached are not listed and should not be used.

Versions 1.8 and earlier are not in this table due to the fact that they're past End of Life.

We don't know enough about the ideosyncracies with your laws to evaluate that. But quite frankly Free Software sometimes poses an issue with local regulation. If you go with LedgerSMB, I'd recommend working with us to detail any shortcomings and get those resolved.

You can help us to make a list over "X country" laws and LedgerSMB shortcomings according your countrys law.

Getting all the development dependencies and a working copy for LedgerSMB can be time consuming and complex. However, using our Docker Compose infrastructure reduces this to four simple steps:

1. Install Docker
2. Install Docker Compose
3. Clone the LedgerSMB repository from GitHub
4. Clone the LedgerSMB Development Docker repository from GitHub

(And start the infrastructure from the docker compose file.)

Example

The example below works on Debian Stretch:

Install Docker

$ sudo apt-get install \
     apt-transport-https \
     ca-certificates \
     curl \
     gnupg2 \
     software-properties-common
$ curl -fsSL https://download.docker.com/linux/$(. /etc/os-release; echo "$ID")/gpg | sudo apt-key add -
$ sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/$(. /etc/os-release; echo "$ID") \
   $(lsb_release -cs) \
   stable"
$ sudo apt-get update
$ sudo apt-get install docker-ce

Install Docker Compose

Check the latest release at https://github.com/docker/compose/releases/ (and replace 1.17.0 with it)

$ sudo curl -L https://github.com/docker/compose/releases/download/1.17.0/docker-compose-`uname -s`-`uname -m` \
            -o /usr/local/bin/docker-compose
$ sudo chmod +x /usr/local/bin/docker-compose

Install docker compose bash completion (optional)

$ sudo curl -L https://raw.githubusercontent.com/docker/compose/1.17.0/contrib/completion/bash/docker-compose \
              -o /etc/bash_completion.d/docker-compose

Clone the LedgerSMB repository from GitHub (checks out 'master' branch)

$ git clone https://github.com/ledgersmb/LedgerSMB.git ledgersmb
# and, for 1.8 or earlier, additionally:
$ cd ledgersmb && git submodule update --init --recursive && cd ..

Clone the LedgerSMB Development Docker repository from GitHub

$ git clone https://github.com/ledgersmb/ledgersmb-dev-docker.git lsmb-dev-docker

At this point you are set up to start developing and testing LedgerSMB; in order to test your changes in a running LedgerSMB instance, run:

$ cd ledgersmb
$ ../lsmb-dev-docker/lsmb-dev master up -d

This command starts the container infrastructure (using the names "ldmaster-lsmb", "ldmaster-proxy" and "ldmaster-db" for the LedgerSMB, NGinx and PostgreSQL containers respectively), taking the sources in the current directory (ledgersmb) to run the application. It also starts a Selenium grid to allow browser tests.

Notes

File permissions

You may run into problems with file permissions if you want to run commands inside the containers which try to modify your local repository. You will need to either recursively set the file ownership to this user in your local tree, assign liberal 0777 (directory) and 0666 (file) permissions or execute the commands inside the container as root.

Example using www-data user, after you fix your file permissions:

docker exec -ti ldmaster-lsmb bash
www-data@90451823cb57:/srv/ledgersmb$ make dojo

Example using root inside the container:

docker exec -ti --user=root ldmaster-lsmb bash

Cache issues

The container is set up with template caching enabled. This means that you'll need to restart the container after code changes to see them. This is a simple:

$ ../lsmb-dev-docker/lsmb-dev master restart

Supported versions

The development container infrastructure only supports development of 1.5 and never versions of LedgerSMB.

Enjoy!

The best way to get (free) help is to join one of the LedgerSMB mailing lists or browse the mailing list archives for past advice:

Announcements List

https://lists.ledgersmb.org/postorius/lists/announce.lists.ledgersmb.org/

User List

https://lists.ledgersmb.org/postorius/lists/users.lists.ledgersmb.org/

Developer List

https://lists.ledgersmb.org/postorius/lists/devel.lists.ledgersmb.org/

 

 

 

 

SVN commits List (not used since the shift to github)

http://archive.ledgersmb.org/ledger-smb-commits/threads.html

# diff -u "original file" "new edited file" > “diff file”

Submit your patches ( “diff file” through the Sourceforge project tracker. If you are going to do somewhat largish changes, it's best to discuss how to do them on the developers list. That increases chances for acceptance which is in general the best solution for you and the lsmb community.

The LedgerSMB community follows the Ubuntu Code of Conduct.

Assuming you have followed the How Do I Backup My Data instructions, you can restore your database as follows...

Note LedgerSMB versions prior to version 1.9.16 did not support PostgreSQL 14 or higher due to a backward incompatible change in PostgreSQL 14.

Note that the following examples use the  'lsmb_dbadmin' for the database administrative user. Recent LedgerSMB installs do not automatically create an 'lsmb_dbadmin' user.  This has to be created manually.  You may have to use the 'postgres' user depending on how your database was installed.

1) Restore the roles

$ psql -h [database host] -U [database admin user] < [roles backup file]

For example:

$ psql -h localhost -U lsmb_dbadmin < lsmb-roles.sqlc

2) Create a new database to restore into

$ psql -h [database host] -U [database admin user] -c 'CREATE DATABASE [new company name]'

For example:

$ psql -h localhost -U lsmb_dbadmin -c 'CREATE DATABASE newcompany'

3) Restore the company backup into the new database:

$ psql -h [database host] -U [database admin user] [new company name] < [company backup file]

For example:

$ psql -h localhost -U lsmb_dbadmin newcompany < lsmb-db.sqlc

Log in to the the 'setup.pl' administrative interface, using your ledgersmb database admin user (usually "lsmb_dbadmin" or "postgres"). The default address for setup.pl is http://localhost/ledgersmb/setup.pl.

There are 2 buttons:

• Backup database (parts, customers, accounting records, etc)
• Backup roles (your login accounts and rights)

One creates a backup of the content of your database. The other creates a backup of the roles.

Roles are elements which are required to exist before creation of a database, and assign fine-grained access control.

Both files are needed when restoring, and you need to restore the roles before the database.

The backup can be mailed to an e-mail account, or you can download it with your browser, depending on your output selection in the backup screen.

After backing-up the data, it is prudent to confirm that the backups are of non-zero size to confirm that they have been correctly downloaded.

See How Do I Restore My Data for further information.

Overview

Company database upgrades are supported all the way back from 1.4 directly to 1.8, using the 1.8 software. Company database upgrades from 1.3 and 1.2 are also supported, but due to the different nature of the upgrade process are called "migrations". The important difference being that when doing a migration, a copy of the data is being created in the 1.8 structure, while upgrades adjust the existing structure for 1.8. When upgrading from versions earlier than 1.7, please read the release notes and upgrade instructions of those versions: those instructions still apply but are not repeated here.

Before starting, please remember:

• Create a backup
• Don't do this in a hurry
• When running into problems, check out the "Support" page

Technical upgrade

Upgrading the software works the same as with prior versions. Please refer to the procedure to upgrade a tarball installation for 1.7 for the 1.8 upgrade. Be sure to install the new Perl module dependencies listed in the Changelog. Also note that the Docker image definition contains a comprehensive list of Debian Buster package dependencies.

<Upgrading docker & docker compose to be written>

Company database upgrade

Technically, this process hasn't changed since 1.7 and the instructions for 1.7 still apply.

Each new LedgerSMB release has tightened the checks on validity of the data stored in the database. 1.8 continues on that path and adds yet more checks - this helps us find bugs and prevents undesirable data entering into the ledger. During the upgrade, existing data is checked against these new quality criteria and optionally offered for correction (or deletion, depending on the type of inconsistency).

Before you begin

• Verify that all Reconciliation Reports have been either approved or deleted
  If you forget this step, the migration will offer to delete it for you; approval isn't supported during migration. Note that this does not refer to transactions; unapproved transactions can safely exist during upgrade.
• Create a backup
• Tell users not to use your system during upgrade

After the upgrade

• Import the templates for PnL and Balance sheet
  Go through the menu System > Templates and either upload the various "PNL" and "balance_sheet" document formats or paste the source; you can find the template sources here: https://github.com/ledgersmb/LedgerSMB/tree/1.8/templates/demo (the TeX document to be processed by pdflatex) or here: https://github.com/ledgersmb/LedgerSMB/tree/1.8/templates/xedemo (the TeX document to be processed by xelatex)
• Assign the new role 'file upload' to administrator users
  Log into setup.pl in a company you want to change the access rights for; click "List users". From the list of users, select a user that you want to assign file upload rights (for the menu System > Files). Repeat for all relevant users.

There are two strategies in migrating your books to between accounting solutions in general:

1. Choose a cut-off point and migrate your balance sheet and income statement per that day as an opening balance
2. Migrate the complete history of the books from the old solution to the new one

These approaches apply even when the source is a spreadsheet (i.e. "manual") and LedgerSMB is the target. The second approach requires a full mapping of data from the source system to the target. This is usually quite involved and a reason not to use it. On the other hand, businesses are generally required to retain their records for a specific amount of time (multiple years, for audit purposes) and the second approach migrates the history-to-be-retained to the target system. With the first approach, a separate solution needs to be found to retain the required history.

Steps to migrate your opening balances into LedgerSMB

The goal of the migration is to "cut-over" accounting as per the chosen date. The general approach to that is to create an opening balance and opening income statement per that date and continue from there. Generally, a natural date to be chosen for such a cut-over is at the year-end when the income statement starts out clean for the year to come and an opening balance is created in the balance sheet.

The above works for relatively simple balance accounts such as a bank account or petty cash. When the account is a summary of underlying items, this approach is more problematic: in order to pay invoices, the system needs to know about them; migrating the total balance doesn't work well. The same applies to inventory where available inventory attributes to Cost Of Goods Sold (COGS) on a FIFO basis.

To construct a beginning balance with sufficient detail to support a complete cut-over, I have followed these steps:

1. Set up your chart of accounts
2. Migrate fixed assets
   1. Create the assets at their original value at the acquisition or depreciation start-date using their original depreciation scheme
   2. Run depreciation all at once on the day before migration resulting in the correct fixed asset account balance
3. Migrate inventory
   1. Identify when remaining stock was acquired (in order to initialize COGS)
   2. Set up "Goods & Services > Parts" for stock to be migrated
   3. Create an import file listing per day which items in stock were acquired and at what price
      • From the file above, exclude any stock from unpaid invoices; it will be added in the next step
      • Note that for assemblies "acquisition date" should be interpreted as "production date" -- the date the assembly was entered into inventory
   4. Import the file into the system (how)
4. Migrate open invoices
   1. Create customers and vendors at the bare minimum for which there are open invoices
   2. Create open sales and purchase invoices at their original creation dates
   3. Apply payments to the invoices on the original payment dates
5. Migrate the remaining balance
   1. Subtract the balances in the accounts in the new system from the balances to be migrated
   2. Create a GL transaction on the date before the cut-over with the calculated differences
   3. Post the GL transaction
   4. Verify the migrated numbers by running a balance sheet on the day before cut-over
   5. The numbers should be the same as those in the original balance
6. Freeze the migration balance to prevent hampering
   1. Go to "General Journal > Year End", tab "Close Period"
   2. Enter the date before the cut-over in "Close As-of"
   3. Click "Close Period"

Lets say that the cut-over date is "2020-01-01"; then the date to close the books at is "2019-12-31". After completing the procedure above, no transaction can be entered or modified before or at "2019-12-31", making this a truely static opening balance.

Upgrading tarball installations

There are two steps to upgrading a LedgerSMB 1.6.x installation to 1.6.y (x smaller than y):

1. Upgrade the software
2. Upgrade the company database

The last step has to be executed for each company database that's set up.

Note that all the steps below are prefixed with the 'sudo' command, but these can be executed as 'root' directly as well.

Upgrading the software

This is by far the easiest part. These are the steps to go through, 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.6.y.tar.gz --directory /usr/local
• Copy the configuration file from the old installation:
  $ sudo cp /usr/local/ledgersmb.backup/ledgersmb.conf /usr/local/ledgersmb/
• Start the LedgerSMB application server again (Starman example given, as before):
  $ sudo service starman-ledgersmb start

Upgrading the company database

After the software has been upgraded, the company database(s) have to be upgraded. When a user logs in on a database which is of a version different from the software that's used to access the database, a "Database version mismatch" error will be generated.

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, now you need to 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).

After login, setup.pl will show a sccreen with the following at the top:

 

Logged in as lsmb_dbadmin
LedgerSMB 1.6 db found
Rebuild/Upgrade?

By clicking the "Yes" button, the company database upgrade process will be executed.

Repeat this process for all company databases.

I had created a second database. To delete it, do I just drop the database from postgresql?

On a GNU-ish *nix platform use the script:
tools/delete-company-database.sh
it'll remove the roles and the database.

Sql ledger has the option to add a barcode to a part.

In 1.4, you will be able to add a barcode per make/model record.

How are barcodes added when using LedgerSMB?

Sort term solution:
It's not optimal for a UPC management but it solves the immediate problem:

Add a space separated list with the barcodes to the partnumber field

The partnumber is the "Number" filed on the same line as "Description" in the "Add Part" page.
And yes, "space separated list" works in the POS interface. (If you scan one of the codes in the space separated list )

Here's how the partnumber and description fields work
-----------------------------------------------------------------
It searches for any substring match for the entry.
If there is only one match it populates and moves on
If there are no matches it asks you if you want to create one
If there are multiple matches it gives you a list to choose from
same on the invoice screens

Long term solution:
------------------------
- add a UPC field to the makemodel table.

Question from: Tau (2009)

There are a number of possible causes for login problems. Some of the more common causes are:

Login in 1.3.x is new. Take a look at this screen guide:
http://www.ledgersmb.org/help/install/Ubuntu_Installation_Tutorial_Ledge...

Magic Characters in passwords:
The legacy code from SQL-Ledger has some issues with parsing passwords that contain either the equals sign ("=") or the ampersand (&). This is gradually being resolved in the LedgerSMB codebase but for now avoid using either of these characters in your passwords. The issue is that the equals and ampersand characters are used as delimiters in query strings and posted content - this is being worked on so should not be an issue "soon".

Googlebait: Symptoms of this include "Error! Cannot connect to datasource" and "no database driver specified and DBI_DSN env var not set at LedgerSMB/Form.pm" (suspect this is for admin password).

Browser plugin
The noscript Firefox plugin can prevent the Super-user login and Password box from being created. Disable noscript on your login page.

Password "popup"
Installed in a fresh install of Ubuntu. All seemed fine on in the evening when I went home for the weekend. (I was able to login) Now when I login I get an other password request popup opening with: A username and password are being requested by http://127.0.0.1. The site says: "LedgerSMB"

The likely issue here is that the initial password creation temporarily valid, with the idea that the individual setting the password may not be the application user. Consequently the password has expired and you cannot log in.

To solve the Password "popup", you can do one of a couple things:
By: Chris Travers

1) You can locate your pg_hba.conf file and change the authentication type to "trust" briefly while logging in and changing your password. This requires telling PostgreSQL to reload its files (or restarting PostgreSQL)

2) You can log into PostgreSQL with something like: sudo -u postgres psql and then change the expiration date. (on Centos or Red Hat su to the postgres user and run psql: su - postgres) Something like:

ALTER USER 'myusername' WITH VALID UNTIL '2011-11-09';

Then when you log in, you should be able to change your password under the preferences screen or if it will expire within a week, it should pop up that screen when you log in, with a warning on top.

PostgreSQL authorization settings (pg_hba.conf)
Read the "pg_hba.conf settings for production"
http://ledger-smb.svn.sourceforge.net/viewvc/ledger-smb/branches/1.3/INS...

The PostgreSQL doc about client authentication and pg_hba.conf
http://wiki.postgresql.org/wiki/Client_Authentication
https://www.postgresql.org/docs/8.4/static/auth-pg-hba-conf.html
https://www.postgresql.org/docs/9.2/static/auth-pg-hba-conf.html

Yes you can. In order to do so, you must first create a valid session for your follow-up requests by authenticating:

$ curl -c cookie-jar.txt -H 'Content-Type: application/json' \
    -d '{"login": "<your-user>", "password": "<your-password>", "company": "<your-company>"}' \
    https://example.org/login.pl?action=authenticate

The request above creates a file called "cookie-jar.txt" in the current directory which - after successful authentication - contains the authentication cookie to be used for follow-up requests. To use it, use curl's -b parameter:

$ curl -b cookie-jar.txt -c cookie-jar.txt -H 'Content-Type: application/json' \
    -d @request-body.json https://example.org/erp/api/v0/invoices/

Note that the use of curl's "-d" parameter implies that a POST request is issued. The presence of the at-sign in "@request-body.json" tells curl to read the request body from the file 'request-body.json'. When you decide not to use 'curl', but issue these requests from programming language, please make sure to issue POST requests.

OpenAPI documentation of the LedgerSMB API by version is available at https://docs.ledgersmb.org/openapi

No, there is currently no REST api; however, one is planned.

Other APIs are not available, except for the Perl APIs the application uses itself.

Not out of the box. However, community member John Locke (from Freelock Inc) is doing it using a custom integration. He doesn't mind sharing his code.

Yes.

LedgerSMB has a mechanism called "Account headings". The headings are the opposite of what Intuit explains about Quickbooks for their subaccount support: Quickbooks splits an account into multiple and aggregates those new accounts into the old one for reporting. To achieve the same in LedgerSMB, you create multiple accounts and one or more headings. LedgerSMB then aggregates the totals of the accounts per heading. The system used by LedgerSMB closely resembles what MYOB describes about their accounts and headers.

What you need to do is look for rows in payment_links which have type=0

Then, in acc_trans, you need to identify those rows which have an entry_id of a row which has a 0 amount. That row is probably an fx_transaction row.

The preceding entry_id row is likely one for the same transaction, with a non-zero, non-fx_transaction amount.

You need to insert a new row into the payment_links table with:

• payment_id: same as for the fx_transaction
• entry_id: entry_id of preceeding entry in acc_trans
• type: 0

When you do that, the customer balances should be fixed.

If you find yourself in this situation, the answer is to create a 0 (null) payment: Select both the voiding and the voided invoice in the Cash->Payment (or Cash->Receipt) screen. This will clear the invoices against each other with a net-zero result.

Unfortunately, the LedgerSMB 1.3 version doesn't automatically clear a voiding invoice against a voided invoice upon posting of the former. The workflow described works around this issue.

I have made a payment to a vendor, but entered an incorrect date, far in
the future. Consequently the payment does not show when I try to reconcile
the relevant bank statement.

How do I back-out the incorrectly entered payment?

Cash/Vouchers/Reverse Payment.

Then when you are done adding the payments you want to reverse,
approve the batch.

Tested on: LedgerSMB 1.3.15.
source: http://permalink.gmane.org/gmane.comp.finance.ledger.smb.user/6087

Short answer: Yes

LedgerSMB can tie product sales to a tax class so that VAT can automatically be split off into the required VAT accounts on a sale, and when cancelling an invoice, automatically perform the reverse bookings.

Each product can be 'attached' to an account and the associated % will be applied automatically.

Quite a few users find some of the terminology and accounting processes a little confusing at first. Some of the more popular small business accounting packages tend to hide these aspects of book-keeping from users for simplicity, so with the current user interface there is often some new ideas to grasp.

First step is the manual - the LedgerSMB manual is free and highly recommended reading.

If you would like some background on general accounting practices, there is an (unassociated) tutorial So, you want to learn Bookkeeping" which seems a good place to start.

Another excellent resource is second-hand book stores. Lots of MBA studends sell off their textbooks (presumably to finance their first business rather than pay of gambling debts) so second-hand bookstores will often have very good texts on accounting at bargain prices - these can make great reference books.

Finally it would be remiss not to recommend securing the services of an accountant to help you out with the finer points from time to time, should you feel the need or have a legal obligation to do so.

Wikipedia articles:
https://en.wikipedia.org/wiki/Accounting
https://en.wikipedia.org/wiki/Double-entry_bookkeeping_system
https://en.wikipedia.org/wiki/Accountant

Active support

Versions 1.10 and higher are under active development and are supported by the community. Planned end-of-life dates for current releases are:

• 1.11: Planned End-of-life date: 2025-10-03 (released 2023-10-03)

End of life

If you're looking for help on how to use EOL-ed versions, please try mailing the users mailing list.
If you're looking for someone to create bugfixes, please check with one of the parties providing commercial support or for less urgent fixes LedgerSMB Issues

Version 1.10 has been declared end-of-life on 2024-10-08. The last release in the series is 1.10.38. No futher releases will be made by the community.

Version 1.9 has been declared end-of-life on 2023-09-24. The last release in the series is 1.9.30. No futher releases will be made by the community.

Version 1.8 has been declared end-of-life on 2022-09-04. The last release in the series is 1.8.31. No futher releases will be made by the community.

Version 1.7 has been declared end-of-life on 2022-10-04. The last release in the series is 1.7.41. No further releases will be made by the community.

Version 1.6 has been declared end-of-life on 2021-06-10. The last release in the series is 1.6.33. No further releases will be made by the community.

Version 1.5 has been declared end-of-life on 2019-12-23. The last release in the series is 1.5.30. No further releases will be made by the community.

Version 1.4 has been declared end-fo-life on 2017-09-16. The last release in the series is 1.4.42. No further releases will be made by the community.

Version 1.3 has been declared end-of-life on 2015-12-23. The last release in the series is 1.3.47. No further releases will be made by the community.

LedgerSMB versions 1.0, 1.1 and 1.2 won't be maintained any further due to the fact that there are some known security issues which can't be fixed.

For real-time help try our Matrix (IRC like) room  #ledgersmb - you will usually find most of the core team hanging out there. The most feature-full and commonly used client is Element. It is available as a web client (for computers) and also as Android and iOS clients from within the appropriate app stores. We suggest you create a matrix account as that will allow you to log back in later to see our response to your question.

There are people there who range from users to developers who are willing to help. We have agreed to adopt the Ubuntu code of conduct for our community. Please read it if you plan on joining.

Please keep in mind that the community (especially the people you may need help from) are scattered around the world and will likely be in a different timezone to you. This means that it can sometimes take quite a few hours before someone responds. (although these days on IRC there is someone around almost all of the time). For email lists this is not a big problem, but if you are using Matrix (directly or via a matrix guest session) you will need to stay connected until someone answers otherwise we have no way to contact you :-)

If you ask for help as a signed up Matrix user, please log back in and check for a response occasionally, we will always respond as soon as someone is available.

NOTE: there is a nice feature of the Riot web app (a bell shaped icon near the top right) that shows all the messages that mention your name.
This is useful when you come back after a while to see if someone has responded to your question.
Just click on a message there to jump to that point in the chat history

Connecting to MATRIX

Read more about using Matrix  and Element Client

Webclient

You can use a browser-based matrix client to join the channel.
It defaults to guest access with reduced features, but it is trivial to sign up and get additional benefits like channel history and other things.

Dedicated Chat client

• Matrix Console for Android
• Matrix Console for iOS
• Other Matrix clients and plugins (eg: plugin for Weechat)

Is there a place where we could buy some consulting for LedgerSMB?
or a minimal setup according to our specs?

Take a look at Commercial Support