EDGE: Engineering Design Guide and Environment
/public/

System Setup

Table of Contents

28 Feb 2012 RIT CAMPUS ONLY

THESE INSTRUCTIONS ARE CURRENTLY UNDER REVISION AND ARE INCOMPLETE

PLEASE MAKE NOTE OF ERRORS, OMISSIONS, OR AMBIGUITIES

Introduction

This guide is meant to help you install EDGE on your server. There will be three stages to this guide. The first will be pre-installation, where all necessary components to run EDGE will be installed and configured. The second will be installation where EDGE is installed and configured. The third stage is post-installation, where some testing and setup is completed.

Stage 1. Pre-Installation

EDGE uses the LAMP stack (Linux, Apache, MySQL, and PHP), SSL, Subversion, LDAP, and DAV. This guide will show you how to install and configure these.

You will need to create several passwords during this installation process. The table below may server as a convenient method for you to temporarily tracks these passwords during the installation process.

Passwords Used During Installation
Purpose of Username Username Default Password

associated with this username

Local Password

for your installation

EDGE DatabaseMetaUser edgeuser <edgeuserpassword>
EDGE System Administrator edgeadmin <edgeadminpassword>
MySQL Database Administrator root (for mysql) <mysqladminpassword>
SSL Option 1

SSL Option 2

SSL Certificate Pass Phrase <sslpassphrase>

Operating System

This guide assumes that you are running a recent version of UBUNTU (It has been tested through Version 9.04) or a similar distribution or version of a Debian Linux operating system. This guide is not guaranteed to work will all Debian based distributions because packages may have different names or may not exist for a particular distribution.

You can download an image to create an installation CD from a mirror through www.ubuntu.com

The following process assumes that you have installed the basic operating system from the CD, but nothing else.

Installing LAMP and Other Required Packages

We can download and install the necessary packages with the following command: 

sudo apt-get install apache2 php5 libapache2-mod-php5 php5-cgi libapache2-mod-fcgid mysql-server libapache2-mod-auth-mysql subversion libsvn-perl libapache2-svn php-pear php5-tidy php5-gd php5-mysql websvn smarty openssh-server

During installation you will need to create a root password for the MySQL server.

Enter your choice for <mysqladminpassword> from the table above.

You will also be prompted to set up websvn.
Say "no" to setting up the websvn server.
Say "ok" to the message that follows that.

At this point, your Apache webserver is installed and should be running. Open a web browser, and navigate to http://localhost/.

You should see a simple web page that says "It Works!"

Install Apache 2 Modules

EDGE uses a couple apache modules for some of its services. The easiest way to enable this is with the following command: 

sudo a2enmod alias authz_host dav_svn negotiation auth_basic authz_user auth_mysql autoindex dir php5 authn_anon cgi env rewrite authn_file setenvif authnz_ldap dav_fs fcgid authz_default dav ldap ssl authz_groupfile mime status
Now we need to restart apache so the modules will be loaded. Use this command: 
sudo /etc/init.d/apache2 restart

Creating an SSL Certificate

EDGE uses an Apache Secure Socket Layer (SSL) for secure communications. For this to work, Apache needs a signed certificate. There are two options:

SSL Option 1
Generate a certificate signing request and have a certificate authority sign your certificate. This is appropriate for any type of production system, or where the server will be publicly available.
SSL Option 2
Generate a self-signed certificate. This is appropriate for a development or testing system, or if your server is only available on a closed network.

Creating a Certificate Signing Request

Note: Perform these steps for BOTH SSL Option 1 and SSL Option 2.

First we are going to go to the apache2 folder and make a directory for our ssl public and private keys. Use the following commands: 

cd /etc/apache2/
sudo mkdir ssl
cd ssl/
Now we need to generate our private key. Use the following command: 
sudo openssl genrsa -aes128 -out server.key 1024
You will need to enter a <sslpassphrase> for your key. Next, we must generate a certificate signing request. Use the following command: 
sudo openssl req -new -key server.key -out server.csr
You will need to re-enter the same <sslpassphrase> you used in the previous step. Then you will be asked to fill out some information about your site. Most of these fields have a default or are optional.

SSL Option 1 Only

At this point you may submit the certificate signing request to a certificate authority, and follow their instructions.

SSL Option 2 Only

Generating a Self-Signed Certificate

Next we want to remove the pass phrase from our key so that we do not have to enter it each time apache starts. We can do this with the following: 

sudo cp server.key server.key.org
sudo openssl rsa -in server.key.org -out server.key
You will need to re-enter the same <sslpassphrase> you used in the step where you generated the private key.

Next we want to generate our certificate (public key). 

sudo openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

MySQL Setup

