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.
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.
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
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.
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
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
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"
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
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
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.
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
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
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.
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
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)