Building and maintaining customized versions of OpenPetra

see also Customizing OpenPetra

Purpose

Every organisation is different, so there cannot be one OpenPetra installation for all. It might work for smaller charities, for one country, but for bigger offices the default version of OpenPetra is not sufficient.

There must be a standard way to accomplish this, which will ensure that updates from upstream can be used in the customized version, and local improvements can be merged back into upstream if they would benefit other organisations as well.

It can also be helpful for a developer, to make adjustments to config files for his own development. For more notes on this, see Specifying custom settings in Config Files for Development

Rules

• Never change a code file directly
• Changes to the code that benefit everyone must be merged upstream
• Custom files must be clearly identifiable, either by a special sub directory called "custom", or by file extension ".my"
• .config files are never committed to the source code repository.
• If a .my file exists, then it will be used, instead of the .config file.

Customizing files

Build files

• The default values for configuration can be found in inc\nant\OpenPetra.common.xml
• You can create the file OpenPetra.build.config in the root directory, beside OpenPetra.build, and that file is not committed to the repository, since every developer will have different settings in that file.
  • see also User defined configuration parameters with OpenPetra.build.config
• For a defined environment in an organisation or if the repository is only used by one developer, you can commit the file OpenPetra.build.config.my to your local repository, which would be picked up instead of OpenPetra.build.config.

Configuration files

Execute debug version by developer

• There are sample files which are located in the inc/template/etc directory, eg. inc/template/etc/Client.config
  • You can add your own customised files with the name Client.config.my etc to the directory inc/template/etc. This will be used when running e.g. nant startPetraClient.
  • You can add your own customised files with the name Server-*.config.my (e.g. Server-postgresql.config.my) etc to the directory inc/template/etc. This will be used when running e.g. nant startPetraServer.
    • Important: When you want to debug the client you will need to use special server configuration settings. Refer to this [Forum Post] for this.

Configuration files for the installer

• The default configuration files are stored in the files setup\petra0300\remoteclientWin\PetraClientRemote.config and setup\petra0300\linuxserver\PetraServerConsole-mysql.config.
• Most server specific settings (port, URLs etc) should be set when building the installer, and can be defined as parameters on the command line.
• Some customization might be necessary for configuring plugins, eg. for authentication.
• Customized configuration files should be stored in the file PetraClientRemote.config.my or PetraServerConsole.config.my, and will be picked up by the nant tasks which build the installers.

Navigation files

• the default navigation file is csharp\ICT\Petra\Definitions\UINavigation.yml
• Currently, if there is a navigation file UINavigation.yml.my, the installers will use that file instead of the default UINavigation.yml file.
• In the future, it should be possible to derive from UINavigation.yml and to specify only changes to that file, both additions and omissions.

Translation files

• Translation files are stored in the directory i18n, eg. de-DE.po
• Texts can be overwritten to reflect the use of organisation specific terms. Such files with only the different texts are stored in eg. i18n\de-DE.po.my
• When running nant translationCompilePOFile, all language files (*.po) in i18n will be converted to a GNU Gettext resource dll, and the contents of *.po.my files will overwrite the specified texts per language.

Plugins

TODO

Report Parameter/Settings

TODO

Custom Reports

TODO

Changes to the UI dialogs

TODO

Building a release

• TODO build a release for server

nant buildReleaseLinuxServer -D:ReleaseID=0.2.3.0 -D:OrgName="Sample Charity" -D:ServerPort=3000

• • for an update, you don't need the database files and config files anymore

nant buildUpdateLinuxServer -D:ReleaseID=0.2.3.0
on the server you need to update the database:
sudo -u postgres psql openpetra -c "UPDATE s_system_defaults SET s_default_value_c = '0.2.3-0' WHERE s_default_code_c = 'CurrentDatabaseVersion'"

• TODO build a release for client

nant buildReleaseWindowsClient -D:ReleaseID=0.2.3.0 -D:OrgName="Sample Charity" -D:PublisherUrl=www.openpetra.com -D:ServerHost=www.openpetra.com -D:ServerPort=3000
This will create files in the "delivery" directory which are useful for setting up the database on the server, and the initial config files for the server

• TODO archive tar.gz file for building future patches
• TODO build a patch for the client