A few days ago I needed to setup a FreeBSD server from scratch, in order to have a dedicated ticketing and project management system at work. We decided to use the popular Open Source Project Management Software, Redmine, since some of us had some previous (positive) experiences with it.
Looking through the Redmine community wiki, I noticed that the guides on how to install Redmine on a FreeBSD system were either outdated, or in a language I couldn’t understand. In contrast, one can find so many (and up to date!) guides for Debian and Ubuntu. Well, I could not let this injustice stand, so I set out to document the whole process.
Installing Redmine on FreeBSD isn’t hard, but it requires many steps (especially if the machine you are working on is bare and has just the minimum software ports installed.
This guide has the prerequisites of a working FreeBSD server with Apache and MySQL configured and ready to work on (there’s plenty of guides out there to set those up). Preferably, you should also have super user rights on the machine, otherwise this whole venture might prove more difficult than it should be.
If your server is already setup with Ruby, GIT, Passenger and ImageMagick, you can skip past most of the introductory stuff and go straight to the Redmine Installation part.
Compile all the things
We’ll be needing a few packages before we can actually install Redmine on our server. I’ll be documenting the steps I went through on the basis that none of this is already installed (as it wasn’t on my machine either). First thing to do would be to update our ports:
$ portsnap fetch
$ portsnap extract
We’ll need curl to install Ruby Version Manager, so let’s get that out of the way too:
$ cd /usr/ports/ftp/curl
$ make install clean
Wget is optional, but it’ll come in handy later when we download the Redmine source:
$ cd /usr/ports/ftp/wget/
$ make install clean
Next up is ImageMagick. This will take a while, but it’s worth it if you want to have properly working Gantt exports and other image manipulation features (ie. with some of Redmine’s plugins).
NOTICE: Make sure to install ImageMagick WITHOUT HDRI support, since the rmagick gem which we’ll be installing later on doesn’t play along with it.
$ cd /usr/ports/graphics/ImageMagick
$ make install clean
If you haven’t installed bash yet on the server, you’ll be needing it later on:
$ cd /usr/ports/shells/bash
$ make install clean
Install git
$ cd /usr/ports/devel/git
$ make install clean
Setting up RVM
Using RVM (Ruby Version Manager) will allow you to more easily handle multiple ruby versions, gemsets and rails applications on your server. I think it’s a must have on environments where mor ethan one applications might be deployed in the future. If you don’t like RVM, there’s also Sam Stepehenson’s rbenv available, which has a more to-the-point approach to the same issue.
First of all, let’s add a new user for RVM:
$ adduser
Username: rvm
Full name: Ruby Version Manager
Uid (Leave empty for default):
Login group [rvm]:
Login group is rvm. Invite rvm into other groups? []:
Login class [default]:
Shell (sh csh tcsh bash rbash nologin) [sh]: bash
Home directory [/home/rvm]:
Home directory permissions (Leave empty for default):
Use password-based authentication? [yes]: no
Lock out the account after creation? [no]: no
Username : rvm
Password :
Full Name : Ruby Version Manager
Uid : 1001
Class :
Groups : rvm
Home : /home/rvm
Home Mode :
Shell : /usr/local/bin/bash
Locked : no
OK? (yes/no): yes
adduser: INFO: Successfully added (rvm) to the user database.
Login as the RVM user
$ su rvm
Install RVM using curl. This line will also install the latest stable Ruby version.
$ $ \curl -L https://get.rvm.io | bash -s stable --ruby
Make sure to follow the instructions at the end of RVM’s installation process and reload your Bash profile.
$ source ~/.bash_profile
Check that everything runs smoothly.
$ type rvm | head -1
The above should return rvm is a function
[If you have used the curl command above without the –ruby flag] Install your ruby version
$ rvm install 1.9.3-head
Set the ruby version as the system default
$ rvm use 1.9.3-head --default
Let’s also create a default gemset which will be used by our Redmine installation:
$ rvm gemset create redmine
$ rvm use 1.9.3-head@redmine --default
Finally, check that your ruby version is the one we just installed
$ ruby -v
Setting up Redmine
With all the introductory stuff out of the way, we can move on to installing Redmine on our server. First, let’s install the bundler gem:
$ gem install bundler
Get the latest version of Redmine from this link (if you don’t have wget installed, just visit the link download the tar.gz file and upload it to your server) and untar it:
$ cd /usr/local/www/
$ wget http://rubyforge.org/frs/?group_id=1850
$ tar xvfz redmine-2.1.2.tar.gz
Cd into the new directory and run bundler to install all the required gems (skipping unnecessary gems)
$ cd redmine-2.1.2/
$ bundle install --without development test postgresql sqlite
We’ll also install the MySQL C bindings for Ruby, they provide a significant performance increase and there’s really no reason to have a rails app running without them.
$ gem install mysql2
Next up, create a database and a user specific to Redmine.
$ create database redmine character set utf8;
$ create user 'redmine'@'localhost' identified by 'my_password';
$ grant all privileges on redmine.* to 'redmine'@'localhost';
We need to create a database.yml file for the Redmine installation to use.
$ cd /redmine/installation/dir
$ cp config/database.example.yml database.yml
$ vi config/database.yml
Change the adapter to mysql2 (if you’ve installed the mysql2 gem above), then change the database name, username and password to the ones you’ve set when creating your redmine database for the production namespac ie:
$ production:
adapter: mysql2
database: redmine
host: localhost
username: redmine
password: redmineuserpass
encoding: utf8
Now we’re ready to run database migrations and secret key generators for the production environment. This will also load a default data set for Redmine with sample categories, task sets etc.
$ rake generate_secret_token
$ RAILS_ENV=production rake db:migrate
$ RAILS_ENV=production rake redmine:load_default_data
Installing Passenger
In order for the Redmine application to spawn on Apache, we’ll need some kind of interface to run it from. Here, it’s up to you to decide what kind of modules or servers you want to be running, I went with Passenger. We’ll need to install the Passenger gem & the corresponding module for Apache.
$ gem install passenger
$ passenger-install-apache2-module
Now that passenger’s installed, we’ll need to add a few lines to cnfigure it properly in order to run with Apache. Inside your httpd.conf (in /usr/local/etc/apache22/httpd.conf) add the lines:
$ LoadModule passenger_module /home/rvm/.rvm/gems/ruby-1.9.3-p194@redmine/gems/passenger-3.0.17/ext/apache2/mod_passenger.so
$ PassengerRoot /home/rvm/.rvm/gems/ruby-1.9.3-p194@redmine/gems/passenger-3.0.17
$ PassengerRuby /home/rvm/.rvm/wrappers/ruby-1.9.3-p194@redmine/ruby
$ PassengerDefaultUser www
Notice here that I use /home/rvm/ which means that I installed RVM for the user ‘rvm’. Next, we’ll also need to modify our vhosts file as well. Open /usr/local/etc/apache22/Includes/your.domain.com.conf with an editor (or create it first if it doesn’t exist) and add the following:
<VirtualHost SERVER.IP.ADDRESS.HERE>
ServerName server.domain.com
ServerAdmin administrator@your.domain.com
DocumentRoot /usr/local/www/redmine/public
</VirtualHost>
<Directory "/usr/local/www/redmine/public">
AllowOverride All
Options -MultiViews
Allow from all
</Directory>
Finally, restart Apache:
$ apachectl restart
Try visiting your site via a browser, and you should now see a working Redmine installation. The default login credentials are
- username: admin
- password: admin
Epilogue
There’s quite a few steps to take if you’re starting out with a basic server setup, but all in all it is a straight forward process. If you’ll excuse me now, I’ll get back to creating some tasks…