Preface
What is Redmine? Redmine is a flexible project management web application. Written using the Ruby on Rails framework, it is cross-platform and cross-database. What does that really mean though? What it means is that it gives you a great tool to manage your coding projects, either if you’re working solo or working in groups of people doing work on the same project. What’s great about Redmine is all the nice little features it offers you, that make managing your projects so much easier, some of them being
- Multiple projects support
- Flexible role-based access control
- Flexible issue tracking system
- Feeds & email notifications
- Per project wiki
- Per project forums
- SCM integration (SVN, CVS, Git, Mercurial, Bazaar and Darcs)
- Issue creation via email
Having a tool that gives you all this makes it easy to follow what you’ve done on a project so far, what issues have been uncovered with the code so far, and what has been done to fix these problems. But not only that, but it also gives you a great tool to write online documentation for your projects and has user-driven forums for them at the same making the integration between you as a coder and the end users even tighter.
As an added bonus, as with any community as it grows the community starts helping itself, making you able to focus on what’s important and that’s improving your code. Its ties to most modern VCS systems, such as Git, Subversion and Bazaar also make you able to track code changes in real-time through the web, much like you do on GitHub and similar services.
Getting ready
As always when doing work like this on any server, you should make sure you have good backup sets of your production server in case anything goes wrong. I would also recommend to packages that I just can’t live without, and that’s etckeeper and debian-goodies. etckeeper is a nice tool that saves your /etc hierarchy in a coding repository (supports git, mercurial, darcs and bzr) so that you can track your configuration changes with ease, and debian-goodies is a toolset that amongst others checks your system and its running processes to see if any program/service is running with old libraries after a system upgrade using the command checkrestart. After you’ve made sure of the above, perform the following:
sudo aptitude update sudo aptitude safe-upgrade sudo checkrestart (if debian-goodies is installed)
If everything looks good and checkrestart reports back “Found 0 processes using old versions of upgraded files”, you can proceed. If checkrestart reports that some processes are running using old libraries, either restart the respective processes using their associated init script under /etc/init.d or send the -HUP signal using kill, or simply restart the box to start with a clean slate.
INSTALL GIT
First, we install the files needed for git itself.
sudo aptitude install git-core
INSTALL RUBY
Then we install the files needed to get Ruby up and running
sudo aptitude install ruby ruby1.9.1-dev ruby1.8-dev libgemplugin-ruby libgemplugin-ruby1.8 mysql-server apache2-mpm-prefork wget libruby-extras libruby1.8-extras rake apache2-prefork-dev libapache-dbi-perl libapache2-mod-perl2 libdigest-sha1-perl libmysqlclient15-dev build-essential libcurl4-openssl-dev cron
SUPPORT FOR GANT CHARTS (OPTIONAL)
If you want Gant charts available in Redmine, you need this install this optional Ruby module.
sudo aptitude install librmagick-ruby1.8
SET UP MYSQL
Now we need to connect to the MySQL server and set up the database needed by Redmine. If you feel uncomfortable using the mysql console client, you can use tools like phpmyadmin, but this process should be fairly straightforward.
mysql -u root -p CREATE DATABASE redmine CHARACTER SET utf8; CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'my_password'; GRANT ALL privileges ON redmine.* TO 'redmine'@'localhost';
INSTALL REDMINE
Now it’s time to install the files needed by Redmine itself. We clone the unofficial Git repository from Github, which will be cloned into the folder /var/www/redmine. At the time of writing this how-to, the latest stable release of Redmine was the 1.3.0 branch, which we check out after we cloned the repository.
cd /var/www sudo git clone git://github.com/edavis10/redmine.git sudo git checkout -b 1.3.0 1.3.0
CONFIGURE THE DATABASE SETTINGS
Now we need to edit the database configuration file for Redmine so that Redmine knows how to connect to mysql to create its initial database structure with default values.
sudo cp config/database.yml.example config/database.yml sudo vim config/database.yml
Then in the database.yml file, make the “production:” stanza of the file look like this
production: adapter: mysql database: redmine host: localhost username: redmine password: my_password encoding: utf8
INSTALL RUBY GEMS
The version of Ruby Gems that comes with Ubuntu 10.04 isn’t sufficiently new enough for us to complete the installation, and as such we’re forced to install a none packaged version.
cd wget http://production.cf.rubygems.org/rubygems/rubygems-1.8.5.tgz tar xvfz rubygems-1.8.5.tgz sudo mv /usr/bin/gem /usr/bin/gem-ubuntu cd rubygems-1.8.5 sudo ruby setup.rb sudo ln -s /usr/bin/gem1.8 /usr/bin/gem gem -v
gem -v should return 1.8.5
INSTALL RAILS AND OTHER NEEDED GEMS
Now we install Ruby On Rails (or RoR for short) and the required gems for Redmine to communicate with MySQL.
sudo gem install rails -v=2.3.14 sudo gem install mysql sudo gem install rubytree -v=0.5.2
CONFIGURE THE REDMINE WEB FOLDER
We need to create a folder where Redmine stores assets used by the plugins we install later on, as well as set the needed permissions on folders used by Redmine so that the www-data user/group has read/write access.
cd /var/www/redmine sudo mkdir public/plugin_assets sudo chown -R www-data:www-data files/ log/ tmp/ public/plugin_assets sudo chmod -R 755 files/ log/ tmp/ sudo chmod -R 777 public/plugin_assets
Now that the files and folders have been created and have their right permissions, we can now initialize Redmine and the database it will use.
sudo rake generate_session_store sudo RAILS_ENV=production rake db:migrate sudo RAILS_ENV=production rake redmine:load_default_data
TIME TO TEST REDMINE FOR THE FIRST TIME
sudo ruby script/server webrick -e production
Point your web browser to http://<yourip>:3000, replacing <yourip> with the IP of the host running Redmine. You could also try to log in as the admin user with the username “admin” and password “admin”. Please change this password as soon as possible! If all goes well, you can just terminate the ruby process by pressing CTRL + C.
APACHE SETUP
Running Redmine just as a ruby application as we did above is far from ideal, so let’s move on to making Redmine accessible through Apache. The way we achieve this is by installing and setting up the Apache module passenger which basically acts like an interface between Apache and Ruby applications. Let’s get it set up!
PASSENGER INSTALLATION
First, we install the passenger gem, which gives us the tools to build and install the Apache passenger module.
sudo gem install passenger sudo passenger-install-apache2-module
Add this to /etc/apache2/mods-available/passenger.load
LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-3.0.11/ext/apache2/mod_passenger.so
Then add this to /etc/apache2/mods-available/passenger.conf
PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-3.0.11 PassengerRuby /usr/bin/ruby1.8
Then active the Apache module
sudo a2enmod passenger
APACHE VIRTUAL HOST SETUP
Add this to /etc/apache2/sites-available/redmine.yoursite.tld
<VirtualHost xxx.xxx.xxx.xxx:80> ServerName redmine.yoursite.tld ServerAdmin [email protected] DocumentRoot /var/www/redmine/public PassengerDefaultUser www-data RailsEnv production RailsBaseURI /redmine SetEnv X_DEBIAN_SITEID "default" <Directory /var/www/redmine> Order allow,deny Allow from all </Directory> </VirtualHost>
Then let’s enable to virtual host and restart Apache
sudo a2ensite redmine.yoursite.tld sudo service apache2 restart
You should now be able to get the Redmine site up by pointing your browser at http://redmine.yoursite.tld – if not, please check your configuration and your Apache access/error logs.
GIT INTEGRATION
What good is a good project management tool without actual code to manage? My favourite VCS is beyond a shadow of a doubt Git. Git is a lightweight, easy to understand and flexible system to maintain your code. In our setup, we will be using a Git daemon called gitosis to host and sort out our Git repository needs.
INSTALL GITOSIS
First, we install the needed Ruby gems to access our gitosis files, and the required libraries for gitosis as well as binaries.
sudo gem install inifile lockfile net-ssh sudo aptitude install libnet-ssh-ruby1.8 python-setuptools gitosis git-daemon-run acl
We need to edit the file /etc/fstab to activate ACL support on the partition we store our Git repositories. Gitosis resides in /srv/gitosis, which is mounted on / on most systems, meaning we need to activate the ACL module to the / partition. This is done by adding the parameter ‘acl’ before ‘errors=remount-ro’, like this.
UUID=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / ext4 acl,errors=remount-ro 0 1
To activate the ACL module, we need to restart the machine
sudo shutdown -r now
FINAL SETUP OF GITOSIS
Now that we’ve installed gitosis and activated the ACL module for the file system gitosis resides on, we are ready to initialize the gitosis main repository. First, we need to make an SSH key for the main repository.
sudo -H -u gitosis ssh-keygen -t dsa
IMPORTANT: Please do not enter a password for this SSH key!
Let’s initialize the main repository.
sudo -u gitosis cat /srv/gitosis/.ssh/id_dsa.pub | sudo -H -u gitosis gitosis-init sudo sed -i.orig 's:/var/cache:/srv/gitosis:g' /etc/sv/git-daemon/run sudo sv restart git-daemon
Now we need to apply the ACL settings for the files found under the gitosis home folder.
sudo setfacl -m user:www-data:r-x,mask:r-x /srv/gitosis/.ssh sudo setfacl -m user:www-data:r--,mask:r-- /srv/gitosis/.ssh/id_dsa
Gitosis should now be ready and installed. But it’s still not integrated with Redmine, which will be used to view our code as well as manage the repository users. For this, we need the Redmine gitosis plugin. Let’s proceed with that.
INSTALL THE REDMINE GITOSIS PLUGIN
cd /var/www/redmine sudo script/plugin install git://github.com/xdissent/redmine_gitosis.git sudo -u www-data X_DEBIAN_SITEID=default RAILS_ENV=production rake db:migrate:plugins
To make sure Redmine is aware of the newly installed plugin, we need to restart Apache
sudo service apache2 restart
To enable the plugin, go to your Redmine site and log in as an admin user, then proceed to Administration -> Plugins -> Configure Redmine Gitosis Plugin.
FINAL WORDS
I hope you found this howto helpful in your quest to get Redmine set up for your project management needs. I’m sure that you, just as I did will fall head over heels for this great gem of a tool. If you spot any errors or have any comments on this little howto, please leave a comment in the comment field below. Happy mining and managing!