Difference between revisions of "EPF Wiki Installation Guide"

Revision as of 09:11, 11 July 2012

This guide describes how to install EPF Wiki on Windows with IIS Express. As IIS Express is a IIS release for developers, this describes the creation of a 'development' environment. But this guide could also be used for creating a production environment, the basic steps remain the same. Note however that he recommended production environment for Rails (and so for EPF Wiki) is Linux/Ubuntu, see EPF Wiki Installation Guide for Ubuntu.

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

More on information on EPF Wiki in in the EPF Wiki User Guide.

Requirements

This guide assumes you will use a current version of IIS of IIS Express. This guide is based on IIS 7.5 Express. First and foremost requirements for IIS apply. This installation guide was tested using Windows Virtual PC VHD which can be used freely for 90 days. And then you will need the following:

• EPF Wiki 1.6
• .Net Framework Version 4.0
• UnxUtils
• MySQL Server 5.5

For your convenience most of the install files can be found in one location on Dropbox

Install Utilities

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>

Install IIS 7.5 Express

.Net Framework Version 4.0

Required for IIS. Download and install dotNetFx40_Full_setup.exe

WebMatrix

Microsoft WebMatrix is a free, all-in-one, extensible web development application for Windows, developed by Microsoft. This will also install Web Platform Installer (WPI) by Microsoft. You can install from the Microsoft site using the following link: Install Microsoft WebMatrix.

Helicon Zoo

Helicon Zoo is a repository of web frameworks and applications for Microsoft IIS. We use this the Ruby Hosting Package and the WebMatrix Templates. These components are installed using WPI

• Start WPI. I use wpilauncher_3_10.exe, you can find this executable on Microsoft site or the Dropbox folder.
• Select Options
• Enter the Helicon Zoo feed http://www.helicontech.com/zoo/feed/ and select Add feed and OK.
• You should now see a tab Zoo. Select that and Add the following components
  • Ruby Hosting Package
  • WebMatrix Templates

File:Wpi-change-options.png

Install MySQL Server 5.5

Installation of MySQL is beyond scope of this document but for the record. I used mysql-5.5.24-win32.msi. With Typical as the setup type. Standard Configuration as the configuration type. Installed as Windows Service and I included bin directory in Windows PATH.

Install EPF Wiki

Create Empty Site

Start WebMatrix and select Site From Template. Select Rails Site and enter EPFW as site name. On OK this should create a URL and location for our application. You can follow the URL and see a message that a new empty site has been created. The empty site will be configured to run a development environment. Unless you want to create an actual development environment, it is recommended (for performance reasons) to configure it to run as a production environment.

Edit the file web.config and change RACK_ENV

<add name="RACK_ENV" value="development" />

to

<add name="RACK_ENV" value="production" />

Note: is you are creating an environment using IIS and you don 't have access to WebMatrix, you can't perform this step. In that case you can download epfwiki_r1_6_20120710_2140_IIS_site_template.zip from [1].

Download and Install

Download epfwiki_r1_6_20120710_2140.zip from downloads and extra the content to the location created in the previous step. Overwrite any existing files and folders.

production.rb

In EPF Wiki folder you might want to edit the configuration file for the production environment production.rb. At this point the three three configuration settings at the are the most important.

 ENV['EPFWIKI_APP_NAME'] = 'EPF Wiki'
 ENV['EPFWIKI_REPLY_ADDRESS'] = "no-reply@epf.eclipse.org"
 ENV['EPFWIKI_HOST'] = "localhost" # used for jobs, when there is no host variable in the environment

The no-reply address is rendered in every email as the from address.

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. Note: include a port number if you are not using the default port 80 e.g. ENV['EPFWIKI_HOST'] = "myepfwiki:8080"

Bundle Install

Via Start > All Programs > Ruby 1.9.3-p0 > Start Command Prompt with Ruby. Navigate to the application folder and enter bundle install

MySQL Connector/C

bundle install at the outputs a message similar to below, with instructions to download and put libmysql.dll in Ruby bin directory. I downloaded my version of the connector mysql-connector-c-noinstall-6.0.2-win32.zip from dev.mysql.com downloads.

 ======================================================================================================
 
   You've installed the binary version of mysql2.
   It was built using MySQL Connector/C version 6.0.2.
   It's recommended to use the exact same version to avoid potential issues.
 
   At the time of building this gem, the necessary DLL files where available
   in the following download:
 
   http://dev.mysql.com/get/Downloads/Connector-C/mysql-connector-c-noinstall-6.0.2-win32.zip/from/pick
 
   And put lib\libmysql.dll file in your Ruby bin directory, for example C:\Ruby\bin
 
======================================================================================================

Create the MySQL Database User

From the same command prompt window as used in the previous step you can now create the MySQL Database User Account.

1. In the Command Prompt logon to MySQL as root
2. Create the user epfwiki with the password ikiwpur.
3. Grant privileges and usage to this database user.

Of course you can use a different database user and password, you should change the database config file config/database.yml accordingly.

Example:

C:\Users\Administrator\Documents\My Web Sites\EPFW>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'@'localhost' identified by 'ikiwpur';
Query OK, 0 rows affected (0.08 sec)

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

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

database.yml

Edit the database configuration file config/database.yml. Make sure that the production entry matches your username and password from the previous step.

production:
  adapter: mysql2
  database: epfwiki
  host: 127.0.0.1
  username: epfwiki
  password: ikiwpur
  encoding: utf8

Create the database schema

Start Command Prompt with Ruby as in previous step and navigate to the application folder. Issue the following commands to create the database schema.

 set RAILS_ENV=production
 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:\Users\Administrator\Documents\My Web Sites\EPFW>set RAILS_ENV=production
C:\Users\Administrator\Documents\My Web Sites\EPFW>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:\Users\Administrator\Documents\My Web Sites\EPFW>

Configure EPF Wiki

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 do this edit the file config/initializers/setup_mail.rb. Change the file to match your SMTP server settings. An example for the Gmail SMTP server is

 ActionMailer::Base.smtp_settings = {  
   :address              => "smtp.gmail.com",  
   :port                 => 587,  
   :domain               => "epf.eclipse.org",  
   :user_name            => "onno.van.der.straaten@gmail.com",  
   :password             => "****",  
   :authentication       => "plain",  
   :enable_starttls_auto => true  
 }

If you don't have a SMTP server you could also use the following line in that file. That way you can use EPF Wiki without error messages being generated. In the log file log/production.log you will find extracts of email message send. There you should be able to find for example the sign up links send to users to create an account.

 ActionMailer::Base.delivery_method = :test

Start EPF Wiki

You can now restart EPF Wiki for the changed settings to take effect. Start WebMatrix and restart. If you see a message that MySQL could not connect to 'localhost', you have to restart some more or even reboot maybe for WebMatrix to pick up the changed configuration.

After restart navigate to EPF Wiki by clicking the URL link displayed in WebMatrix. This should then show the screen to create the administrator account.

File:You-there.png

If this is not the case, the first thing to do is to check the log file log/production.log for any clues on what is going wrong.

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.