EPF Wiki Installation Guide

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 forthcoming.

If you have any questions about this guide or EPF Wiki please use the Eclipse Process Framework Project Developers List. Install sources can be found on the EPF Downloads page.

Previous versions of this guide:

• EPF Wiki Installation Guide for version 1.5 RC 1

More information on EPW Wiki can be found in

1. EPF Wiki User Guide
2. EPF Wiki Development Guide

If you are using release 1.5 RC 1 and you want to upgrade, see the EPF Wiki R1.5 Patch

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.

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 EPF Wiki install sources from EPF Downloads 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

To integrate TinyMCE with EPF Wiki:

1. Download TinyMCE 3.2.0.2 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

---

The 1.5 release uses TinyMCE 3.2.0.2 but the first release candidate for the 1.5 release uses TinyMCE version 2.0.8 and 2.1.3. These TinyMCE versions are not compatible. If you are upgrading your installation, see EPF Wiki R1.5 Patch

---

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.epf.eclipse.org",
 :port  => 25, 
 :domain  => 'epf.eclipse.org',
} 

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 Task

Create a Scheduled Task job_daily. This job will send reports (daily, weekly, monthly) and will update Wiki sites if updates have been scheduled. It 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 name job_daily.bat with the following contents:

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

This job should run at night or at when ever your site is used the least.

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.

Running multiple instances of EPF Wiki

The following section describes the basic steps involved when you want to run multiple instances of EPF Wiki using InstantRails. Such instances are completely seperate, which could be useful for instance for create a demo, training, test or staging environment. These instances are accesible via different ports. Of course you could also use different domain names for each environment.

1. Create multiple application directories in the rails_apps directory (for example create folders named EPFWiki_production EPFWiki_demo).
2. Create multiple database, one for each instance
3. Edit the database.yml files in each EPF Wiki directory to match the created databases
4. Start InstantRails manager and select I > Rails Applications > Manage Rails Applications
5. Press Refresh List
6. Check the first EPF Wiki application and press Configure Startup Mode
7. Specify runtime mode and port, for example production and 3003
8. Press Edit Apache config file
9. Add listen and virtual host directives for each port you want to use, see example below
10. Repeat step 7 for each environment
11. select I > Rails Applications > Manage Rails Applications, check all EPF Wiki boxes and press Start with mongrel

Example snippet Apache config file

...
listen 80
listen 81
...
<VirtualHost *:80>
    ServerName myepfwiki
    ProxyPass / http://localhost:3003/
    ProxyPassReverse / http://localhost:3003
</VirtualHost>

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