Combined Installation Instructions: Note: Some of these files have been edited. * README from /ledgersmb/doc/README with LSMB 1.2.18 * FAQ from /ledgersmb/doc/faq.html with LSMB 1.2.18 * INSTALL from /ledgersmb/INSTALL with LSMB 1.2.18 * README.OpenBSD from /ledgersmb/README.OpenBSD with LSMB 1.2.18 * README.debian from /ledgersmb/README.debian with LSMB 1.2.18 * README.debian from Debian pkg (Note: I have not checked this as of this update May 25, 2009) LedgerSMB Small Medium Business Accounting Version 1.2.18 DESCRIPTION: LedgerSMB is a double-entry accounting system written in perl. It has been tested with PostgreSQL, Apache, Netscape, Mozilla, Galeon, Explorer, Links, Lynx, Konqueror, Voyager, W3M and Opera clients on Linux, FreeBSD, Solaris, Windows, Mac computers and PDA's. Data is stored in a PostgreSQL database server, either locally or remote, the display is through a text or GUI web browser. The system is linked by a chart of accounts. All transactions for AR, AP and GL are stored in a transaction table. Hyper-links from the chart of accounts let you view transactions posted through AR, AP and GL. Configuration files let you specify to which SQL database server to connect to, personal preferences such as company name, language, number and date format, etc. With the admin script you can create, edit or delete users, create and delete datasets and set up the Chart of Accounts and templates needed for the system. You can have a group of users using the same dataset and templates for generating Invoices, Income Statements and Balance Sheets or a different set altogether. Templates are supplied in html, text and tex format to generate most of the forms. Forms can be printed to screen, sent to a printer or e-mailed. COPYRIGHT: Licensed under the terms of the GPL. LATEST VERSION: Available from www.ledgersmb.org PLATFORMS: Non-specific, see requirements. REQUIREMENTS: 1. Perl, 5.8.1+ 2. http server (Apache, NCSA, httpi, thttpd, ...) 3. SQL Server (PostgreSQL 8.0+) 4. DBD (DBD-Pg) 5. DBI 6. Locale::Maketext::Lexicon 0.56+ 7. LaTeX (optional) FOREIGN LANGUAGE SUPPORT: 28 languages are supported. Language files are ordinary text files, no special software is needed to change or add new translations. Some of the translation files are not 100% complete. If strings are missing, English is used instead. ====================================================================== INSTALLATION INSTRUCTIONS: ---------------------------------------------------------------------- DISTRO AND OS-SPECIFIC NOTES: ---------------------------------------------------------------------- OpenBSD users: Please see this document which describes all the steps needed to install LedgerSMB for OpenBSD. http://www.ledgersmb.info/OpenBSD_Install.html ---------------------------------------------------------------------- Ubuntu Server users: Please see this document which describes all the steps needed to install LedgerSMB for Ubuntu Server. http://www.ledgersmb.info/UbuntuServerInstall.html ---------------------------------------------------------------------- For Unix systems: '$' signifies the bash prompt, '=>' the psql prompt. Installing LedgerSMB 1.2 ---------------------------------------------------------------------- Debian users: Installation Notes Appendix for Debian In the dists/deb directory, there files which provide information on which prerequisites can be installed via apt-get and which ones need to be installed via CPAN. A simple way to do this is to: apt-get install `cat required_debs.txt` cpan > install Class::Std > install Config::Std LedgerSMB for Debian: LedgerSMB can be accessed at http://127.0.0.1/ledgersmb, although initial set up is required. To prepare LedgerSMB for use: 1) As the postgres user, create a database user for LedgerSMB authentication $ createuser --no-superuser --createdb --no-createrole \ -U postgres --pwprompt --encrypted ledgersmb Here it will prompt twice for the ledgersmb postgres user password, remember what you enter here for step 5. 2) Create postgres database for ledgersmb $ createdb -U ledgersmb -O ledgersmb -E UNICODE ledgersmb $ createlang plpgsql -U postgres ledgersmb 3) Add databases for all datasets which you want to have available For instance, we want a dataset for each of examplecom, exampleorg and examplenet, so... $ createdb -T ledgersmb examplecom $ createdb -T ledgersmb exampleorg $ createdb -T ledgersmb examplenet 4) Populate the user database and set an admin password (this admin password will be used to log into the administrative interface). $ psql -U ledgersmb -d ledgersmb -f \ /usr/share/ledgersmb/sql/Pg-central.sql $ psql -U ledgersmb -d ledgersmb ledgersmb=> UPDATE users_conf SET password = \ md5('admin-password) WHERE id = 1; 5) Edit /etc/ledgersmb/ledgersmb.conf Scroll down to the very bottom and check your database settings, they will need to be changed. Insert the ledgersmb postgres user password you used in step 1. 6) Edit /etc/postgresql/8.x/main/pg_hba.conf so that ledgersmb user may connect. Depending on your security infrastructure you can use the METHOD md5 or trust. Reload postgres so your changes take effect. 7) Configure apache2 Check /etc/ledgersmb/ledgersmb-httpd.conf and see if it is what you want - it will usually be fine just the way it is. The default configuration will make this accessible to everyone who can get to your ip address on port 80. If you want to lock it down to localhost, do so now in the forementioned configuration file! $ cd /etc/apache2/conf.d/ $ ln -s ../../ledgersmb/ledgersmb-httpd.conf 8) Reload apache2 $ /etc/init.d/apache2 reload At this point you can connect to http://127.0.0.1/ledgersmb/admin.pl and login with the password set in step 4. If upgrading from LedgerSMB < 1.2.0-rc5, you need to edit /etc/ledgersmb/ledgersmb.conf to adjust your configuration to match the new options and renaming. If upgrading from LedgerSMB < 1.2.0-beta1 or from SQL-Ledger, read UPGRADE. The config format, locale names, database schema, and per-user configuration locations have been sufficiently changed with 1.2.0-beta1 so as to require special attention in upgrading. -- Elizabeth Krumbach Tue, 6 Jan 2009 05:38:48 -0500 ---------------------------------------------------------------------- This document contains information on how to install LedgerSMB. We recommend that the reader start by reading the section on manual installation and then start by trying the automated means mentioned later. Also this document assumes that the reader is already familiar with the release notes. If you have not already done so, please read the release_notes file in the doc/ directory. ---------------------------------------------------------------------- MANUAL INSTALL: 1. Untar in desired location (for example, /usr/local/ledgersmb, refered to as LEDGERPATH for the remainder of this INSTALL file). LedgerSMB files should be owned by the apache user, apache:apache on many, but not all, systems. 2. Create a postgresql admin database role, by convention named 'ledgersmb': $ createuser --no-superuser --createdb --no-createrole -U \ postgres --pwprompt --encrypted ledgersmb (\ is a bash line continuation character, this is a single command) The prompted password (referred to as ledgersmb-user-password) will later be used in the DBConnect: string in the configuration file 'ledgersmb.conf' If you prefer to work in postgresql's psql console, the equivalent SQL statement to create the ledgersmb role is: => CREATE ROLE ledgersmb LOGIN PASSWORD 'ledgersmb-user-password' \ NOINHERIT CREATEDB; Further commands and database interaction should be conducted using the new LedgerSMB admin role 'ledgersmb'. 3. Create a central user database, owned by the LedgerSMB admin role, 'ledgersmb': $ createdb -U ledgersmb -O ledgersmb ledgersmb The equivalent SQL statement is: => CREATE DATABASE ledgersmb WITH ENCODING='SQL_ASCII' \ OWNER=ledgersmb; 4. On the database that will store your user and session information, run the included Pg-central.sql SQL commands to configure the user and session tables and functions: $ psql -U ledgersmb -d ledgersmb -f LEDGERPATH/sql/Pg-central.sql (LEDGERPATH is in the location you expanded the release tarball file. If you untarred in '/usr/local' then LEDGERPATH will be '/usr/local/ledgersmb'). NOTE: LedgerSMB's preferred configuration is to store the user and session management tables in a separate database from the company databases (aka 'datasets', created in admin.pl). If you are already working with or prefer to have your user and session tables in one company dataset, see further information in the manual. You must have PLPGSQL installed in the dataset as well. However that is beyond the scope of these instructions. 5. The SQL commands in step 4) created an LedgerSMB-managed admin user, e.g. a row in the users and users_conf table. You must now update the 'admin' user's password in users_conf from the default password. $ psql -U ledgersmb -d ledgersmb ledgersmb=> UPDATE users_conf SET password = \ md5('ledgersmb-user-password') WHERE id = 1; (Change ledgersmb-user-password to your preferred administrative password, which is separate, but can be the same spelling as postgres-password). ledgersmb=> \q 6. Edit the LEDGERPATH/ledgersmb.conf file: * Copy 'ledgersmb.conf.default' to 'ledgersmb.conf' * Make sure to set the section under [globaldb] to point to the central user and session database, using password postgres-password: [globaldb] DBname = ledgersmb DBhost = localhost DBport = 5432 DBUserName = ledgersmb DBPassword = ledgersmb-user-password 7. Add configuration to Apache: $ sh configure_apache.sh 8. Check Dependencies: The Build.PL script can be used to test for unmet dependencies and run other tests. It doesn't install anything yet, but it will tell you what you are missing. To check for dependencies, run: $ perl Build.PL Missing dependencies can generally be installed via a Linux distribution's package manager, or by CPAN. (Build.PL itself uses Module::Build, which is available in packages like perl-Module-Build or libmodule-build-perl.) Once this is done and dependencies are satisfied, you can check to see whether the installation nominally works by running: $ ./Build test The test suites currently check to make sure all the perl modules load and that a number of numeric tests are passed. Dependencies which are recommended are needed only for specific functionality and may not be required in all circumstances. These include: * Net::TCLink for credit card processing in a POS environment * Parse::RecDescent for the CLI script host 9. Restart Apache (instructions vary with your Linux distro or operating system). ---------------------------------- Create Datasets and Users 1. Create Datasets: Browse to: http://'insert-your-hostname'/ledgersmb/admin.pl login with 'ledgersmb-user-password' Select 'Pg Database Administration' Button Create dataset(s) with: User: ledgersmb Password: ledgersmb-user-password Superuser: postgres Password: (postgres-password) Create one dataset (a postgresql datatabase) for each separate company which will use LedgerSMB for accounting, e.g.: ledgeracme ledgerbigco (...) 2. Create User(s) pointing to specific datasets (companies from above): Browse to: http://'insert-your-hostname'/ledgersmb/admin.pl login with 'ledgersmb-user-password' Select 'Add User' Button Create User(s) pointing to a specific dataset (ledgeracme, etc.), each with their own password 'user-password', with database login information: User: ledgersmb Password: ledgersmb-user-password User: johndoe Password: johndoe-user-password Congratulations, you have installed and configured LedgerSMB 1.2 ---------------------------------------------------------------------- Load the Accounting Program Browse to: http://'insert-your-hostname'/ledgersmb/login.pl Enter a User Name and Password (This time you won't be using postgres or ledgersmb, but one of the created users.) User: johndoe Password: johndoe-user-password Good Luck!! Enjoy!! ====================================================================== FTP INSTALLATION If you control the server and have shell access, the instructions above are preferred over those given here. instead of those given here. This is simply a set of notes for those who must install on a shared server. If you do not have access to the server's configuration files install LedgerSMB in userspace by ftp'ing all the files to your server. 1. Untar ledgersmb in your private_html directory. 2. turn on script execution for the folder ledgersmb. You can control this with an .htaccess file: Options +ExecCGI DirectoryIndex login.pl 3. Protect the users directory with an .htpasswd file: order allow,deny deny from all 4. Protect the templates directory with an .htpasswd file: order allow,deny deny from all 5. Set up your PostgreSQL database and the tables. The procedure is specified above. You will most likely only have access to PostgreSQL with some other tools like pgadmin. OTHER ISSUES: Before submitting a bug, please consult the COMPATABILITY list. This documents which versions of software have known interoperability problems with LedgerSMB. SET UP A USER: 1. Load your web browser and connect to http://localhost/ledgersmb/admin.pl 2. Click on "Add User". In the Database section select the driver and enter the user you used to create the dataset. ====================================================================== LOAD THE ACCOUNTING PROGRAM: Load your web browser and connect to http://localhost/ledgersmb/login.pl INSTALLATION CHECKLIST: 1. Untar LedgerSMB somewhere (i.e /usr/local, /opt) 2. Change permission for the users, templates, css and spool directory 3. Edit httpd.conf 4. Edit ledgersmb.conf 5. Add the database user ledgersmb 6. Load admin.pl 7. Create datasets for companies 8. Add users In the Database section enter a) PostgreSQL Host: for local connections leave blank Dataset: the dataset created in step 7 Port: for local connections leave blank User: ledgersmb Password: 'ledgersmb-user-password' IF SOMETHING DOESN'T WORK: * IRC Support For real-time help try IRC - you will usually find most of the core team hanging out at irc.freenode.net / #ledgersmb * There are also several mailing lists at http://www.ledgersmb.org where you can seek free help. * For commercial support see http://www.ledgersmb.org/ TROUBLESHOOTING: Error: Access Denied in admin.pl Likely causes: 1. The password entered may not match the password set in Manual Install, step 5. You can repreat that step as often as you need to get login to admin.pl working, but in case your 'admin' user is not id=1, try using the expanded version of the SQL: ledgersmb==> UPDATE users_conf SET \ password=md5('ledgersmb-user-password') WHERE id = (SELECT id FROM \ user WHERE username = 'admin'); (\ is a bash line continuation character, this is a single command) (Substitute 'ledgersmb-user-password' for your chosen password). 2. The central database may have been created with a different postgres user (role) than you are using for the connection. In this case, you may not have permission to access the required database entities. To correct this, assuming that the admin database role is ledgersmb, issue the following commands from psql: ledgersmb==> GRANT ALL ON users TO ledgersmb; ledgersmb==> GRANT ALL ON users_id_seq TO ledgersmb; ledgersmb==> GRANT ALL ON users_conf TO ledgersmb; ledgersmb==> GRANT ALL ON session TO ledgersmb; ledgersmb==> GRANT ALL ON session_session_id_seq TO ledgersmb; Error: "No GlobalDBH Configured or Could not Connect" LedgerSMB 1.2 uses a dedicated connection to the central database for user authentication. When the attempt to connect to that database fails, the error message above is displayed. In this case, check the following parameters under the [globaldbh] of the ledgersmb.conf file. 1. DBUserName should match the database user you imported Pg-central as (if you followed the instructions above, that would be ledgersmb). 2. DBPassword needs to match the database password to used to connect to. You can test the above causes by running (from the command line): $ psql -U [DBUserName] password: [DBPassword] When you enter the password, it will not show up on the screen. 3. The other line that you should pay attention to is the DBConnect line. Parameters in the form of name=value need to match those for your host. The following parameters need to be set correctly in that line: dbname=ledgersmb (the database you imported Pg-Central.sql into). host=localhost (don't change unless you know what you are doing!) port=5432 (don't change unless you know what you are doing!) The full line should then be something like: DBConnect: dbi:Pg:dbname=ledgersmb;host=localhost;port=5432 And that section of ledgersmb.conf looks like: [globaldb] DBname = ledgersmb DBhost = localhost DBport = 5432 DBUserName = ledgersmb DBPassword = ledgersmb-user-password ====================================================================== FAQ (Frequently Asked Questions) * Printing to a Printer from a Windows Server There are several obstacles to printing from a web appliction that was written for Linux or UNIX in Windows. These include: - Lack of Postscript support in the printing subsystem. To resolve this, you must install Ghostscript and Gsview. The latter package provides a utility called gsprint that will allow you to print Postscript on your Windows printer. - The fact that most Windows software, including gsprint, tends to print output that will cause the web server to crash. The winprint.bat included with this distribution corrects this problem. To use the winprint.bat solution, configure your printers in your ledger-smb.conf as "winprint.bat printer-name." If you omit the printer name, the default printer will be used. - Windows does not allow you to set up system printers that all users can access. Thus the web server often doesn't have access to the printers you have set up. To correct this issue, follow the steps at http://support.microsoft.com/kb/q184291/. * Error on converting from SQL-Ledger: ERROR: column "chart_id" contains null values SQL-Ledger does not enforce a NOT NULL constraint on the chart_id field in the acc_trans table. Consequently, it is possible in certain circumstances to insert transactions into the database with invalid information including NULL chart_id's. When this occurs, normally the Chart of Accounts and Trial Balance will fail to balance. So this is a serious problem with data integrity. LedgerSMB prevents this by adding the NOT NULL constraing but this can cause prevent people from migrating when they have invalid data in their databases. If you encounter an error like this, the first thing to do is seek technical support, regardless of whether or not you wish to continue the migration. In general the providers of support for LedgerSMB and SQL-Ledger should all be able to be of some assistance. Unfortunately, since this problem involves information loss, no solution can be automated without invalidating your accounting information. * SELinux http://docs.fedoraproject.org/selinux-faq-fc3/index.html modify /etc/selinux/conf and set SELINUX=permissive use audit2allow, add the following to policy.conf, then run make reload #line 83 allow httpd_sys_script_t port_type:{ tcp_socket udp_socket } \ {send_msg recv_msg }; allow httpd_sys_script_t sysctl_kernel_t:dir search; allow httpd_sys_script_t sysctl_t:dir search; allow httpd_sys_script_t tmp_t:sock_file write; allow httpd_sys_script_t httpd_sys_content_t:lnk_file read; allow httpd_sys_script_t sysctl_kernel_t:file read; allow httpd_sys_script_t unconfined_t:unix_stream_socket connectto; * lineitems not printing Templates designed on a UNIX platform don't work on a DOS platform. To make them work load the template either with the builtin template editor or a text editor and save. Templates designed on a Windows platform have the same problem and won't work on a UNIX platform. Once you strip the ^M's the'll work just fine. Note too that most Linux and UNIX installations come with two utilities for making these conversions: unix2dos and dos2unix. Windows users can obtain these utilities as part of Cygwin. * characterset problems If you have problems displaying the correct characterset try adding AddDefaultCharset On in your httpd.conf file. * cannot create function Run: createlang -U postgres plpgsql ledgersmb to install the plpgsql language handler into the "ledgersmb" database. More information on this utility can be found at the interactive documentation at the PostgreSQL site. * IDENT Authentication failed for user "ledger-smb" Edit pg_hba.conf and change authentication to local all all md5 host all all 127.0.0.1/32 md5 The file is often in the 'data' directory of your postgresql installation. In some distributions it may be in /etc/pgsql or a similar directory. A file search can be helpful when all else fails. # find / -name 'pg_hba.conf' WARNING! DO NOT just put a 'host all all trust' in pg_hba.conf unless you know what you are doing; that can introduce a pretty huge security hole. * LaTeX templates If you don't want to edit tex code by hand, you could use Lyx, Abiword, or any WYSIWYG editor capable of exporting latex code. LaTeX is somewhat complex to learn, initially, but offers a much superior environment to produce professional-looking forms in postscript and PDF format. * Use without Frames To use without frames, add ?path=/bin/lynx to the login URL: http://localhost/ledger-smb/login.pl?path=/bin/lynx * PDF option disappeared Edit ledgersmb.conf and set: latex = 1 * printing to a printer Printers are defined in ledgersmb.conf [printers] Default = lpr Color = lpr -PEpson Check in your /etc/printcap file for the names of available printers. If you have LaTeX installed set: latex = 1 in ledger-smb.conf Note: html data entry format is for screen preview. Use the "Print" option from your browser to print to a printer. * beginning balances Add a GL Journal entry and enter the beginning balance for your accounts. Beginning balances are the balances from your last balance sheet. If you also add open invoices to account for COGS for inventory, add the invoices and make the appropriate adjustments. * establish a beginning inventory add the parts with a vendor invoice. Use the real cost for the items, not zero. If you use zero cost then the cost of goods will be zero when you sell the item. * Assemblies Assemblies are manufactured goods assembled from parts, services and assemblies. Because you do not buy assemblies you 'stock assemblies' by adding assembled units to your inventory. The quantity for individual parts is reduced and the quantity for the assembly increased. To disassemble an assembly you simply return the parts to inventory by entering a negative quantity for the number of assemblies to stock. * DBD-Pg not installed Most modern distributions now package DBD-Pg. If it is not packaged follow this recipe to get it working. - check if you have the header files for PostgreSQL $ find / -name 'libpq-fe.h' if nothing shows up install the development package for PostgreSQL - download and untar DBD-Pg - set the environment variables POSTGRES_LIB and POSTGRES_INCLUDE - cd to DBD-Pg directory as ordinary user $ perl Makefile.PL $ make $ make test if all went well su to root # make install - remove the DBD-Pg directory * script not executing, shows in browser instead Add AddHandler cgi-script .pl in your httpd.conf file. * switch display to a foreign language Load your preferences and select the language. Language selection is in accordance to ISO 3166-1 standards. * Text shows in English when I use a foreign language This is because the corresponding entry in the .po file. Add the missing text the appropriate .po * switch to a foreign language for the login and admin screen Edit ledger-smb.conf and enter the code for the $language variable language = "de" This is a global change and applies to all logins, individual settings may be changed by setting the language in your Preferences. ====================================================================== LedgerSMB security Typical setups: /usr/local/vh/www <- DocumentRoot for virtual host /usr/local/vh/ledger-smb <- Alias for ledger-smb /usr/local/vh/users <- users directory out of reach /usr/local/vh/www <- DocumentRoot for virtual host /usr/local/vh/www/ledger-smb <- Alias for ledger-smb /usr/local/vh/www/ledger-smb/users <- users configuration files and tmp space Order Deny,Allow <- disable webserver Deny from All access for users directory The location for the users directory can be specified in ledger-smb.conf * Set permission for the users and templates directory to 711 * If you do not want anyone to change the templates with the built-in editor set the files in templates/directory/ to read only or disable the menu item to edit the templates. * You can set up a read-only environment if you disable the menu items to add data. i.e 'Add Transaction' if unchecked you will not be able to add a transaction or repost a transaction. You may look at it but nothing else. * There are various settings for audit control and you may disable reposting entirely or up to a certain date. And with the audit trail enabled you can keep tab of who is doing what. * For PostgreSQL you may also set who has access to the server in the file pg_hba.conf * In addition you can secure the tables from unauthorized access by setting up a different database user and GRANT rights. For instance, users without DELETE rights will still be able to use the program, change customers and vendors, add transactions but will not be able to delete or repost transactions. To lock all the tables to create a RO system GRANT SELECT rights only. * Other security options include a secure shell, your webserver's authentication system, SSL, encrypted tunnels, ... Last Updated May 28, 2009