Difference between revisions of "EPF Wiki Installation Guide"

Revision as of 02:36, 26 July 2008

This guide describes how to install EPF Wiki on Windows using InstantRails. Use of InstantRails is recommended if you want to install EPF Wiki on Windows for production, test and demo purposes. Note however that the recommended production environment for Rails (and so for EPF Wiki) is Linux. Detailed installation instructions for Linux are in the EPF Wiki Virtual Appliance Guide, which describes how to create EPF Wiki as a VMWare Virtual Appliance using Linux Debian.

If you have any questions about this guide or EPF Wiki please use the Eclipse Process Framework Project Developers List

Requirements

• InstantRails 2.0
• Internet Browser (FireFox 3.0 recommended)
• Windows XP Professional
• Latest EPF Wiki zip file from http://www.eclipse.org/epf
• UnxUtils
• HTML Tidy
• 7-zip

Note: this guide has only been tested to work for Windows XP Professional but in principle it should work equally well for other Windows versions e.g. Windows Server.

UnxUtils

UnxUtils is used to unzip uploaded zip files with content. To install it:

1. Creat folder with path C:\UnxUtils and download and extract UnxUtils there
2. Add the entry C:\UnxUtils\usr\local\wbin; for UnxUtils to your PATH variable

After these steps you should be able to run unzip from any folder. To test it:

C:\Documents and Settings\Vmware>unzip --help
UnZip 5.42 of 14 January 2001, by Info-ZIP.  Maintained by C. Spieler.    
...
C:\Documents and Settings\Vmware>

HTML Tidy

HTML tidy is used to cleanup HTML. This is done to improve differences analysis using XHTMLDiff.

An easy way to install it is to drop the executable tidy.exe from http://tidy.sourceforge.net/ in the folder c:\WINDOWS\SYSTEM32. Any other location is fine too of course but EPF Wiki assumes Tidy can be run from any location (without path).

To test it:

C:\Documents and Settings\Vmware>tidy -v
HTML Tidy for Windows released on 25 January 2008

InstantRails

1. Create a folder with path C:\InstantRails2.0 and extract the InstantRails-2.0-win.zip there. Note: there are some issues reported extracting the InstantRails zip, see Unzip Problems

You can now start the InstantRails Manager (InstantRails.exe) from the root of the extracted file.

Apply Mongrel Workaround Patch for EPFC using index.htm

EPFC generates sites with index.htm in the root folder to start the site. Most Web servers assume such files will be named index.html but allow you to configure alternatives. Mongrel is not so advanced so we change this hard coded assumption.

We change the method can_serve in file handlers.rb (in folder C:\InstantRails2.0\ruby\lib\ruby\gems\1.8\gems\mongrel-1.1.2-x86-mswin32\lib\mongrel) so it will also serve index.htm. The snippet below shows added lines in bold.

if File.directory? req_path
  # The request is for a directory
  index = File.join(req_path, @index_html)
  index2 = File.join(req_path, 'index.htm')
  if File.exist? index
    # Serve the index
    return index
  elsif File.exist? index2
    return index2
  elsif @listing_allowed
    # Serve the directory
    return req_path
  else
    # Do not serve anything
    return nil
  end
else

EPF Wiki

Required Gems

When using InstantRails we only need xhtmldiff.

1. Start the InstantRails Manager (InstantRails.exe) and select I > Rails Applications > Manage Rails Applications. Press the button Create New Rails App... This should open a Command Prompt.
2. Type gem install xhtmldiff. Note, if you need to install behind a proxy server you can use the p switch, the command will look something like gem install xhtmldiff -p http://myproxy.mydomain.com.

Example:

C:\InstantRails2.0\rails_apps\EPFWiki>gem install xhtmldiff -p http://myproxy.mydomain.com
Bulk updating Gem source index for: http://gems.rubyforge.org
Successfully installed diff-lcs-1.1.2
Successfully installed xhtmldiff-1.0.0
2 gems installed
Installing ri documentation for diff-lcs-1.1.2...
Installing ri documentation for xhtmldiff-1.0.0...
Installing RDoc documentation for diff-lcs-1.1.2...
Installing RDoc documentation for xhtmldiff-1.0.0...

Create the EPF Wiki Application Folder

1. Create a folder with the name EPFWiki in the rails_apps folder of InstantRails.
2. Download the EPFWiki.zip to this folder and extract the contents there
3. Start the InstantRails Manager (InstantRails.exe) and select I > Rails Applications > Manage Rails Applications. The list of applications should now include EPFWiki.
4. Create a folder with the name log in the folder EPFWiki

