summaryrefslogtreecommitdiff
path: root/UPGRADE
blob: de0592d5e6826f066c10700a4e6ceb8f6ae7adcb (plain)
  1. Upgrading to LedgerSMB 1.2
  2. From LedgerSMB (1.1.12 or earlier)
  3. or
  4. SQL-Ledger (2.6.27 or earlier)
  5. This document contains information on how to upgrade from earlier versions of
  6. LedgerSMB or SQL-Ledger. This upgrade is a major revision and may not go
  7. smoothly. We recommend that the reader start by reading the section on manual
  8. installation and then start by trying the automated means mentioned later.
  9. Also this document assumes that the reader is already familiar with the release
  10. notes. If you have not already done so, please read the release_notes file in
  11. the doc/ directory.
  12. Before you begin, make sure that you are running at least PostgreSQL 8.0. If
  13. you are running a prior version, you will need to dump your data, upgrade the
  14. database server and restore the data before proceeding.
  15. You may want to review the INSTALL file as well, as common troubleshooting
  16. information and more detail may be found there.
  17. MANUAL UPGRADE:
  18. ===============================================================================
  19. 1) Back up old installation
  20. THis is a major upgrade. If something goes wrong, you want to be able to get
  21. back to a known good state. To back up the old installation do as follows:
  22. a) Copy the LedgerSMB install directory (for example /usr/local/ledger-smb)
  23. to another location
  24. b) Back up the database using pg_dump or other PostgreSQL backup program.
  25. c) (optional) Make a live bakup of the accounting database by creating a new
  26. db with it as the template. Something like:
  27. createdb -U postgres -T ledgersmb accounting_backup
  28. 2) Check New Dependencies
  29. The Build.PL script can be used to test for unmet dependencies and run other
  30. tests. It doesn't install anything yet, but it will tell you what you are
  31. missing. To check for dependencies, run "perl Build.PL" from the command line.
  32. Missing dependencies can generally be installed via a Linux distributor's
  33. package manager or by CPAN.
  34. Once this is done and dependencies are satisfied, you can check to see whether
  35. the installation nominally works by running "./Build test" from the command
  36. line. The test suites currently check to make sure all the perl modules load
  37. and that a number of numeric tests are passed.
  38. Dependencies which are recommended are needed only for specific functionality
  39. and may not be required in all circumstances. These include:
  40. * Net::TCLink for credit card processing in a POS environment
  41. * Parse::RecDescent for the CLI script host
  42. 3) Upgrade database
  43. a) cd to the sql/legacy/ directory of the new ledger directory
  44. b) run "psql" with appropriate options to connect to your database.
  45. c) Note the db schema version by running the following query:
  46. "SELECT value from defaults where setting_key = 'version';" (1.2.0 or
  47. later)
  48. or
  49. "SELECT version FROM defaults;" (SQL-Ledger 2.6.x or LedgerSMB 1.1.x
  50. or earlier)
  51. d) Run the SQL upgrade scripts in order starting with the one whose name
  52. begins with "Pg-upgrade-[version]" (each of these scripts will upgrade to
  53. the next database version which is also identified in the file name).
  54. N.B.: use `ls -v` to see the scripts in version order and run them
  55. in the order shown by this command.
  56. e) If you have a problem running the scripts (errors due to ownership
  57. or you just want to change ownership of the tables), connect to the
  58. database as you did in c above and at the => prompt:
  59. "\d"
  60. You will see a list of all tables, sequences, triggers, etc. After
  61. creating a user (see the INSTALL file for details), you can change
  62. ownership of the relation by running the following at the => prompt:
  63. "ALTER TABLE|SEQUENCE|TRIGGER public.<relation_name> OWNER TO "new_owner";
  64. Select the appropriate relation type and relation_name.
  65. Rerun the upgrade scripts starting with the first one that failed.
  66. Note that subpara d above will create three tables that may not actually be
  67. used depending on your setup: users, users_conf, and session. In general if
  68. you have multiple datasets, these tables will only be used in one.
  69. 4) Decide where to put the user/session management tables. In general, we
  70. recommend as follows:
  71. a) Single dataset installations should use the user tables in the dataset.
  72. b) Multicompany installations should use user tables in a separate dataset
  73. from any accounting data.
  74. For a single dataset, just import sql/Pg-central.sql into your database.
  75. If you need to create another dataset, you can create the db and import the
  76. sql/Pg-central.sql file into it.
  77. 5) Set the admin password:
  78. a) From psql, determine what admin password you wish to use. Then type:
  79. "update users_conf set password = md5('my_password');"
  80. Naturally you would use your password instead of my_password.
  81. 6) Create ledgersmb.conf using appropriate values from the old ledger-smb.conf
  82. and connection data for the central authentication database.
  83. ledgersmb.conf.default can be used as a base.
  84. 7) Import the users. Run the import-members script to do this.
  85. 8) Copy the files from the LedgerSMB tarball over your existing installation.
  86. 9) Delete the users directory.
  87. 10) Upgrade your templates. Run the following command:
  88. perl upgrade_templates.pl $templatedir
  89. Where $templatedir is the directory of your templates.
  90. 11) You can test basic parts of the installation by running Build ./test at
  91. this point.
  92. Congratulations, you have manually upgraded to LedgerSMB 1.2.
  93. TODO: Add upgrade.pl script and automate the above process.