Now we are going to setup MySQL, the database that EDGE uses. We'll start by opening the MySQL command prompt. In the terminal type: 

mysql -u root -p
You will be prompted to enter the <mysqladminpassword> you setup when you installed the mysql package. Once you have entered your password you will be in the mysql prompt. First, we need to create the main database that edge will use. Do this by entering: 
create database edgedb default character set utf8;
Next, we need to create two users for the database. One, edgeuser, is a metauser that will be used by the EDGE programs. The second, edgeadmin, is a username that you can use to administer the system later on: 
grant all on edgedb.* to 'edgeuser'@'localhost' identified by '<edgeuserpassword>';
grant all on *.* to 'edgeadmin'@'localhost' identified by '<edgeadminpassword>';
Now you can exit the mysql prompt by typing: 
exit;

PHP Setup

Now we are going to install some pear packages for php5. First we're going to update the pear channel: 

sudo pear channel-update pear.php.net
EDGE uses some packages which are alpha and beta, which pear doesn't allow you to install by default, so we need to change the configuration: 
sudo pear config-set preferred_state alpha
Now we can install all the pear packages necessary: 
sudo pear install Archive_Tar Cache_Lite Console_Getopt DB_Table HTML_Common HTML_QuickForm HTML_Table Image_3D Image_Barcode Image_Canvas Image_Color Image_Color2 Image_GIS Image_Graph Image_GraphViz Image_IPTC Image_MonoBMP Image_Remote Image_Text Image_Tools Image_Transform Image_XBM MDB2 MDB2_Driver_mysql MIME_Type Numbers_Roman PEAR PHP_Compat Pager PhpDocumentor Structures_Graph Text_Wiki Text_Wiki_Doku Text_Wiki_Mediawiki VersionControl_SVN XML_Parser XML_SVG XML_Util
Now we're going to set pears config back to stable because its generally not a good idea to install alphas or betas. 
sudo pear config-set preferred_state stable

Now we need to modify the php.ini file. First go to the php5 config directory: 

cd /etc/php5/apache2
Now open the php.ini file with root access (eg. sudo gedit php.ini). In the file change: 
;arg_separator.output = "&amp;"
To: 
arg_separator.output = "&amp;"
And: 
magic_quotes_gpc = On
To: 
magic_quotes_gpc = Off

SVN Setup

Subversion is an open source document control system used by EDGE. We need to create a directory that will be used by subversion for storing all of the project information. Note that these repositories may get quite large, so you will want to insure that the /var directory is on a large hard disk for a production system. If you are just doing development, then the disk size is not critical.

First, let's make the direcotry where the repositories from EDGE will be stored. 

cd /var
sudo mkdir /var/svn-repos

Now, create a user group called 'svn' that the subversion system SVN, EDGE, WebSVN, and Apache can all share. Next, add the metauser 'www-data' that is used by the default Apache server as a member of group 'svn'. Third, change the ownership of the newly created directory tree to www-data, with svn group access. Finally, provide read+write+execute access to this directory tree for the owner 'www-data' and group 'svn' while disallowing all access for the 'world'. 

sudo groupadd svn
sudo addgroup www-data svn
sudo addgroup <linuxusername> svn
sudo chown -R www-data:svn /var/svn-repos/
sudo chmod -R 770 /var/svn-repos/

You will need to log out, and then log back in, to make the group addition take effect for <linuxusername>.

WebSVN Setup

WebSVN is an open source package used by EDGE for convenient web based access to the EGE project subversion repositories. We need to set it up now. 

sudo dpkg-reconfigure websvn
You will be prompted five times during the reconfiguration. Please respond as follows:
Prompt 1
select 'yes', then press the enter key
Prompt 2
press the enter key
Prompt 3
enter '/var/svn-repos/' in the box, and then press the enter key
Prompt 4
clear the text in the box so that it is an empty field and then press the enter key
Prompt 5
select 'ok', then press the enter key

Stage 2. Installation

Create a Working Location

For this section, assume that you are logged into your computer, with sudo privileges, as <username>. Throughout these instructions, replace <username> with your own username. Replace <usernamepassword> with your DCE password that has been authorized to grab an EDGE distribution. The first step is to create a temporary directory when we can download some files for setup. 

cd ~
mkdir temp
mkdir sandbox
cd temp

cd /var
sudo mkdir local-repos

Get the distribution

At this time, you will need to authenticate with a valid RIT DCE user account <username> and <usernamepassword> in order to export the distribution. When we eventually go to full open source, then we should cease to require authentication, or at least not have it be restricted to RIT users.

First. we grab some data files. 

cd ~/temp
svn export https://designedge.rit.edu/dav/EDGE/web/public/distribution/edgedb.sql edgedb.sql
svn export https://designedge.rit.edu/dav/EDGE/targetroot targetroot