Create the MySQL Database User

1. Start the InstantRails Manager (InstantRails.exe) and select I > Rails Applications > Manage Rails Applications. Press the button Create New Rails App... This should open a Command Prompt.
2. Navigate to the EPF Wiki folder
3. In the Command Prompt logon to MySQL as root
4. Create the user epfwiki with the password ikiwpur.
5. Grant privileges and usage to this database user.

Note: if you want to use a different database user and password, you should change the database config file (config/database.yml) accordingly.

Example:

C:\InstantRails2.0\rails_apps>cd EPFWiki

C:\InstantRails2.0\rails_apps\EPFWiki>mysql -uroot
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1 to server version: 5.0.27-community 

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> create user epfwiki identified by 'ikiwpur';
Query OK, 0 rows affected (0.08 sec)

mysql> grant all privileges on *.* to epfwiki;
Query OK, 0 rows affected (0.05 sec) 

mysql> grant usage on *.* to epfwiki;
Query OK, 0 rows affected (0.00 sec)

Create the database, load the schema and data

1. Start the InstantRails Manager (InstantRails.exe) and select I > Rails Applications > Manage Rails Applications. Press the button Create New Rails App... This should open a Command Prompt.
2. Navigate to the EPF Wiki folder
3. Type set RAILS_ENV=production
4. Run the migration scripts: rake db:create db:migrate

Note: if you need or want to recreate the database you can run the command rake rake db:drop db:create db:migrate

Example:

C:\InstantRails2.0\rails_apps\EPFWiki>rake db:create db:migrate
(in C:/InstantRails2.0/rails_apps/EPFWiki)
== 1 Initial: migrating =======================================================
-- create_table("checkouts", {:force=>true})
   -> 0.0160s
-- add_index("checkouts", ["user_id"], {:name=>"checkouts_user_id_index"})
   -> 0.0160s
...
 (lines deleted)
...
== 8 AdminMessages: migrating =================================================
== 8 AdminMessages: migrated (0.1250s) ========================================

== 9 CreateUpdates: migrating =================================================
-- create_table(:updates)
  -> 0.0160s
== 9 CreateUpdates: migrated (0.0160s) ========================================

C:\InstantRails2.0\rails_apps\EPFWiki>

TinyMCE

EPF Wiki has been confirmed to work with TinyMCE version 2.0.8 and 2.1.3 but not with 3.1.0.1, which is the first download on the TinyMCE page.

To integrate TinyMCE with EPF Wiki:

1. Download TinyMCE 2.1.3 from tinymce.moxiecode.com
2. Extract the contents and copy the folder tinymce\jscripts\tiny_mce to [application install dir]\public\javascripts. The folder javascripts\tiny_mce should now contain Javascript library tiny_mce.js

EPF Wiki does not work together with 3.1.0.1! The editor will start if you use this version but the EPF Wiki toolbar with buttons for save, checkin and undo checkout will not be rendered

Specify the details of your SMTP server

EPF Wiki uses email extensively (for registration of new users, change reports), so an important step for any production environment is to add the details of your SMTP server to the configuration file for the production environment production.rb (in folder config/environments/). It is recommended the EPF Wiki server gets anonymous access to the SMTP server. It is also recommended to test the access to the SMTP server using Telnet before making EPF Wiki available for use. On the internet there are many howto's on how to do that, see smtp telnet email

With anonymous access to the SMTP server, the settings will look something like:

ActionMailer::Base.delivery_method = :smtp
ActionMailer::Base.smtp_settings = {
 :address  => "smtp.resultinfra.com",
 :port  => 25, 
 :domain  => 'resultinfra.com',
} 

When you need to logon to use the SMTP server, there are other arguments you need to add:

:user_name  => "andy.kaufman@epf.eclipse.org",
:password  => "Andy Kaufman",
:authentication  => :login

Add and Configure EPF Wiki as an InstantRails Application

1. Start the InstantRails Manager (InstantRails.exe) and select I > Rails Applications > Manage Rails Applications.
2. From the list select EPFWikiand press Configure Startup Mode
3. Replace development with production in the Runtime Mode field
4. Replace 3000 with 3003 in the Port field
5. Press Edit Apache Config File and add a Virtual Host directive for your server

Example of a Virtual Host directive:

<VirtualHost *>
    ServerName myepfwiki
    ProxyPass / http://localhost:3003/
    ProxyPassReverse / http://localhost:3003
</VirtualHost>

If you don't have a real, existing hostname in the DNS, you also have to edit the hosts file:

