xethm55
January 21st, 2008, 10:51 PM
I came accross redmine in a search for an integrated content management system for me to use for projects I have in development ( I will refrain from any shameful plugs ). I had some strict criteria:
Needed to integrate well with SVN ( chosen revision control)
Needed to have the following Modules:
Wiki
Issue Tracker
User Authentication
Needed to have a unified theme between all modulesI tried many solutions (Mantis, FlySpray, Bugzilla, dokuwiki, pmwiki, TikiWiki, MediaWiki, and more) however none of them seemed to fit the criteria. That is until I happen upon RedMine. It was every thing I wanted and more. However I was put off by there not being a lot of guides to setup redmine to work through apache in ubuntu.
So, being that I just went through about a week of trial and error setting up redmine, a content management system, to run on Ubuntu, I decided that I should write a guide on the process for future reference ( I am prone to memory loss ) and for others who desire it. This is a lengthy guide - I tried to be very detailed - so you might want to set aside a few hours to do this.
First things first lets get the disclaimers out of the way. I am not in any way responsible for any negative effects this may cause to your computer, you, your walls and/or material possessions, or other people around you. You follow this guide at your own risk. I will try to help out when I can and remember to check.
Installation Guide Part I: Redmine, the Basics:
( Composed from the referenced sites at the bottom )
The following assumes that you have a command line install of Ubuntu [Gutsy], that you want to install redmine in /home/redmine, and have it be the default website apache serves.
Install all the packages needed from the repositories:
sudo apt-get install libmysql-ruby mysql-server subversion apache2 ruby rubygems irb ri rdoc ruby1.8-dev build-essential phpmyadmin rake libapache2-mod-fastcgiWhen that command finishes, issue the following command to install Ruby on Rails and Mongrel (this took me a long time to figure out)
sudo gem install rails mongrel mongrel_cluster daemons --include-dependenciesIf the installer asks what versions to install, Install the following versions:
Rails 2.0.2 (Ruby)
Mongrel Web Server 1.1.3
Mongrel_Cluster 1.0.5
Daemons 1.0.9Once that is complete, we need to create symbolic links in /usr/bin for the mongrel scripts. Assuming that your gems installed in the same location, issue the following commands:
sudo ln -s /var/lib/gems/1.8/bin/mongrel_rails /usr/bin/mongrel_rails
sudo ln -s /var/lib/gems/1.8/bin/rails /usr/bin/rails
sudo ln -s /var/lib/gems/1.8/bin/mongrel_cluster_ctl /usr/bin/mongrel_cluster_ctlNow that we have access to the scripts (gets rid of that annowing path export !) and ruby on rails is setup, we need to get the latest version of redmine
sudo svn co http://redmine.rubyforge.org/svn/trunk /home/redmineNow that you have the source, you will need to do a little setup in MySQL.
So fire up phpmyadmin ( You could do this from the command line, but why would you ) by going to the following address in a web browser:
http://localhost/phpmyadmin(You would need to replace localhost with the server address if you are doing this remotely)
From the main phpmyadmin page, go to Privileges, then click on Add New User.
Enter a username (I used redmine) and a password (or generate one) you just need to remember it / write it down
Click on “Create database with same name and grant all privileges”
Click Go ( lower right of page – might need to scoll down ).
Now that we have a dabase created, we need to add that to the redmine configuration.
We need to create a database configuration from the exsisting example file. So, issue the following commands:
cd /home/redmin/config
sudo cp database.example.yml database.ymlNow the database.yml file needs to be edited, so enter the following (you could use any command line editor)
sudo nano database.ymlChange the section (below) so that it reflects the username and database you setup with phpmyadmin
Password also needs to be entered in plain text
production:adapter: mysql
database: redmine
host: localhost
username: root
password:so, for example mine looks like this (since I used redmine as user / db):
production:adapter: mysql
database: redmine
host: localhost
username: redmine
password: [chosen password]Now that we have the database setup and configured, we need to write a base set of tables to it. To do this, issue the following command.
sudo rake db:migrate RAILS_ENV="production"If the stars aligned properly, this should spit out a bunch of database table creation logs and exit without errors.
Now those databases need to be populated with default data so issue the following command if the previous one completed successfully:
sudo rake redmine:load_default_data RAILS_ENV="production"If that completes successfully issue the following command to start the test web server:
sudo ruby script/server -e productionNow, cross your fingers and you should be able to access your new redmine install via:
http://localhost:3000 (http://localhost:3000/)Replacing localhost with address of server
The default login information is:
Username: admin
Password: adminAfter changing the admin password (Administration->Users), I suggest that you go and create a new account (Administration->Users-New) then logout and log back in with new account.
Then go to Administration->users and lock the admin account.
Installation Guide Part II: Apache Mongrels
Now we need to setup the mongrel clusters for redmine. From the base redmine install directory (/home/redmine for me) issue the following command:
cd /home/redmine
sudo mongrel_rails cluster::configure -e production -p 8000 -N 3 -c /home/redmine --user www-data --group www-dataThis should return that the mongrel cluster was successfully written. Now that we have a configuration setup, we should attempt to start the mongrel cluster, by issuing the following command (must be within your redmine directory ex /home/redmine):
sudo mongrel_rails cluster::startYou should see that mongrel cluster was started on ports 8000,8001,8002. At this point, you should be able to access the redmine install at
http://localhost:8000 (http://localhost:8000/)Now for the fun part, setting up apache to work with redmine.
Apache needs to be able to read and write files in the redmine install. Changing the ownership of the files will accomplish this, so issue the following command:
sudo chown -R www-data:www-data /home/redmineSince the user and group apache uses is www-data. Now the .htaccess file in the redmine/public folder needs to be setup. Issue the following commands (assuming you are still in your redmine directory):
cd /home/redmine/public
sudo nano .htaccessReplace this whole file with the following ( worked for me atleast ):
# General Apache options
AddHandler fastcgi-script .fcgi
AddHandler fcgid-script .fcgi
AddHandler cgi-script .cgi
Options +FollowSymLinks +ExecCGI
RewriteEngine On
RewriteRule ^$ index.html [QSA]
RewriteRule ^([^.]+)$ $1.html [QSA]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]
ErrorDocument 500 "<h2>Application error</h2>Rails application failed to start properly"
Save and exit. This is the original file with all the if statements removed and only the sections that are needed left. Now that we have a presumably working .htaccess file, we need to modify the apache configuration. Go to the apache2 configuration directory and open apache2.conf, by issuing the following commands:
cd /etc/apache2
sudo nano apache2.confWith apache2.conf open, we need to modify the following two lines (located about half way through the file around line 180):
# Include module configuration:
Include /etc/apache2/mods-enabled/*.load
Include /etc/apache2/mods-enabled/*.confChange the two include lines to be:
# Include module configuration:
Include /etc/apache2/mods-available/*.load
Include /etc/apache2/mods-available/*.confThis is not really preferred, since it loads all the apache modules, however, I did not want to go through the process of elimination to find the correct ones to enable.
Now we need to create a new site. So go into the sites available and modify the default site. Issue the following command:
cd /etc/apache2/sites-available
sudo nano defaultReplace the contents of this file with the following:
<VirtualHost *>ServerAdmin email@example.com
ServerName redmine.example.com
ServerAlias example.com
RewriteEngine On
# Redirect all non-static requests to cluster
RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
RewriteRule ^/(.*)$ balancer://redminecluster%{REQUEST_URI} [P,QSA,L]
</VirtualHost>
<Proxy balancer://redminecluster>BalancerMember http://127.0.0.1:8000 (http://127.0.0.1:8000/)
BalancerMember http://127.0.0.1:8001 (http://127.0.0.1:8001/)
BalancerMember http://127.0.0.1:8002 (http://127.0.0.1:8002/)
</Proxy>Save and exit. Now we need to open the proxy up to requests. To do this, we need to edit the proxy.conf file in the mods-available directory. So, issue the following commands;
cd /etc/apache2/mods-available
sudo nano proxy.confThe following lines (around line 9 ) need to be modified.
Order deny,allow
Deny from allThe lines need to be modified to the following:
Order allow,deny
Allow from allSave and exit. Again, this is not a preferred way of doing things, This should be modified to only allow connections from apache to redmine, I did not want to take the time to do that. Now, apache should be all setup. Apache needs to be restarted to get it working, so issue the following command:
sudo /etc/init.d/apache2 restartHopefully you should see that the restart went ok. If that is the case, you should be able to access redmine remotely in a web browser. Now, if the planets align and you wish really hard, You should see redmine appear when browsed to the server without specifying the port.
Installation Guide Part III: The Reboot
There is one more problem, the setup will not work if the computer is restarted unless you start the mongrel cluster manually. To a get mongrel to start at boot, we need to link redmine’s configuration for the cluster in /etc/mongrel_cluster. To do this, issue the following commands:
sudo mkdir /etc/mongrel_cluster
cd /etc/mongrel_cluster
sudo ln -s /home/redmine/config/mongrel_cluster.yml /etc/mongrel_cluster/redmine.ymlDoing an:
ls -alshould show that you now have a symbolic link to redmines mongrel cluster configuration.
Now, we need to copy over the mongrel startup script to init.d to do this, issue the following commands:
cd /etc/init.d
sudo cp /var/lib/gems/1.8/gems/mongrel_cluster-1.0.5/resources/mongrel_cluster /etc/init.d/
sudo chmod +x /etc/init.d/mongrel_clusterNow that we have the init script we need to tell it to boot on startup. To do the issue the following command:
sudo /usr/sbin/update-rc.d -f mongrel_cluster defaultsThat should be it. Mongrel_cluster and redmine should startup on boot, automagically.
References:http://www.redmine.org/wiki/redmine/HowTo_run_Redmine_with_a_Mongrel_cluster
http://mongrel.rubyforge.org/docs/mongrel_cluster.html
http://www.redmine.org/wiki/redmine/RedmineInstall
http://wiki.rubyonrails.org/rails/pages/RailsOnUbuntu
http://www.redmine.org/wiki/redmine/Download
http://wiki.rubyonrails.org/rails/pages/RailsOnCentos5
http://rubyforge.org/forum/message.php?msg_id=27821
http://bitnami.org/stack/redmine (http://bitnami.org/)
-xethm55
Needed to integrate well with SVN ( chosen revision control)
Needed to have the following Modules:
Wiki
Issue Tracker
User Authentication
Needed to have a unified theme between all modulesI tried many solutions (Mantis, FlySpray, Bugzilla, dokuwiki, pmwiki, TikiWiki, MediaWiki, and more) however none of them seemed to fit the criteria. That is until I happen upon RedMine. It was every thing I wanted and more. However I was put off by there not being a lot of guides to setup redmine to work through apache in ubuntu.
So, being that I just went through about a week of trial and error setting up redmine, a content management system, to run on Ubuntu, I decided that I should write a guide on the process for future reference ( I am prone to memory loss ) and for others who desire it. This is a lengthy guide - I tried to be very detailed - so you might want to set aside a few hours to do this.
First things first lets get the disclaimers out of the way. I am not in any way responsible for any negative effects this may cause to your computer, you, your walls and/or material possessions, or other people around you. You follow this guide at your own risk. I will try to help out when I can and remember to check.
Installation Guide Part I: Redmine, the Basics:
( Composed from the referenced sites at the bottom )
The following assumes that you have a command line install of Ubuntu [Gutsy], that you want to install redmine in /home/redmine, and have it be the default website apache serves.
Install all the packages needed from the repositories:
sudo apt-get install libmysql-ruby mysql-server subversion apache2 ruby rubygems irb ri rdoc ruby1.8-dev build-essential phpmyadmin rake libapache2-mod-fastcgiWhen that command finishes, issue the following command to install Ruby on Rails and Mongrel (this took me a long time to figure out)
sudo gem install rails mongrel mongrel_cluster daemons --include-dependenciesIf the installer asks what versions to install, Install the following versions:
Rails 2.0.2 (Ruby)
Mongrel Web Server 1.1.3
Mongrel_Cluster 1.0.5
Daemons 1.0.9Once that is complete, we need to create symbolic links in /usr/bin for the mongrel scripts. Assuming that your gems installed in the same location, issue the following commands:
sudo ln -s /var/lib/gems/1.8/bin/mongrel_rails /usr/bin/mongrel_rails
sudo ln -s /var/lib/gems/1.8/bin/rails /usr/bin/rails
sudo ln -s /var/lib/gems/1.8/bin/mongrel_cluster_ctl /usr/bin/mongrel_cluster_ctlNow that we have access to the scripts (gets rid of that annowing path export !) and ruby on rails is setup, we need to get the latest version of redmine
sudo svn co http://redmine.rubyforge.org/svn/trunk /home/redmineNow that you have the source, you will need to do a little setup in MySQL.
So fire up phpmyadmin ( You could do this from the command line, but why would you ) by going to the following address in a web browser:
http://localhost/phpmyadmin(You would need to replace localhost with the server address if you are doing this remotely)
From the main phpmyadmin page, go to Privileges, then click on Add New User.
Enter a username (I used redmine) and a password (or generate one) you just need to remember it / write it down
Click on “Create database with same name and grant all privileges”
Click Go ( lower right of page – might need to scoll down ).
Now that we have a dabase created, we need to add that to the redmine configuration.
We need to create a database configuration from the exsisting example file. So, issue the following commands:
cd /home/redmin/config
sudo cp database.example.yml database.ymlNow the database.yml file needs to be edited, so enter the following (you could use any command line editor)
sudo nano database.ymlChange the section (below) so that it reflects the username and database you setup with phpmyadmin
Password also needs to be entered in plain text
production:adapter: mysql
database: redmine
host: localhost
username: root
password:so, for example mine looks like this (since I used redmine as user / db):
production:adapter: mysql
database: redmine
host: localhost
username: redmine
password: [chosen password]Now that we have the database setup and configured, we need to write a base set of tables to it. To do this, issue the following command.
sudo rake db:migrate RAILS_ENV="production"If the stars aligned properly, this should spit out a bunch of database table creation logs and exit without errors.
Now those databases need to be populated with default data so issue the following command if the previous one completed successfully:
sudo rake redmine:load_default_data RAILS_ENV="production"If that completes successfully issue the following command to start the test web server:
sudo ruby script/server -e productionNow, cross your fingers and you should be able to access your new redmine install via:
http://localhost:3000 (http://localhost:3000/)Replacing localhost with address of server
The default login information is:
Username: admin
Password: adminAfter changing the admin password (Administration->Users), I suggest that you go and create a new account (Administration->Users-New) then logout and log back in with new account.
Then go to Administration->users and lock the admin account.
Installation Guide Part II: Apache Mongrels
Now we need to setup the mongrel clusters for redmine. From the base redmine install directory (/home/redmine for me) issue the following command:
cd /home/redmine
sudo mongrel_rails cluster::configure -e production -p 8000 -N 3 -c /home/redmine --user www-data --group www-dataThis should return that the mongrel cluster was successfully written. Now that we have a configuration setup, we should attempt to start the mongrel cluster, by issuing the following command (must be within your redmine directory ex /home/redmine):
sudo mongrel_rails cluster::startYou should see that mongrel cluster was started on ports 8000,8001,8002. At this point, you should be able to access the redmine install at
http://localhost:8000 (http://localhost:8000/)Now for the fun part, setting up apache to work with redmine.
Apache needs to be able to read and write files in the redmine install. Changing the ownership of the files will accomplish this, so issue the following command:
sudo chown -R www-data:www-data /home/redmineSince the user and group apache uses is www-data. Now the .htaccess file in the redmine/public folder needs to be setup. Issue the following commands (assuming you are still in your redmine directory):
cd /home/redmine/public
sudo nano .htaccessReplace this whole file with the following ( worked for me atleast ):
# General Apache options
AddHandler fastcgi-script .fcgi
AddHandler fcgid-script .fcgi
AddHandler cgi-script .cgi
Options +FollowSymLinks +ExecCGI
RewriteEngine On
RewriteRule ^$ index.html [QSA]
RewriteRule ^([^.]+)$ $1.html [QSA]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]
ErrorDocument 500 "<h2>Application error</h2>Rails application failed to start properly"
Save and exit. This is the original file with all the if statements removed and only the sections that are needed left. Now that we have a presumably working .htaccess file, we need to modify the apache configuration. Go to the apache2 configuration directory and open apache2.conf, by issuing the following commands:
cd /etc/apache2
sudo nano apache2.confWith apache2.conf open, we need to modify the following two lines (located about half way through the file around line 180):
# Include module configuration:
Include /etc/apache2/mods-enabled/*.load
Include /etc/apache2/mods-enabled/*.confChange the two include lines to be:
# Include module configuration:
Include /etc/apache2/mods-available/*.load
Include /etc/apache2/mods-available/*.confThis is not really preferred, since it loads all the apache modules, however, I did not want to go through the process of elimination to find the correct ones to enable.
Now we need to create a new site. So go into the sites available and modify the default site. Issue the following command:
cd /etc/apache2/sites-available
sudo nano defaultReplace the contents of this file with the following:
<VirtualHost *>ServerAdmin email@example.com
ServerName redmine.example.com
ServerAlias example.com
RewriteEngine On
# Redirect all non-static requests to cluster
RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
RewriteRule ^/(.*)$ balancer://redminecluster%{REQUEST_URI} [P,QSA,L]
</VirtualHost>
<Proxy balancer://redminecluster>BalancerMember http://127.0.0.1:8000 (http://127.0.0.1:8000/)
BalancerMember http://127.0.0.1:8001 (http://127.0.0.1:8001/)
BalancerMember http://127.0.0.1:8002 (http://127.0.0.1:8002/)
</Proxy>Save and exit. Now we need to open the proxy up to requests. To do this, we need to edit the proxy.conf file in the mods-available directory. So, issue the following commands;
cd /etc/apache2/mods-available
sudo nano proxy.confThe following lines (around line 9 ) need to be modified.
Order deny,allow
Deny from allThe lines need to be modified to the following:
Order allow,deny
Allow from allSave and exit. Again, this is not a preferred way of doing things, This should be modified to only allow connections from apache to redmine, I did not want to take the time to do that. Now, apache should be all setup. Apache needs to be restarted to get it working, so issue the following command:
sudo /etc/init.d/apache2 restartHopefully you should see that the restart went ok. If that is the case, you should be able to access redmine remotely in a web browser. Now, if the planets align and you wish really hard, You should see redmine appear when browsed to the server without specifying the port.
Installation Guide Part III: The Reboot
There is one more problem, the setup will not work if the computer is restarted unless you start the mongrel cluster manually. To a get mongrel to start at boot, we need to link redmine’s configuration for the cluster in /etc/mongrel_cluster. To do this, issue the following commands:
sudo mkdir /etc/mongrel_cluster
cd /etc/mongrel_cluster
sudo ln -s /home/redmine/config/mongrel_cluster.yml /etc/mongrel_cluster/redmine.ymlDoing an:
ls -alshould show that you now have a symbolic link to redmines mongrel cluster configuration.
Now, we need to copy over the mongrel startup script to init.d to do this, issue the following commands:
cd /etc/init.d
sudo cp /var/lib/gems/1.8/gems/mongrel_cluster-1.0.5/resources/mongrel_cluster /etc/init.d/
sudo chmod +x /etc/init.d/mongrel_clusterNow that we have the init script we need to tell it to boot on startup. To do the issue the following command:
sudo /usr/sbin/update-rc.d -f mongrel_cluster defaultsThat should be it. Mongrel_cluster and redmine should startup on boot, automagically.
References:http://www.redmine.org/wiki/redmine/HowTo_run_Redmine_with_a_Mongrel_cluster
http://mongrel.rubyforge.org/docs/mongrel_cluster.html
http://www.redmine.org/wiki/redmine/RedmineInstall
http://wiki.rubyonrails.org/rails/pages/RailsOnUbuntu
http://www.redmine.org/wiki/redmine/Download
http://wiki.rubyonrails.org/rails/pages/RailsOnCentos5
http://rubyforge.org/forum/message.php?msg_id=27821
http://bitnami.org/stack/redmine (http://bitnami.org/)
-xethm55