The following might be useful as a tech writing example. I took Pete’s email (below), and created a Word doc from it (below his message). With some iterative questioning, I put the doc together. This ultimately was included in a larger document. The intended audience are technical IT people – system administrators with heavy IT experience.
From: Cyr, Pete
Sent: Thursday, August 18, 2011 6:23 PM
To: Sinnott, Quinn; 'Hassall, Michael'
Cc: Reisinger, Marty; Wang, David; Kinard, Gary; Emberland, Gorm
Subject: RE: Installation of Grin Global for MySQL
I'm sorry to be getting involved in this email thread so late, but I was on vacation last week (a nice relaxing week at the beach with no computers – I highly recommend it!) so this is my first chance to respond. Here are the steps I would recommend you attempt to get your system up and running with MySQL on a remote (non-Windows) server.
Step 1 – Install the GG system on a fresh clean Windows box as follows:
a) Cleanly install either XP Pro SP3 or Windows 7 Pro/Ultimate (not the Home Edition please).
b) Install MySQL – I typically use the Windows Essentials 5.1 installer (make sure the default storage engine is InnoDB).
c) Navigate your browser to our beta-test downloads website: http://test.grin-global.org/gringlobal/downloads/ and download and install the Updater application by following the instruction in the attached PDF (the Updater install steps start on page 9 but the first 8 pages are good background material before you install).
d) Follow the steps in the PDF document for installing all three of the GG server components on the Windows box (see page 17) – you will want to create the GG server using a localhost database connection – it should automatically detect your MySQL installation and install the GG database to it.
Note: You do not need to install the Curator Tool on the server to get your GG server up and running (the Curator Tool is an application designed to be used on the curators desktop computer – not something that is typically used directly on the GG server – but having said that, there is nothing that prevents you from installing the Curator Tool on the server if you prefer)
Step 2 – Load your local data (using the Import Wizard in the Administrator Tool) to the new MySQL GG database
a) Start the Administrator Tool.
b) Follow the instructions in the attached PDF for preparing your local data for importing to GG using the Import Wizard
NOTE: you can use the template data at our website (http://www.grin-global.org/index.php/Training) to see example data for how to properly format your import data.
The instructions are in the PDF link in the left column and the sample data are in the links in the right column.
Step 3 – Load the data into your remote MySQL database server
a) Backup the MySQL GG database from your localhost Windows server
b) Copy the backup file over to your remote MySQL database and restore it there
Step 4 – Modify the database connection used by the middle tier web services to point at your new remote MySQL database (see image)
a) Start the Administrator Tool
b) Expand the ‘Web Application’ branch
c) Select ‘DataManager (Connection String)’ branch (it is the bottom branch in the tree)
e) Reboot the GG Windows server and try connecting to the localhost GG website (http://localhost/gringlobal/search.aspx) from the Windows box
If all went well, your GG website, web services and search engine should all be using the data stored in the remote MySQL database.
On a slightly different subject...
To answer your questions about how the Curator Tool interacts with changing the MySQL database server as you did in the step above... The short and simple answer is that it has no effect on the Curator Tool at all. The reason is because the CT only gets data through the web services (Middle Tier) so when you changed the Middle Tier database connection string in Step 3d above the Curator Tool knew nothing about it but it will now be getting data from the new database server (instead of getting data from your original MySQL GG database on the Windows box).
If that last paragraph has confused you, perhaps these ‘fun facts’ about the GG system will help clarify things:
1) There are three tiers in the GG system – Client Tier, Middle Tier, and Data Tier.
2) The Curator Tool (a Client Tier application) never talks to the Data Tier directly (in your case the Data Tier is the remote MySQL database).
3) The Middle Tier consists of three sub-components: the GG website, the Search Engine, and the Web Services (data brokers used by the Client Tier applications).
4) The Middle Tier runs under the IIS web server on a Windows box.
5) The Curator Tool only talks to the Middle Tier Web Services, and it does so using HTML and XML through port 80 on the IIS server (very firewall friendly).
6) The Middle Tier acts as the ‘middle man’ for brokering the data between the Data Tier and the Curator Tool. Therefore the Curator Tool never needs a database connector to the GG database because it never connects directly to that database – instead it requests data from the Middle Tier which then uses its MySQL database connector to get the data from the remote MySQL database.
I hope this helps to clarify some of the confusion. Please do not hesitate to let us know how we can be of further assistance during your installation of GG on MySQL.
_________________ end of Pete’s message; doc follows:
Installing GRIN-Global on a Non-Windows Server
GRIN-Global was designed to primarily run in a Windows environment, but it is possible to have a non-Windows server house a MySQL, PostgreSQL, or Oracle database. However, to do so, you will need to first install GG on a Windows-based PC, and then port the database from the Windows-based PC over to the non-Windows server by backing up the Windows database and restoring it to the non-Windows server.
After porting the database to the non-Windows server, you will then point to the database in its new location with a parameter in the GRIN-Global Admin tool. Follow the detailed steps in this section for this type of installation.
The GRIN-Global (GG) system is a 3-tier based system. The three tiers are the: client, middle, and data tiers.
The data tier is the database where the plant genetic resource data is permanently stored – GRIN-Global is designed to handle four database engines: SQL Server, MySQL, Oracle, PostgreSQL. Organizations can implement any one of these as their database engine.
The middle tier consists of three sub-components: the GG Public Website, the Search Engine, and Web Services. (Web Services sends and receives data used by any Client Tier application.)
The middle tier runs under the IIS web server on a Windows computer.
The GG client tier application – the Curator Tool – never talks to the data tier directly, but instead communicates only with the middle tier’s Web Services, using HTML and XML through port 80 on the IIS server. (By using port 80, the CT is very firewall friendly.)
Since the middle tier manages the data between the data tier and the client tier ( the Curator Tool), the CT never needs a database connector to the GG database because it never connects directly to that database; instead the CT requests data from the middle tier which in turn uses its database connector to retrieve the data from the remote database (data tier)
The ideal environment for installing GG is a Windows-based computer that has not yet had any applications installed on it, especially database applications. Having a “clean” system avoids any possible conflicts that may occur when there are two or more database engines installed on the same PC. For example, if a PC has SQL Server 2005 running on it, during the GG installation, GG will load a 2008 version of SQL Server. Sometimes having more than one database engine installed on the same box, such as SLQ Server and MySQL, can also complicate installation of GG.
1. Install either Windows XP Pro SP3 or Windows 7 Pro/Ultimate. (GRIN-Global is not compatible with Windows Home Edition, therefore do not install on any Windows Home OS.)
2. Install a version of your preferred database engine on the Windows computer. For example, if you intend to run Oracle, MySQL, or PostgreSQL on the remote server, install the Windows version on your Windows box now. NOTE: MySQL installations should use the MySQL Windows Essentials 5.1 installer and ensure that the InnoDB storage engine is set as the default.
3. Navigate your browser to the GRIN-Global test download website: http://test.grin-global.org/gringlobal/downloads/ . Download and install the GG Updater application by following the instructions in the GRIN-Global Installation Guide. (The Updater installation steps begin on page 9, but the first eight pages include background material you should review before installing.)
4. Refer to the section Server Components: Installing (or Updating) section in the Installation Guide and follow the steps for installing the three GG server components on a Windows-based computer. Create the GG server using a localhost database connection – it should automatically detect your preferred database installed in step 2 above and install the GG database to it.
You do not need to install the Curator Tool on the server to get your GG server up and running.
The Curator Tool is an application designed to be used on the curator’s desktop PC and does not typically run on the server, but if you prefer, you can also install it on the server.
Note that whenever you install the Curator Tool on a PC, a version of SQL Server Express will also be installed. The Curator Tool uses this database engine only for its lookup tables. There should not be any clash with the main database engine by installing SQL Server Express.
Load Your Local Data to the New MySQL GRIN-Global Database
1. Start the GG Administrator Tool. You will use the Import Wizard in the Administrator Tool to complete these next steps.
2. Follow the instructions in the Import Wizard Cookbook for preparing your local data for importing to GG using the Import Wizard.
For examples of sample data, refer to the spreadsheets at http://www.grin-global.org/index.php/Training There is a zip file listed under the Training Exercises section, in the table’s fourth row, that contains all of the sample .csv files.
Load the Data into Your Remote MySQL Database Server
1. Backup the MySQL GRIN-Global database from your localhost Windows server.
2. Copy the backup file over to your remote MySQL database and restore it there.
Modify the Database Connection Used by the Middle Tier Web Services
In this step, you will use the GG Admin Tool to point to your new remote database.
1. Start the Admin Tool.
2. Click on the Web Application branch; select DataManager (Connection String).
3. Modify the Connection String box to point to your remote server. To do so, click the Provider dropdown box; select the database type that matches the target remote database engine type. Then click the Connection String Creator… button.
Complete the fields on the Database Connection window to generate the correct Connection String text. Click the Save and Continue button when complete. (Each database engine type has its respective Database Connection window. The one shown here pertains to SQL Server.)
5. To test your remote database, reboot the Windows server that hosts the GG Web Services and Public Website. After the server reboots completely, on your client PC open a browser and connect to the localhost GG Public Website using (http://localhost/gringlobal/search.aspx). If the Public Website comes up without errors, you can be assured that the new remote database is working and connected properly because the following conditions are true: