28 Feb 2012 RIT CAMPUS ONLY
THESE INSTRUCTIONS ARE CURRENTLY UNDER REVISION AND ARE INCOMPLETE
PLEASE MAKE NOTE OF ERRORS, OMISSIONS, OR AMBIGUITIES
IntroductionThis 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.
|Purpose of Username||Username||
associated with this username
for your installation
|EDGE System Administrator||edgeadmin||<edgeadminpassword>|
|MySQL Database Administrator||root (for mysql)||<mysqladminpassword>|
SSL Option 1
SSL Option 2
|SSL Certificate Pass Phrase||<sslpassphrase>|
Operating SystemThis 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 statusNow 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 1024You 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.csrYou 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.keyYou 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
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 -pYou 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:
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.netEDGE 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 alphaNow 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_UtilNow 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/apache2Now open the php.ini file with root access (eg. sudo gedit php.ini). In the file change:
;arg_separator.output = "&"To:
arg_separator.output = "&"And:
magic_quotes_gpc = OnTo:
magic_quotes_gpc = Off
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 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 websvnYou 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
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 1Save a copy of the actual media wiki PEAR package that was installed above...
cd /usr/share/php sudo mv Text OriginalPEARText
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:
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/ lsYou should see two files, edge-http and edge-https in the listing.
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 localhostFor example:
Now save and close edge-http.
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.
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.
OPTIONAL: Installing Other Recommended Packages
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.1Like this:
# bind-address = 127.0.0.1