Building a Customized Workstation installer
From Giews
This is the Developers Guide to Building a Customized Workstation Installer. At the moment the script is working for Windows installer only. The Linux installer is still under development.
Reference:
- GIEWS_Workspace = C:\workspaces\giews_workstation
- GIEWS_Web = C:\workspaces\giews_workstation\giews-web
- Geonetwork_Web = C:\workspaces\giews_workstation\geonetwork-web
- Installer_Builder = C:\workspaces\ giews_workstation\giews-installer
- MYSQL_Directory = C:\Program Files\MySQL\MySQL Server 5.0
- Installer_Project_Code = the GAUL_code of country where the installer will be deployed (e.g. 103 for Guatemala)
- Project_Codes = GAUL_codes of projects included in the installer (Note that some installer may contain the Country and Region projects)
- Customization_Directory = {Installer_Builder}\customization\
- Customization_Code = ISO3_CODE (if exists) or Installer_Project_Code (e.g. ETH for Ethiopia, 9999 for Palestine)
- Country_Name = English label of the country where the installer will be deployed
[edit] Preparing the Development Environment
1. Setting Eclipse:
- Download Eclipse Web Tools Project 2.0.1 http://www.eclipse.org/webtools/releases/2.0.1/
- Or, if you can access the S-drive, use S:\GIEWS-Workstation3.0\tools\eclipseWTP201.zip
- Set up Eclipse Plugins. If you used the installer on the S-drive you don't have to add the updates. Otherwise: Open Eclipse. Go to Help/Software Updates/Find and Install/Search for new features to install. Click on the button import and import this xml below.
<?xml version="1.0" encoding="UTF-8"?>
<bookmarks>
<site name="subversion" url="http://www.polarion.org/projects/subversive/download/1.1/update-site" web="false" selected="true" local="false" />
<site name="Web Tools Platform (WTP) Updates" url="http://download.eclipse.org/webtools/updates" web="false" selected="false" local="false" />
</bookmarks>
- Make sure to setup Server Runtime by checking Window.. Preferences.. Server.. Installed Runtime.. Add.. Apache.. Apache Tomcat 5.5.
- Make sure to select JDK 1.5 by checking Window.. Preferences.. Java.. Installed JREs.
2. Setting the Workspace:
- File.. Switch workspace.. Other.. {GIEWS_Workspace}
3. Setting the Eclipse Projects:
- File... New -> Other...
- Choose SVN folder -> select project from SVN
- Click Next button
- URL: https://giews.svn.sourceforge.net/svnroot/giews/gw_kids
- Authentication: (your username and password for SourceForge account) (save password if you want)
- The client will try to connect to the server
- Choose "trunk" folder.
- Checkout the projects giews-web, geonetwork-web, giews-installer
- Checkout as following repository resources as projects
- Click Finish button (This may take at least 20 minutes)
- Build project giews-web. This will update the WebContent/WEB-INF/classes files.
- At the moment none of the projects are checked-in to SVN because the files are too heavy. Copy World project from \\lprapp08\tomcat_GIEWS\webapps\GIEWS_KIDS\WEB-INF\projects\0 to your local {GIEWS_Web}/WebContent/WEB-INF/projects
- Make sure to define the correct <Context> in Tomcat's server.xml
[edit] Preparing the Customization folder
1. For new installers, copy {Customization_Directory}/_TEMPLATE.
2. Rename [Copy of _TEMPLATE] to {Customization_Code}. The ISO3 can be queried from our GIEWS schema. (e.g. select ISO3 from country_codes where country_name = "Kenya")
The directory should contain the following folders: [communication_module] [database] [webapps_data] [webapps_languages] [webapps_projects]
[edit] Preparing the communication module files
1. Refer to How to generate digital keys and certificates
2. Copy the following files:
* communication.ini
* {Country_Name}Group_GroupKey.key
* {Country_Name}Group_TrustStore.key
to {Customization_Directory}/{Customization_Code}/communication_module folder
- (The instructions below are obsolete, these are replaced by the above instructions.)
1. Request Guido Barbaglia to prepare the necessary files. CC Grita, Mohammad, Geromo in the email.
* {Country_Name} node digital key to be dumped in S:\GIEWS-Workstation\communication_module\new_nodes
* FAO registration of the {Country_Name} node
2. Once Guido created the files, copy from S:\GIEWS-Workstation\communication_module\new_nodes\{Country_Name} the following files:
* communication.ini
* {Country_Name}Group_GroupKey.key
* {Country_Name}Group_TrustStore.key to {Customization_Directory}/{Customization_Code}/communication_module folder
[edit] Preparing the Database schema and projects
This procedure is tedious at the moment. In the future we hope to improve this procedure by generating SQL script instead of cleaning up the database from a JSP.
1. Stop local MySQL server using the Administrator tool.
2. Copy the latest database from lprapp08 GIEWS schema to your local mysql data folder i.e. \\lprapp08\mysql_GIEWS\GIEWS to {MYSQL_Directory}\data\GIEWS_Installer
3. Copy the latest database from lprapp08 geonet schema to your local mysql data folder i.e. \\lprapp08\mysql_GIEWS\geonet to {MYSQL_ Directory}\data\geonet
4. Clean-up the database leaving only the records related to the specific country(s)/region(s) by running locally http://localhost:8080/giews/workstation/prepare_db_for_project_installer.jsp (Note: Before doing so, comment CommunicationModuleUploader in {GIEWS_Web}\WebContent\WEB-INF\web.xml as this servlet is resource-hungry. Remember to restore this servlet later after Step 7. DB clean-up may take at least 10 minutes. Please make appropriate changes in the jsp before running the file. Please double-check the database settings in WEB-INF\giews.ini. It should point to your local Mysql GIEWS_Installer schema)
5. precision table may sometimes contain duplicate records (an issue yet unresolved). Remove duplicate records by running:
CREATE TABLE new_table AS SELECT * FROM precisions WHERE 1 GROUP BY dataset_id, precisions_code; DROP TABLE precisions; RENAME TABLE new_table TO precisions;
6. Just to be sure if the database entire clean-up was successful, query the tables using MySQL browser
7. Perform generate_installer_projects.jsp routine
- Remove the contents of {GIEWS_Web}\WebContent\WEB-INF\projects\{Project_codes} (Note: This may sometimes require a shutdown in Tomcat because KIDS locks the DBF files)
- Run http://localhost:8080/giews/workstation/generate_installer_projects.jsp . This works exactly the same as the old Project Generation except that files are copied directly from Lprapp08 to generate project files. Check Tomcat logs for any errors. Fix any problem.
- Open {GIEWS_Web}\WebContent\WEB-INF\projects\ to check the generated projects.
- Change {GIEWS_Web}\WebContent\WEB-INF\projects\project_tree.xml and projects.xml manually.
- Launch local GIEWS Workstation http://localhost:8080/giews/workstation/page.jspx to check if the projects are loaded.
- Once everything is fine, copy {GIEWS_Web}\WebContent\WEB-INF\projects to {Installer_Builder_Directory}\customization\{Customization_Code}\webapps_projects
- Copy all country notes (note*.xml) and profiles (profile*.xml) from \\lprapp08\tomcat_GIEWS\webapps\GIEWS_KIDS\WEB-INF\projects \ {Customization_Code} to {Installer_Builder_Directory}\customization\{Customization_Code}\webapps_projects
8. Stop local MySQL server using the Administrator tool
9. Copy database files from {MYSQL_Directory}/data/GIEWS_Installer to {Installer_Builder_Directory}\customization\{Customization_Code}\database
10. Copy all files in {MYSQL_Directory}/data/geonet to {Installer_Builder_Directory}\database\dist\mysql\data
[edit] Preparing Crop calendar
1. Run SELECT * FROM GIEWS_installer.cropcalendar; If there are records, copy the image from \\lprapp08\tomcat_GIEWS\webapps\GIEWS_KIDS\data to Installer_Builder_Directory}\customization\{Customization_Name}\webapps_data
[edit] Getting the latest Online Help
1. The Online Help may be more updated than that of SVN because Francesca updates the Help pages often. If this is the case, copy the files under \\lprapp08.fao.org\tomcat_GIEWS\webapps\GIEWS_KIDS\giews_help tp {GIEWS_Web}\WebContent\giews_help
2. Coordinate with Tanzila about any modifications in the chapters. This is in reference to the version in Ldvapp03.
3. Commit the files to the SVN.
[edit] Prepare Geonetwork
1. {Geonetwork_Webapps} should have the latest files. Otherwise, merge with \\lprapp08\tomcat_GIEWS\webapps\geonetwork or contact Emmanuele for any recent updates. Then checkin the latest Geonetwork codes to SVN.
[edit] Building the installer
1. Open {Installer_Builder}\build.properties in your Eclipse workspace and change the values as appropriate
[edit] build.properties
app-version=2.3
customization-display-name=GIEWS Workstation for {Country_Name}
customization-folder-name=GIEWS_Workstation
customization-shortcut-name=GIEWS Workstation
customization-exe-name=GW_
customization-name={ISO_Code}
country={Country_Name}
default_node_name={Country_Name}
default-server-port-no=8084
default-http-port-no=8087
default-db-port-no=3307
logging-mode=on
include-java-source=true
2. Double-click on build-installer-customization.xml
3. Right-click. Run As.. Ant Build build-installer
4. An Ant Input Request window will popup. Select y and the process will start.
5. The output exe will be created in {Installer_Builder}\installer\dist
6. Move the exe to {Installer_Builder}\installer\dist{Customization_code}
Note that for future updates in creating the installer, these two files are most important: build-installer-customization-windows.xml and installer-windows.xml. Below is giews-installer structure for your reference.
[edit] giews-installer directory structure
[giews-installer] --- [customization] ------ [_TEMPLATE] --------- [communication_module] --------- [database] --------- [webapps_data] --------- [webapps_languages] --------- [webapps_projects] --- [database] ------ [dist] --------- [mysql] ------------ [os_windows] --------------- [bin] ------------------ start-MySQL-server.bat ------------------ stop-MySQL-server.bat --------------- [scripts] --------------- [share] --------------- db-config.properties --------------- my.ini --- [etc] --- [installer] ------ [bin] --------- [apache-tomcat] --------- [jre] --------- [utilities] ------ [izpack] --------- [bin] --------- [conf] ------------ installer-params.xsl ------------ installer-windows.xml ------------ shortcutSpec.xml ------------ userInputSpec.xml ------ [jsmooth] --------- [conf] ------------- install-GIEWSWorkstation.jsmooth ------------ uninstall-GIEWSWorkstation.jsmooth ------ [lib] ------ [src] --------- GWInfo.html --------- index.html --------- Licence.txt --------- Readme.txt --------- [dynamic-patches] -------------- [dist] ----------------- launch-Readme.bat ----------------- service-GIEWSWorkstation.bat ----------------- shutdown-server.bat ----------------- startdb.bat ----------------- startup-server.bat ----------------- stopdb.bat ----------------- uninstall.bat --- [server] ------ [classes] ------ [lib] ------ [icons] --------- folder.ico --------- GIEWSWorkstation-logo.ico --------- shutdown-server.ico --------- startup-server.ico --------- uninstall.ico --------- Word.ico ------ [images] --------- company_logo.gif --------- icon.png build-installer-customization-windows.xml build.properties
[edit] Testing the installer
1. Double click the exe file in {Installer_Builder}\installer\dist{Customization_code}.
2. Go through the installation process until the Step where it would ask for a Node Name. The default_node_name in build.properties will be the default. If the installation is for a Ministry or Institution, change the Node name to the ministry or institute name (e.g. Ministry of Agriculture, National Statistics Office, etc.)
3. At the end of installation, the Tomcat and Mysql servers are automatically started. Search for the shortcut in Start menu. Click on Start Workstation to launch the Workstation page in your default browser.
[edit] Distributing the installer
1. Zip the whole {Installer_Builder}\installer\dist{Customization_code} folder. Name the zip as {Country_Name}v#YYYY.MM.DD.zip (e.g. Ethiopiav2.3.2007.11.26.zip)
2. Copy the file to \\ext-ftp\es\Reserved\GIEWS\Workstation\{Country_Name}
3. This is accessible from FTP as ftp://ext-ftp.fao.org/ES/Reserved/GIEWS/Workstation/{Country_Name}/{Country_Name}v#YYYY.MM.DD.zip
e.g. ftp://ext-ftp.fao.org/ES/Reserved/GIEWS/Workstation/Ethiopia/Ethiopiav2.3.2007.11.26.zip
4. Send email to everyone concerned about the installer release.
[edit] Releases
| Country Name | OS | Date Last Requested | Who Requested | Notes | |
|---|---|---|---|---|---|
| Guatemala | Windows | Nov 19, 2007 | Gladys Morales | Provided Gladys with auto-run CD; installed in her notebook for the PRESANCA mission; Includes South America | |
| El Salvador | Windows | Nov 19, 2007 | Gladys Morales | Provided Gladys with auto-run CD; installed in her notebook for the PRESANCA mission; Includes South America | |
| Ethiopia | Windows | Nov 16, 2007 | Shukri Ahmed | Provided Shukri with auto-run CD; installed in his notebook for his mission; Includes Eastern Africa | |
| Palestine | Windows | Nov 9, 2007 | Fabio Grita | Includes Palestine (combined West Bank+Gaza Strip), West Bank and Gaza Strip projects | |
| Georgia | Windows | Oct 5, 2007 | Fabio Grita | ||
| Armenia | Linux | Armen Sedrakyan | |||
| Kenya | Linux |
