EEA
SMAP PTK installation instructions
| Released | 16/01/2007 |
|---|---|
| Contributor | bulanmir |
(Windows 2000, XP)
Table of Contents
2. Requirements
3. Distribution package
4. Pre-installation checks
5. Required information
1. Introduction
The SMAP Clearing House (http://smap.ew.eea.europa.eu) makes available its portal software in the form of a portal toolkit, with friendly installation package for Windows. This architecture is based on the Zope (http://www.zope.org) Web and application server, the Python (http://www.python.org) scripting language and the Naaya multilingual content management system. The outcome of the installation process is an out-of-the-box SMAP node.
The purpose of this document is to describe how the SMAP PTK installation package should be used on a server running Windows 2000 or Windows XP. This is a turn-key self-contained package that installs:
- a Zope server version 2.7.5
- a Zope instance for the SMAP portal
- the SMAP PTK software (set of Python products for Zope)
- converters to plain text for DOC, PDF and XLS files (the converters are useful to index and search through binary files)
You should have fairly good knowledge of the Windows operating system in order to be able to perform these tasks.
2. Requirements
- An user account with administration rights on the local machine
- At least 200 Mbytes free disk space on the drive you are performing the installation to. This is the minimum requirement for the installation. Extra disk space should be allocated for the log files and for new data that will be uploaded in the portal.
- Assuming a dedicated server, the system should have at least 256 Mbytes main memory (minimum installation requirement, 512 Mbytes recommended)
- WinZip 8.0 or higher
3. Distribution package
The distribution package is available at the SMAP PTK distribution page, and it contains the following files:
- SMAP_Installation_Guide.html (this file)
- SMAP.exe (SMAP Portal Toolkit installation package)
4. Pre-installation checks
The following checks must be done before proceeding with the installation:
- Memory size should be at least 256 Mbytes. The General tab of your System Properties dialogue box (right click on the My Computer shortcut from your desktop to obtain it) displays a section called Computer, which provides you information about the RAM.
- Check that there is enough free space (200 Mbytes) on the drive you are planning to install the kit. There are many ways you can find this out, for instance: open a Windows Explorer, click on My Computer item and inspect the size and available space of all the drives from your computer.
5. Required information
During the installation process, the following information will be requested:
- Full host name: if you want to publish your portal on the Internet, you need a registered domain name such as smap.it, otherwise you can just leave the field completed with the local computer name, which is automatically detected for you;
- Host IP address: the local computer's IP address is automatically detected and completed for you;
- An account - username and password - for the administrator of the Zope server: http://server_name:HTTP_port_number/manage.
- An e-mail address of the administrator of this portal (e.g. webmaster@your_organisation.ro). This e-mail address will receive important messages from the Zope server.
- Port number for the Zope Web server (HTTP)
- An e-mail server that can be accessed by the portal to send emails (never to receive). This is not necessary if the toolkit is used only to edit data off-line and then update the server.
- The port of the email server listed above.
- An e-mail address of the mailbox of this portal (e.g. portal_notification@your_organisation.ro). This e-mail address will be shown in FROM field in every e-mail sent by the portal.
6. Installation
When you have collected all the above information you can start the installation procedure. Click on the SMAP.exe file, which will result in unzipping the archive into the SMAP PTK Installation Files and starting the actual installation process.
The program will perform the necessary checks and will ask for all the information you collected in the previous section, before installing and configuring the SMAP portal. Some times the wizard will provide you with a (guessed) default option, but don't accept blindly its suggestions - use the information gathered by you.
Tips:
a. The folder you choose to install into should be empty at installation time. It is advised to let the installation program create it.
b. The application is registered as a Windows Service, the operating system takes care of re-starting it, even before a user logs on that machine. This means that, Zope server is registered as Windows Service. The service management can be done in three ways: using the Windows Services console, using the SMAP server console application or using the scripts provided, as BAT files, for starting/stopping and installing/uninstalling the service.
c. If the installation fails for some reason, the installation program will try to delete all the files copied. You are advised to check that yourself and manually remove the potential remaining files before running the installer again: all the files are copied in the folder you have specified in Step 1 of the set-up process.
d. A folder will be created in the Start Menu folder, Programs named "SMAP" which will contain shortcuts to application files.
No Environment variables are added or modified during the installation process.
e. The performed installation steps are listed in a file named install.log. This could become useful in the case something goes wrong.
7. Installed components
The SMAP PTK Installation Wizard installs the following servers in specified folders:
- Zope2.7.5 in the <install_path>\zope folder
- application scripts (BAT files) in the <install_path>\bin folder
- converters in the <install_path>\bin folder
- SMAPUnins.exe in the <install_path> folder
- install.log in the <install_path> folder
The application comes with scripts (BAT files) that can be executed from the command line or by double-clicking on them:
- installservice.bat - will try to install the Zope service
- removeservice.bat - will try to uninstall the Zope service
- startservice.bat - will try to start the Zope service
- stopservice.bat - will try to stop the Zope service
The application writes this key in the registry HKEY_LOCAL_MACHINE\SOFTWARE\SMAP\SMAP PTK.
An entry is created among the system shortcuts: Start -> Programs -> SMAP.
7.1. Converters
TextIndexNG, which is a third-party component of Naaya supports a registry for external converters wrapped into a Python class to convert a document or an object to text before it gets indexed. The converter is selected based on the mime-type and the extension of the object (file). The following converters are avaialable:
- for PDF files; the converter is located in the <install_path>\bin\converters\pdftohtml folder
- for DOC files; the converter is located in the <install_path>\bin\converters\antiword folder
- for XLS files; the converter is located in the <install_path>\bin\converters\xlHTML folder
8. Zope
Zope is an open source application server for building content management systems, intranets, portals, and custom applications. The Zope community consists of hundreds of companies and thousands of developers all over the world, working on building the platform and Zope applications. Zope is written in Python, a highly-productive, object-oriented scripting language.
Under Microsoft WindowsNT/2000/XP, there are two ways you can run Zope:
- as a service. This is the best option if you want Zope to automatically start when your machine boots, and to keep Zope running when you log-off.
- from a console window. Closing this console window will terminate the Zope server.
The SMAP Portal Toolkit Install Wizard installs and configures Zope as a service named SMAPZope. The Zope server files can be found in the folder <install_path>\zope and Zope instance files can be found in the folder <install_path>\instance. The instance configuration file zope.conf can be found under the folder <install_path>\instance\etc.
Note: On the same machine, multiple Zope services can be installed by other tools, each one with a different name and configuration.
8.1. Running Zope as a service
There are three ways you can control the SMAPZope service:
a. Using the Windows Services console. It is available in the Start Menu Folder -> Control Panel -> Administrative Tools.
This console presents a list with all services. The SMAPZope service is also present in this list. If you select this from the list a window will open; here information about the service can be found (name, description, status) and also some actions can be performed:
- Start - if the server is not running this will start the server
- Stop - if the server is running this will stop the server
- Change startup type - by default is set as Automatic this means that the Zope will start every time the system starts. This can be changed into Manual, the server will not start automatically but instead must be start manually. The Disable type prevents the service from being started by the system, a user, or any dependent device.
b. Using the SMAP server console. It is available in the Start Menu Folder -> SMAP.
From this console the same actions like above can be performed: view information about the service, start and stop the service and change the startup type.
c. Control the service manually from command line.
The native Windows NT/2000 command NET can be used:
NET START "SMAPZope" - this will start the service
NET STOP "SMAPZope" - this will stop the service
The following commands are available:
<install_path>\zope\bin\python.exe <install_path>\instance\bin\zopeservice.py --startup=manual install - register Zope as service (this is already done for you by the installation kit)
<install_path>\zope\bin\python.exe <install_path>\instance\bin\zopeservice.py remove - remove Zope from services
<install_path>\zope\bin\python.exe <install_path>\instance\bin\zopeservice.py start - start the service
<install_path>\zope\bin\python.exe <install_path>\instance\bin\zopeservice.py stop - stop the service
<install_path>\zope\bin\python.exe <install_path>\instance\bin\zopeservice.py restart - restart the service
Note: For details about the service usage consult the header of the file:
<install_path>\instance\bin\zopeservice.py
Note: The name of the services is specified in a special file:
<install_path>\instance\bin\zopeservice.py
Do not modify this file since the application assumes the service name is SMAPZope.
8.2. Running Zope from command line
To run Zope manually just execute the <install_path>\instance\bin\runzope.bat. You can do that either by locating the file using a file browser such as Windows Explorer and double-clicking on it, or by opening a command prompt and executing the above command. Closing the console window will stop the server in this case.
8.3. Change Zope configuration
The Zope configuration file is <install_path>\instance\etc\zope.conf. The most important environment settings are:
- HTTP_PORT - the port for HTTP server
- WEBDAV_SOURCE_PORT - the port for the special WebDAV source view
- FTP_PORT - the port for FTP server
If you want to modify any of these modify the zope.conf file. This file can be edited using any text editor (e.g. Notepad).
Please check the links available in the A. Resources section for further information.
9. Issues and troubleshooting
You must have Administrator rights in order to perform the following actions:
- install the application
- uninstall (remove) the application
- use the SMAP server console
9.1. Installing issues
a. There can be only one installation on the same machine and system. This is because:
- it registers the Zope service (SMAPZope) and you cannot have two services with the same name.
- it writes a key with a fixed name in the registry
- it creates a folder with shortcuts and if the folder exists, then the shortcuts cannot be created
b. The installation log file, install.log, containing details about the operations done during the installation process is located in the <install_path> folder.
9.2. Uninstalling issues
The uninstall can be performed by executing the SMAPUnins.exe program located in the <install_path> folder.
a. When the uninstaller is executed, it reads the application data from the registry and, before removing the application, it will display all the actions that will be performed. Please read them carefully before proceeding.
b. The uninstaller will not remove the followings:
- install.log
- SMAPUnins.exe
- the backup folder that is created during the uninstall process; here a copy of the Zope's data.fs can be found
c. Before starting the uninstaller wizard, it is recommended to stop the Zope service. This will prevent a situation like: the service is blocked for some reason and the uninstaller cannot control it anymore so the service cannot be removed because of this.
A known issue is that the SMAPZope service may encounter problems when it is stopped (long timeout or even blocking).
Note: DO NOT remove the service folder before removing the service, since Windows cannot remove a service if its Path to executable is invalid or missing.
d. If you have the situation described above and the uninstaller was incapable to remove some of the service, you will notice that also the corresponding folder was not removed. In order to remove that service the following steps must be performed in this order:
- use the Registry Editor (regedit) to remove all the keys related to the service (search by service name, e.g. SMAPZope)
- reboot the system in order to have the service removed
- delete the corresponding folder (e.g. zope)
10. Post installation
10.1. Cron jobs
Some actions in the portal must be performed on regular basis (e.g. once a day): update the RDF channels and clean up for unsubmitted items. For each portal an UID is generated; the UID is needed in order to call portal methods from the cron jobs. The portal UID is available in the ZMI in the portal_properties object. If a wrong UID is provided, then the methods will not run; this a measure of security. Three cron jobs must be working in the operating system:
- update RDF channels - the following URL must be accessed:
http://server_name:HTTP_port_number/SMAP/updateRemoteChannels?uid=<portal UID>
- clean up portal - the following URL must be accessed:
http://server_name:HTTP_port_number/SMAP/cleanupUnsubmittedObjects?uid=<portal UID>
The Scheduled Tasks available from the Control Panel can be used to run the cron jobs. For each a task must be created: the IE browser must be selected as the program that must be executed and the specific cron job URL must be appended to the Run command.
Of course any software that handles cron jobs can be used.
10.2. Mapping Domain Name
After the SMAP website kit is installed on your machine, you can access it at the web address: http://hostname:http_port/SMAP. If you want that the SMAP website to be visible as http://portal_url, there are some steps to be followed:
- Map in a Domain Name Server portal_url web address as your machine's IP address.
- Map in your http server's configuration files (usually Apache Server) the http://hostname:http_port/SMAP address as http://portal_url.
Apache virtualhost configuration
The Apache HTTP server can be set up to serve the Zope's SMAP content through the virtualhost directive. The term Virtual Host refers to the practice of maintaining more than one server on one machine, as differentiated by their apparent hostname. Apache must have the mod_proxy module installed.
Below is a virtual host directive example:
<VirtualHost IP_address>
ServerAdmin administrator's_email_address
ServerName portal_url
ProxyPass /errorp http://hostname/errorp
ProxyPass / http://localhost:zope_port/VirtualHostBase/http/portal_url:80/SMAP/VirtualHostRoot/
ProxyPassReverse / http://localhost:zope_port/VirtualHostBase/http/portal_url/SMAP/VirtualHostRoot/
ProxyPass /misc_ http://hostname:zope_port/misc_
ProxyPass /p_ http://hostname:zope_port/p_
TransferLog logs/SMAP_log
CustomLog logs/SMAP_log combined
</VirtualHost>
For more information on apache configuration, visit the Apache Server Website.
11. Access statistics
In order to have access statistics, a special program that parses the Zope's log can be used or a third party solution for tracking.
An example of a an application that analyse log files is Analog.
"Analog is a program to measure the usage on your web server. It tells you which pages are most popular, which countries people are visiting from, which sites they tried to follow broken links from, and all sorts of other useful information."
For more information please read Analog: Introduction.
An example of a web counter service is Site Meter.
"Site Meter is a free, fast, and easy way to add a web counter to your web page. Not only can it display the number of visitors to your web site, it also keeps statistics on the number of visits each hour and every day. It also provides detailed information about these visitors. These statistics are provided in real time so they are always up-to-date."
"Site Meter tracks page views and visits. You may also have heard the term "hits". When someone comes to your site, they generate a "hit" for every piece of content that is sent to their computer. Viewing a single web site page would generate one hit for the page and one hit for every individual graphics file that was on the page. A single page could easily generate a dozen or more hits. When you are browsing a site, every time you follow a link, it is treated as a single "page view". Site Meter defines a "visit" as a series of page views by one person with no more than 30 minutes in between page views."
For more information please read Site Meter FAQ.
A. Resources
- Zope application server:
http://www.zope.org/
Zope documentation:
http://www.zope.org/Documentation/ - How to Create a Windows Service Using Sc.exe
http://support.microsoft.com/?kbid=251192