1. Press Edit Windows Host File and add a entry for your hostname

Example of a host file entry:

127.0.0.1	myepfwiki

1. Press Ok

Tell EPF Wiki about the Web Server Hostname

EPF Wiki uses jobs (Scheduled Tasks on Windows) to send reports and update Wiki sites. Such a job is unaware of the Web server configuration as no Web server is involved in the operation, so we have to tell EPF Wiki the host and port the Web server is using. We can do this be editing the configuration file for the production environment (config/environments/production.rb).

1. Open production.rb
2. Replace ENV['EPFWIKI_HOST'] = "localhost" with the right hostname e.g. ENV['EPFWIKI_HOST'] = "myepfwiki"

Note: include a port number if you are not using the default port 80 e.g. ENV['EPFWIKI_HOST'] = "myepfwiki:8080"

Start EPF Wiki

1. Start the InstantRails Manager (InstantRails.exe) and select I > Rails Applications > Manage Rails Applications
2. Check EPFWiki in the list and select Start With Mongrel
3. Start an Internet Browser and navigate to your EPF Wiki application e.g. http://myepfwiki. If you get an error about LIBMYSQL.dl, see the notes at the bottom of this page

The application should display a form where you can create the first user. This user will become the main administrator (most privileged account). To create this account you have to provide a name, email and a password.

Troubleshooting

If Mongrel fails to start, start it from the command line:

1. Start the InstantRails Manager (InstantRails.exe) and select I > Rails Applications > Create New Rails App
2. cd to the folder EPFWiki
3. Type set RAILS_ENV=production
4. Type ruby script/server

Add the Scheduled Tasks

EPF Wiki assumes that default four Scheduled Tasks will be created, three for reporting (daily, weekly and monthly) and one for creating and updating Wikis.

The Scheduled Tasks should run from the EPF Wiki Application root e.g. C:\InstantRails2.0\rails_apps\EPFWiki and we schedule it to run a bat file with the same name.

In the Run field of the tasks we use the following entries:

• job_daily_report.bat
• job_weekly_report.bat
• job_monthly_report.bat
• job_daily.bat

Each bat file runs the corresponding EPF Wiki job:

• ruby script/runner -e production 'job_daily_report'
• ruby script/runner -e production 'job_weekly_report'
• ruby script/runner -e production 'job_monthly_report'
• ruby script/runner -e production 'job_daily'

For the first three the timing of the task is important, of course. You want those tasks to run just after the period. So, for example, you would run the weekly report Monday morning. If you run it on Sunday it will report changes for the previous week.

Example bat file:

call ../../use_ruby.cmd
cd EPFWiki
ruby script/runner -e production 'job_daily'

Notes

InstantRails

"Instant Rails is a one-stop Rails runtime solution containing Ruby, Rails, Apache, and MySQL, all pre-configured and ready to run. No installer, you simply drop it into the directory of your choice and run it. It does not modify your system environment.". See InstantRails Site for more information.

The procedure entry point mysql_stmt_row_tell could not be located in the dynamic library LIBMYSQL.dll

This is a known issue when using IntstantRails 2.0. Look for it on the internet. A quick workaround is to add LIBMYSQL.DLL to the ruby/bin directory. This DLL can be found in the MySQL bin directory.

Creating a Demo, Test Environment without SMTP server

If you follow this instruction to create an environment for non-production use and you don't have a SMTP server available, you should disable the use of the SMTP server. Add the line config.action_mailer.delivery_method = :test to the configuration file for the production environment production.rb which is located in the folder config/environments.

Alternatively you can follow this instruction and use test where the production environment is mentioned e.g. test.rb instead off production rb and so on. That would be the preferred approach.

Page not found trying to start a Wiki

EPF Wiki uses path such as http://myepfwiki/wikis/rm/ to start the Wiki site. The web server is configured to look for index.html but EPFC uses index.htm. When using InstantRails you cannot simply fix this by changing the DirectoryIndex directive. This has no effect because Apache is used only as a proxy server. The problem is caused by the Mongrel server.

This behaviour is not configurable with Mongrel. See the workaround.

Searching for: index.html
examples\httpd.conf(174): DirectoryIndex index.html
examples\httpd.conf(448): RewriteRule ^/$ /index.html [QSA] 
lib\mongrel\handlers.rb(121): def initialize(path, listing_allowed=true, index_html="index.html")
test\test_handlers.rb(63): "http://localhost:9998/files/rdoc/index.html",
Found 4 occurrence(s) in 3 file(s)