Installing Redmine 3 on an Existing Ubuntu LAMP server

Note:  This has been updated from its original post in 2015.

I will be upgrading some Ubuntu 12 servers in the near future and will be deploying Redmine 3 (upgrading from 2.2).  In order to prepare for that, and because I needed a Redmine instance for a project I will be undertaking (an store management app to integrate with Square), I decided to do a full deploy of Redmine to an Ubuntu 14 server I had setup to use in a course I was teaching at UCSD.  It had Apache, MySQL and PHP installed to support a BPM solution, so I would need to add RoR support to the server, and get Redmine running.  Although this wouldn’t be fully parallel to what I will be doing in a couple of weeks, it would serve as a refresher for me, and alert me to things I need to be aware of.  I was mostly able to follow the Redmine install documents, but there were a few exceptions that I wanted to document, as well as some additional pieces that the Redmine docs don’t really address.

The first step is to get Passenger running.  The instructions are simple and straightforward, and this installation worked just fine.  Once installed, you need to install Redmine.  The first question is about Ruby in your environment.  I attempted to use RBEnv as that seems to be growing in popularity.  After hitting a number of snags, I opted to uninstall RBEnv and switch back to RVM which I’ve had success with.  I suspect that had I wanted to try for a bit longer, I could have ironed out the RBEnv issues, but I decided to move on.  Basically what was happening was that I had first installed it in my home account, then realized that this would be problematic and located instructions for doing a multiuser install, as I want to run my app under a service account, not as my user.  I should point out that I did all of this work with a “standard” user account that was also in the sudoers list.  I believe that I will be able to effectively manage the upgrades over time with this approach.

I followed the multiuser RVM installation instructions located here.  Again, this is straightforward, just follow the instructions and make sure you are working in the multiuser part.  After completing the install, create a Redmine user (this is after the whole Redmine install is completed) to act as a service account, and grant it the appropriate permissions.  The account can be locked and will work just fine, so people cannot attempt to log on to your system if they guess the service account name.  Once RVM is installed, you can install whatever Ruby you wish (or rubies).  I installed 2.2.3, then made it the system default (RVM use 2.2.3 –default).  I give the redmine user ownership of the files, tmp and log directories recursively as that user needs to write to those directories.

Once that is complete, create a database for Redmine and select a user for this.  As a matter of safety, I create a specific user to access the database, and limit connections to localhost only, for the Redmine user only.  If you have PHPMyAdmin running this is a simple enough task.  In general, and MySQL defaults to this, you shouldn’t be directly connecting to it from another machine.  If such a thing is necessary, you should do it on an IP by IP basis, so that you are allowing just a specific IP.  I have an implementation at a client where there is an integration between MySQL and another tool that requires a direct external connection for read only.  I created a read only user, and allow it to authenticate only from that one IP address.

Install both SVN and ImageMagick.  The OpenID libraries are dependent on whether you want OpenID.  ImageMagick is optional as well, but the default with Redmine is to use RMagick to handle images, and it will not install without ImageMagick.  You’ll want images, so just go for it.  There is one thing that won’t install with the RMagick gem, if you just install ImageMagick (sudo apt-get install imagemagick).  You will also need to install a dev library by using sudo apt-get install libmagickwand-dev.

At this point, you will want to install the MySQL libraries and drivers so that the MySQL2 gem will install correctly.  Run the following.

sudo apt-get install ruby-mysql  libmysqlclient-dev (the old libmysql-ruby was a transitional package).

At this point download Redmine.  I used SVN and downloaded it to a directory in usr/local.  Then I created a symlink to the directory in /var/www.  From here, configure the database.yml file as directed in the installation directions, then install bundler (gem install bundler) then install the required gems using bundle install –without development test (you can exclude rmagick at this point, as well, if you aren’t going to use it).

Next, create the application secret by executing, from within the Redmine directory (also applies to any app) rake secret.  This generates a secret key and then captures it in an environment variable.  Rails 4 requires that you create a config/secrets.yml file and place the following two lines, in lieu of using the config/initializers/secret_token.rb file:

production:

secret_key_base: ‘secret generated above’

A key configuration item, as it turns out is:

PassengerResolveSymlinksInDocumentRoot on

Without this, you will simply receive a list of items in the public folder.  This appears to be Rails related as I have an older version of Redmine running the same version of Passenger, but on Rails 3 that doesn’t require this directive.  Redmine 3, using Rails 4+ appears to have this requirement.

This secures your application by not placing your secret key in any of the application files (it exists only at the OS level).  Alternatively you can set secret_key_base: <%= ENV[“SECRET_KEY_BASE”] %> and load it from the profile of the redmine user (assuming that this is the user which will be running the application).

Finish by creating the database schema, default data set, and setting the file permissions as indicated.

The last step is to let Apache know about the new application.  In general, I prefer, like many, to create a redmine.conf file in the /etc/apache2/sites-available directory.  Within it, create the appropriate virtual host entry pointing to the public directory inside of the redline application (e.g. /var/www/redmine/public) for both the document root and the directory.  You may want to specify the following lines to ensure that Passenger runs correctly, but in my experience they are not entirely necessary:

PassengerRuby (path to ruby, see below)

PassengerDefaultUser <service account created earlier>

If you are upgrading from an older Ubuntu version, vs. performing a clean install, make sure that you don’t have any passenger configuration items in your apache2.conf file (typically in /etc/apache2/).  The passenger binary itself should be loaded as a module in Apache, and the PassengerRuby and Default user, although they can be defined in the apache2.conf should probably be specified within the virtual host definition.  It wouldn’t hurt to keep things in the apache2.conf file, but by keeping it in the sites definition, the option exists to run different rails apps using different rubies and users.  If, as I have had in the past, you have a legacy app, you can run it under a legacy ruby at the same time a newer app is running on the latest ruby.

To determine the path to ruby, run the following command:  passenger-config about ruby-command, then copy the path to the redmine.conf file as indicated.

Enable the redmine site (a2ensite redmine), restart apache, and all should work.