Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Tree: 9885adc8f8
Fetching contributors…

Cannot retrieve contributors at this time

347 lines (240 sloc) 14.4 kB

Welcome to EPF Wiki

EPF Wiki is Wiki technology designed to be used together with Eclipse Process Framework (EPF). This offers the best of two distinct worlds: the worlds of powerful process frameworks and Wikis. It offers an process engineering infrastructure that combines a modular method construction approach and the flexibility and ease of use that is the defining characteristic of a Wiki.

EPF Wiki is technology built on top of Ruby on Rails that adds Wiki features to the hypertext process descriptions created with EPF Composer.

This release of EPF Wiki is a fork of EPF Wiki 1.5 as was released by the Eclipse Process Framework (EPF) project. It is now maintained here on Github as 'edge' version, so the current master branch of EPF Wiki which will refer to as Edge EPF Wiki.

Getting Started

This remainder of this document describes how to install EPF Wiki on Ubuntu Server 10.04 LTS 32-bit using Apache2 and Phusion Passenger (a.k.a mod_rails). If you want to upgrade your existing EPF Wiki installation, there is a instruction on the Eclipse Wiki.

If you have any questions about this guide or EPF Wiki please use the Eclipse Process Framework Project Developers List. Or you can of course create Github issues if you have an account. More information on EPW Wiki can be found in the EPF Wiki User Guide.

Ubuntu Server 10.04 LTS 32-bit

Download and install Ubuntu server. Install the following options for your convenience

  • OpenSSH server

  • Samba file server

You can easily create EPF Wiki as a virtual applicance using for example VirtualBox using the instructions in this document. This is the recommended approach for using EPF Wiki.

When you enable bridged networking this will allow easy access to EPF Wiki box for administration tasks. Also you can access EPF Wiki from anywhere on the network. The command ifconfig will show the IP address that is assigned to the machine on your network. After that you can easily creat http, ssh or sftp connections to the machine. To activate changes do sudo /etc/init.d/networking restart

Rails Ready

Execute the following commands to install the key components using Rails Ready

wget --no-check-certificate https://github.com/joshfng/railsready/raw/master/railsready.sh 
bash railsready.sh

After this script finished you add the following entry to the .bash_profile. This is an omission in the Rails Ready script that will be fixed in time. You can edit the file using vi or nano. Or any other editor if you edit the file from the desktop of you choice on the network.

Open this file

vi .bash_profile

Add the following entry

