5.1 Using setup.pl

Jack installed LedgerSMB using the default installation instructions, which means the url for his setup.pl is https://example.com/setup.pl. Figure 5.1 on page 5.1 shows the login screen for the tool.

Please note that in version 1.7 and earlier you can’t be logged into the administration tool (setup.pl) and the webapp through the same browser at the same time due to limitations of the implementation.

The login screen shows three fields: (a) a user, (b) a password and (c) a database name.

The user name you use with setup.pl needs to be a PostgreSQL user. The user needs at least the right to create databases and other users; the postgres super user has these rights and more, so it’s generally convenient (but not very secure) to use it.

The password must be the same as that used to log in from the command line using the psql tool or the password you assigned on user creation using the createuser tool ²² 2 Most PostgreSQL deployments need configuration changes for this to work, if you’re installing LedgerSMB yourself. See https://ledgersmb.org for installation instructions.. Both psql and createuser are PostgreSQL tools (not LedgerSMB tools).

The third field is the name of the company database to be created. For practical reasons it’s best to use only lower case letters, numbers and the underscore (_).

The “Login” button is used when the company database already exists. The user can then perform some administrative tasks on the existing database.

The “Create” button is used to create a new company.

When creating a company database, there are a few things that are of importance:

• •

  The name of the company database will be used at login time and hence will be used by all users - a choice of recognizable value is important

• •

  The value entered (and hence the company name) is case-sensitive

• •

  The name can’t be more than 63 characters long

After choosing “example_inc” as his company name, Jack clicks “Create” to create the database and load it with LedgerSMB’s database schema, authorization rules and stored procedures³³ 3 Parts of the program inside the database.. It may take a while (30 seconds or more) for the next screen to appear⁴⁴ 4 Note that during the creation of the database, logs are kept so that in case of errors these can be reviewed either by the person running the installation or by support personnel. On Linux/Unix systems these are stored, by default, in the “/tmp/ledgersmb/” directory and named “dblog”, “dblog_stderr” and “dblog_stdout”.

After the delay the screen from Figure 5.2 on page 5.2 shows up.

LedgerSMB comes with numerous predefined charts of accounts. These have been grouped per country making the selection of a chart a two-step procedure. setup.pl allows for users wanting to define their own charts by offering a “Skip” button. This button skips the process of loading a chart.

Note that you need to define a chart of accounts before you can meaningfully do anything inside LedgerSMB. If you don’t load a pre-defined one you’ll need to create or upload your own from inside the application once setup has completed.

Figure 5.3 on page 5.3 shows the first screen in the CoA selection procedure. Here you select the country for which you want to use the CoA. Note that charts of accounts are highly country dependent and you may want to consult an accountant if no default chart of accounts is included for your country.

As Jack runs his company in the United States, that’s what he selects.

Figure 5.4 on page 5.4 shows the second screen in the chart of accounts selection procedure. The drop down contains a list of all charts of accounts defined for the selected country.

Jack selects the GeneralHierarchical.xml chart of accounts: that will leave him enough room to specialize the setup later if he has to, but for the time being offers a broadly usable setup.

LedgerSMB comes with a set of default reporting templates. These control the formatting of documents like invoices, checks, balance sheet, purchase orders, income statement, etc. Jack is now presented with the screen to load templates. LedgerSMB 1.11 comes with a single choice⁵⁵ 5 Administrators may define extra sets for users to be selected upon company creation; see 48.1:

• •

  demo – Example template set for various output formats including PDF, HTML and Excel

In the previous step, the technical part of the company creation procedure was completed. However, it’s not possible to log in to the company yet. Figure 5.5 on page 5.5 shows the next step in the setup process: the user creation screen. The fields shown have the same meaning as those discussed as part of user management in Section 24.2 on page 24.2.

Jack chooses to create an administrative user called admin who will be authorized to do everything in the application. Later on he will also create a user jack who will be authorized to do everything but changing the configuration and doing application administration. He’ll use the latter user to log in for day to day operations. This will help him prevent changing settings by accident.

Note that none of the fields in this screen are optional. If the name of the user being created isn’t already used with other companies, leave the Import option set to No, otherwise please read the chapter on user creation mentioned above.

Note: The password you enter here is a temporary one which will remain in effect for 24 hours only. Be sure to execute the steps in Section 6.2 on page 6.2 before these 24 hours elapse, because the user will be disabled after that.

Jack has created his company database and now sees the “Database Management Console” screen as shown in Figure 5.6 on page 5.6.

By selection Start using LedgerSMB in the “Database Operation Complete” section of the screen his story continues in the next chapter “The first login”.