Next, let's get the executable code. 

cd /usr/share
sudo svn checkout https://designedge.rit.edu/dav/EDGE/targetroot/usr/share/edge edge --username <username> --password <usernamepassword> 
cd edge/inc
sudo cp config.tmpl config.inc
sudo nano config.inc

Next, let's get the scripts and help information for both EDGE and FACETS. These will be setup as checkouts, so that they can be maintained remotely, and updates pushed out to the servers nightly. 

cd /var/local-repos
sudo svn checkout https://designedge.rit.edu/dav/EDGE EDGE
sudo svn checkout https://designedge.rit.edu/dav/FACETS FACETS

Extract the distribution

We'll make some temporary directories to hold our work. Then, load the dump files into our repository, to begin our local service. Next, export files from our repository back into our working directory, and then copy the files from the temp location into their final destination on our server. The files in /usr/share/edge represent the actual software package of EDGE. The files in /var/svn-repos contain three shell scripts to connect edge with subversion, and the access control list file used to control who can read what in the subversion repositories. Finally, the files in /etc/apache2/sites-available will be used to let the apache server know about our edge service. 

sudo cp -R ~/temp/targetroot/var/svn-repos/* /var/svn-repos/.
sudo cp -R ~/temp/targetroot/var/svn-repos/.htpasswd /var/svn-repos/.htpasswd
sudo cp -R ~/temp/targetroot/etc/apache2/sites-available/* /etc/apache2/sites-available/.

Now, let's make sure all of the file permissions are set properly. Execute several commands: 

sudo chmod 744 /var/svn-repos/repos_create
sudo chmod 744 /var/svn-repos/repos_delete
sudo chmod 744 /var/svn-repos/repos_write
sudo chmod 770 /var/svn-repos/SVN_ACL
sudo chmod 644 /var/svn-repos/.htpasswd
sudo ls -l /var/svn-repos/

Read through the directory listing to insure that repos-create, repos-delete, and repos-write have group and world READ privileges set. Also, verify the ownership of the repositories, recursively. You may want to check the ownership of any other repositories that you chose to install at setup time in the same way (if you installed any other repositories using 'svnadmin load' in the instructions above).

Load MySQL Tables and Initial Data

All of the data tables and a limited amount of start-up configuration data can be loaded into the edge table for MySQL using the commands below. As usual, replace <username> with your own username. 

cd ~/temp/
sudo  mysql -u root edgedb -p < edgedb.sql

You may be prompted for your <username> sudo password, and then you will be prompted for your <mysqladminpassword>.

Customize EDGE for our server

Customize edge config.inc 

cd /usr/share/edge/inc

Open config.inc in an editor with root access (eg. sudo nano config.inc. Replace the <edgeuserpassword> with the password that you created during the pre-installation process. 

$EDGEUSERPASSWORD  = '<edgeuserpassword>';
Next, we set up the EDGE and FACETS projects as local checkouts, by making sure that the following lines are active in config.inc 
  'local_project' => array( 
     'EDGE' => '/var/local-repos/EDGE',
     'FACETS' => '/var/local-repos/FACETS',
   ),

Now, we need to set the password in the flat file used by Apache, which bypasses RIT LDAP authentication: 

sudo htpasswd /var/svn-repos/.htpasswd edgeuser
sudo htpasswd /var/svn-repos/.htpasswd edgeadminuser

when prompted, please enter the <edgeuserpassword> and the <edgeadminpassword> that you created earlier. 

cd /usr/share/edge/templates/
sudo nano /usr/share/edge/templates/navbar.tpl 
   REPLACE  <h2>Blue EDGE Installation</h2>
   WITH     <h2>YOUR SERVER HERE</h2>
you may also replace the logo file here if you wish.

Modify the PEAR media-wiki Package

I really think this is an issue that should be resolved in a near term EDGE release. I don't like the current approach, and certainly it is not desirable for the long term.

When EDGE was first developed, Brian Sipos reworked a lot of media wiki to interface with the repositories, to the extent that It may not really be the original media wiki any longer. we may want to give it a derivative name as an alternative pear package like EDGE_Wiki instead of Text_Wiki or something as we move towards deployment. Until that portion of development is completed, we need to replace the standard PEAR package with the locally modified variant.

Use the command "locate PEAR.php", to find the installation directory for php, which is usually /use/share/php . Once you know the correct location, you can proceed with over-writing the standard package, as follows:

Step 1

Save a copy of the actual media wiki PEAR package that was installed above... 
cd /usr/share/php
sudo mv Text OriginalPEARText

Step 2

Now, overwrite the standard media wiki PEAR package with the locally modified version from the repository 

sudo cp -R ~/temp/targetroot/usr/share/php/Text /usr/share/php/.

This will enable local wiki node entering through the GUI. Failure to do this operation will yield a viewable EDGE setup , but will preclude users from using the GUI to interactively edit wiki pages.

Let's set some file ownership and permissions: 

sudo chown www-data:svn /usr/share/edge/inc
sudo chown www-data:svn /usr/share/edge/inc/*.*
sudo chmod 660 /usr/share/edge/inc/*.*

Customize Apache for our Sites

Now we will set up our sites. We will have two, one for http (non-secure) and another for https (secure). First, go to the apache folder: 

cd /etc/apache2/

Disable the Default Apache site

We're going to disable the site that was enabled by default when apache2 was installed: 

sudo a2dissite default

Now we're going to customize the setup files from our distribution. 

cd /etc/apache2/sites-available/
ls
You should see two files, edge-http and edge-https in the listing.

Customize edge-http 

cd /etc/apache2/sites-available/

Open edge-http in an editor with root access (eg. sudo gedit edge-http).

You will want to replace the entries in <trianglebrackets> with the name of your server and domain. If you are just doing development on a local machine, you can use localdomain and localhost.localdomain for the ServerDomain and ServerName, respectively. 

   # Replace <DomainName> in the line below with your organization such as: acme.com
   #  ServerDomain <DomainName>
   # Replace <localhost> in the line below with your computer such as: edge.acme.com
     ServerName  localhost
For example: 
ServerName edge.rit.edu

Now save and close edge-http.

Customize edge-https

Open edge-https in an editor with root access (eg. sudo gedit edge-https). Scroll down a few lines form the top of the file (usually between lines 8 and 17). If you are using Option 2, no changes are required here. If you are using Option 1, remove the two comments indicated on lines 11 and 12 , and then add two comments on line 16 and 17: 

  # SSL Option 1, External Authority-Signed Certificate
  # If you are using Option 1, enable the next two lines.
  # If you are using Option 2, disable the next two lines.
    # SSLCACertificatePath /etc/ssl/certs/
    # SSLCACertificateFile /etc/apache2/ssl.crt/ca-bundle.crt
  # SSL Option 2, Self-Signed Certificate
  # If you are using Option 1, disable the next two lines.
  # If you are using Option 2, enable the next two lines.
    SSLCertificateFile     /etc/apache2/ssl/server.crt
    SSLCertificateKeyFile  /etc/apache2/ssl/server.key

Next you need to add a section to tell apache how to authenticate users when they try to open an EDGE session. This installation assumes that you are using the RIT LDAP. You will have to edit line 26 as follows to replace it with your LDAP server, and comment out the RIT LDAP server if you are not an RIT developer: 

   # Authentication - LDAP
   # Replace the name <ldapurl> with the name of the ldap server at your organization.
   ##  AuthLDAPUrl <ldapurl>
   # The line below is an example of using LDAP at RIT.
   AuthLDAPUrl ldap://ldap.rit.edu/ou=people,dc=rit,dc=edu

Now save and close https.

Restart Apache

You have configured both the unsecure (edge-http) and the secure (edge-https) sites. Now, we need to enable them and then restart the Apache server: 

sudo a2ensite edge-http
sudo a2ensite edge-https
sudo apache2ctl restart

Post Installation Checks

This section is still under development.

At this point, you should have a working EDGE installation. However, you will not be able to access all of the EDGE toolkits until we create an EDGE administrator account for you.

Bootstrapping the first administrative user into EDGE is still a bit of a pain. Right now, the easiest means is using RIT LDAP. I am having difficulties with the MySQL authentication Module in Apache 2. If we can get the Apache 2 / MySQL authentication working properly, then bootstrapping users will be a lot easier.

THIS IS INCOMPLETE

We can download and install the recommended packages with the following command: 

sudo apt-get install phpmyadmin
sudo cp -l /etc/apache2/conf.d/phpmyadmin.conf /etc/apache2/sites-available/.
sudo a2ensite phpmyadmin.conf
sudo /etc/init.d/apache2 reload

OPTIONAL: Enabling MySQL Remote Access

If you want other computers to be able to access the MySQL server on this host, you will need to modify the MySQL configuration as follows. It is only likely that you will need to do the following steps if you are working in a development team, and multiple developers will be connecting to your database from their own installations. If you are doing development on a stand-alone machine as a single developer, these modifications are not needed.

If YOU WISH TO, you may modify the MySQL configuration file to allow other sites to connect to your EDGE MySQL database on this server. 

cd /etc/mysql/
Now open "my.cnf" in an editor with root access (eg. sudo gedit my.cnf). We need to comment out the line: 
bind-address = 127.0.0.1
Like this: 
# bind-address = 127.0.0.1

Home