[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm" # Load RVM into a shell session *as a function*

Logout and login and check if you have Ruby, RVM and Rails working, for example

ostraaten@epfw-vbox:~$ ruby -v
ruby 1.9.2p290 (2011-07-09 revision 32553) [i686-linux]
ostraaten@epfw-vbox:~$ rails -v
Rails 3.0.9
ostraaten@epfw-vbox:~$ rvm -v
rvm 1.6.32 by Wayne E. Seguin (wayneeseguin@gmail.com) [https://rvm.beginrescueend.com/]

For almost all if not all purposes Rails Ready will suffice but if your requirements for this EPF Wiki server go further you might want to take a look at Rails Ready Ready as well.

MySQL

Open a terminal window to install MySQL client and server. Provide the recommended root password when you are prompted for it.

sudo apt-get install mysql-client mysql-server

EPF Wiki

You can now use git clone to get Edge EPF Wiki on your box.

git clone https://github.com/ostraaten/epfw.git

This command creates folder epfw which we will refer to as the EPF Wiki root. Now we install all EPF Wiki specific Ruby gems using the new gem tool bundler with a single command bundle install:

cd ~/epfw
bundle install

Next we create a MySQL user

mysql -u root -p
create user 'epfwiki'@'localhost' identified by 'ikiwpur';
grant all privileges on *.* to 'epfwiki'@'localhost';
grant usage on *.* to 'epfwiki'@'localhost';

You can check the resulting privileges of this MySQL user with

show grants for 'epfwiki'@'localhost';

You exit the MySQL console with exit. Now create a database configuration file for your installation

cd ~/epfw/config
cp database.yml.example database.yml

If necessary change the database settings in you configuration file database.yml to match your MySQL server setup. But if you created the MySQL database exactly as was described above you can skip the following step.

vi config/database.yml

If you want to use a different editor than vi you can also open the configuration files from another computer that has a different editor. From a different desktop computer that is running plain Ubuntu you can for example browse, open, edit and save the config files by using nautilus:

nautilus sftp://ostraaten@192.168.1.42/home/ostraaten/epfw/config

Now you can create the database and database schema

cd ~/epfw
rake db:create db:migrate RAILS_ENV=production

If this command fails with message that constants are initialized multiple times this is caused by the presence of a folder ruby-1.9.2-p290@global in the gems directory. You can remove this directory and try again

rm -r ~/.rvm/gems/ruby-1.9.2-p290@global

Environment configuration file

Create the environment configuration file using the template

cd ~/epfw/config/environments
cp production.rb.example production.rb

Edit the file

vi production.rb

There are two environment variables you want to consider changing

ENV['EPFWIKI_APP_NAME'] = 'EPF Wiki'
ENV['EPFWIKI_REPLY_ADDRESS'] = "no-reply@epf.eclipse.org"

Then there is a variable that you need to change. EPF Wiki uses jobs to send reports and update Wiki sites. Such a job is or course 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.

ENV['EPFWIKI_HOST'] = "localhost" # used for jobs, when there is no host variable in the environment

Replace ENV['EPFWIKI_HOST'] = "localhost" with the right hostname e.g. ENV['EPFWIKI_HOST'] = "myepfwiki". You have include a port number if you are not using the default port 80 e.g. ENV['EPFWIKI_HOST'] = "myepfwiki:8080"

Email

If you don't change the default email settings, EPF Wiki will try to use sendmail. But there is also the option of using SMTP or to use 'no' email.

cd ~/epfw/config/initializers
cp setup_mail.rb.example setup_mail.rb

For SMTP add a entry similar to the one below to setup_mail.rb

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 want to use email setup_mail.rb should have the following entry

ActionMailer::Base.delivery_method = :test

Apache2 and Phusion Passenger (aka mod_rails)

Install Apache2

sudo apt-get install apache2

Some extra Apache bits For Phusion Passenger

sudo apt-get install apache2-prefork-dev libapr1-dev libaprutil1-dev

Phusion Passenger is installed with the following command. The command will output some vital Apache2 configuration for you environment that you want to take note of. Copy paste it somewhere as it will be needed to configure Apache2.

passenger-install-apache2-module

Depending on the current version of Ruby and Passenger the command outputs something like

LoadModule passenger_module /home/ostraaten/.rvm/gems/ruby-1.9.2-p290/gems/passenger-3.0.8/ext/apache2/mod_passenger.so
PassengerRoot /home/ostraaten/.rvm/gems/ruby-1.9.2-p290/gems/passenger-3.0.8
PassengerRuby /home/ostraaten/.rvm/wrappers/ruby-1.9.2-p290/ruby

And something like

<VirtualHost *:80>
   ServerName www.yourhost.com
   DocumentRoot /somewhere/public    # <-- be sure to point to 'public'!
   <Directory /somewhere/public>
      AllowOverride all              # <-- relax Apache security settings
      Options -MultiViews            # <-- MultiViews must be turned off
   </Directory>
</VirtualHost>

Open ports configuration file

sudo nano /etc/apache2/ports.conf

And add the following entry above the *:80 NameVirtualHost configuration:

NameVirtualHost *:3000
Listen 3000

Open Apache2 configuration file

sudo nano /etc/apache2/sites-enabled/000-default

Add for example the following to this file

LoadModule passenger_module /home/ostraaten/.rvm/gems/ruby-1.9.2-p290/gems/passenger-3.0.8/ext/apache2/mod_passenger.so
PassengerRoot /home/ostraaten/.rvm/gems/ruby-1.9.2-p290/gems/passenger-3.0.8
PassengerRuby /home/ostraaten/.rvm/rubies/ruby-1.9.2-p290/bin/ruby
<VirtualHost *:3000>
  ServerName localhost
  DocumentRoot /home/ostraaten/epfwiki/public    
</VirtualHost>

The entry above shows the localhost as the server name. Assuming you are using EPF Wiki as a virtual appliance you will be using the assigned IP address to access it from other machines on the netwerk. How to assign a proper domain name is not described in this document. Also the paths depend on the passenger version as you can see above. The above configuration assumes you have 3.0.8 installed.

Make sure the settings match your environment. You can always retrieve this information with the following commands:

which ruby
gem environment

Restart Apache2

The Apache2 configuration is now finished. Restart apache to activate changes

sudo /etc/init.d/apache2 restart

After restart you should be able to see EPF Wiki when you navigate to your-ip-address:3000.

You should now see the form for creating the administrators account. It is recommended to do that now because anyone that accesses that resource can create the first account. But the installation is not finished untill you complete the remaining steps.

Tidy

Install HTML Tidy. This is used for cleaning up HTML so that nice visual difference analysis of versions of pages that have been edited in the Wiki.

sudo apt-get install tidy

Test that it is working

~/epfw$ tidy -v
HTML Tidy for Linux/x86 released on 25 March 2009

HTML Editor (TinyMCE)

Download TinyMCE from tinymce.moxiecode.com. EPF Wiki was confirmed to work with versions 3.2.0.2 and 3.4.4. Extract the contents and copy the folder tinymce/jscripts/tiny_mce to epfw/public/javascripts.

Install unzip utility

sudo apt-get install unzip

Unzip and install TinyMCE in the EPF Wiki root directory ~/epfw

cd ~/Downloads
unzip tinymce_3.4.4.zip
cp -r -u tinymce/jscripts/tiny_mce/ ~/epfw/public/javascripts

The folder javascriptstiny_mce should now contain the TinyMCE Javascript libraries for example tiny_mce.js

ostraaten@epfw-vbox:~$ ls ~/epfw/public/javascripts/tiny_mce/
langs	     plugins  tiny_mce.js	 tiny_mce_src.js
license.txt  themes   tiny_mce_popup.js  utils

Jobs

There are now two rake --tasks that you need to schedule as Cron jobs.

To update Wikis with new baselines

rake epfw:update RAILS_ENV=production

To send the daily, weekly, monthly reports

rake epfw:reports RAILS_ENV=production

The task epfw:reports should only run 'once' each day, at the end of the working day. It will send the daily report and, depending on the day of the week or month, also a weekly and/or monthly report. The task epfw:update can run multiple times a day but you should enough time for it to complete a job. When those jobs overlap things get messy. The jobs should run from the EPF Wiki root

The following command is used to create cron jobs

crontab -e

You can use an online tool Crobtab Generator to generate the exact command to enter.

A command like the following updates the wiki with new baselines

cd ~/epfw && rake epfw:update RAILS_ENV=production

The crontab entry that runs a job each night 20:00 hours would be

* 20 * * * cd ~/epfw && rake epfw:update RAILS_ENV=production

Crontab entry to do the update 'and' send the reports

* 20 * * * cd ~/epfw && rake epfw:update epfw:reports RAILS_ENV=production

Crontab entry to do updates every hour

0 * * * * cd ~/epfw && rake epfw:update RAILS_ENV=production

Troubleshooting

If things are not working as expected EPF Wiki will send emails to the administrator with more information. If these emails do not contain information to fix the problem it is necessary to look in the log files of Rails and then of Apache 2.

The Rails log file is ~/epfw/log/production.log. The Apache2 log files can be found in the directory /var/log/apache2.

Update and/or restart EPF Wiki

Logon the machine do a git pull and then touch the restart.txt file to restart EPF Wiki

cd ~\
git pull
touch tmp\restart.txt

License

Copyright © 2006 Logica, 2008 IBM, and others

All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at www.eclipse.org/legal/epl-v10.html

Contributors:

  • Onno van der Straaten - initial implementation and upgrade to Rails 3

  • Ricardo Balduino - additions for feed generation (practices and UMA types)

Jump to Line
Something went wrong with that request. Please try again.