Downloading and installing Redmine

First of all, we need to decide where to store Redmine files. Let's use /opt/redmine (this path is fine for FHS, short for Filesystem Hierarchy Standard):

$ sudo mkdir -p /opt/redmine

This command will create the /opt/redmine directory. Now, let's go to it:

$ cd /opt/redmine

Next, we need to get the latest version of Redmine in the tar.gz archive from http://www.redmine.org/projects/redmine/wiki/Download. At the time of writing this chapter, it was 3.2.0. So get it:

$ sudo wget http://www.redmine.org/releases/redmine-3.2.0.tar.gz

Now unpack the archive into the current directory (which should be /opt/redmine):

$ sudo tar xvf redmine-3.2.0.tar.gz

This command will unpack everything into the redmine-3.2.0 subdirectory. We move there:

$ cd redmine-3.2.0

Configuring the database

Before we proceed, we should fill in the database details in Redmine configuration files (because they will be needed to run Bundler in the Installing dependencies section). To help here, Redmine comes with a sample database configuration in the config/database.yml.example file. Let's rename it to config/database.yml:

$ sudo mv config/database.yml.example config/database.yml

Now, open the config/database.yml file in your favorite editor and modify it so that it looks like this:

production:
  adapter: mysql2
  database: redmine
  host: localhost
  username: redmine
  password: your_password_here
  encoding: utf8

Thus, to make the file look like this, I removed the development and test sections, changed the username from root to redmine, and set the password. You need to replace your_password_here with your own one.

$ makepasswd --chars=32

Installing Ruby and Bundler

Redmine comes with Bundler support. Bundler is a Ruby gem dependency manager, that is, in some ways, similar to the Debian/Ubuntu package manager used in the previous section. In other words, Bundler simplifies the deployment process by ensuring that all dependencies are installed.

However, Bundler is not yet available in our clean system. Moreover, neither gem nor Ruby is available. So, we need to install them first:

$ sudo apt-get install ruby

When you are asked for confirmation, type y and press Enter. This command will install Ruby and all its dependencies, including the gem tool.

Now we can install Bundler. To do this, we will use the gem tool as follows:

$ sudo gem install bundler

Resolving Bundler errors

Bundler can automatically resolve only gem dependencies. This means that when it's not able to find a Ruby library (which is called gem), it tries to fetch it from https://rubygems.org/. But some gems use native system libraries, and therefore they must be built before being installed. Moreover, in order to build such gems, Bundler needs the appropriate system libraries to be already available. Otherwise, it won't be able to install them and will give errors.

In this section, I will let you know which libraries to install to make Bundler run flawlessly, but future versions of Redmine (3.2.0+) may require some other system libraries. So, before you run Bundler, let me show you how to resolve possible Bundler errors. Again, as you are unlikely to get any such error this time, you can skip this subsection and move on to the Installing dependencies subsection.

If you are still here, let's review a sample Bundler error:

As it can be seen from the preceding screenshot, Bundler has failed to build the rmagick gem. Consider this message:

require': cannot load such file -- mkmf (LoadError)

It tells us that Bundler failed to find the mkmf.rb file (.rb is the extension for Ruby files). The most common reason for such an error is that the corresponding library is missing. Also note that Bundler usually needs not only libraries but also their development files. Thus, the mkmf.rb file comes with ruby1.9.1-dev—the package that contains the development files for Ruby 1.9.1.

If Bundler gives a filename that it was not able to find, like in this case, on Debian/Ubuntu you can use the apt-file tool to locate it in non-installed packages. To install apt-file and initialize its database, use these commands:

$ sudo apt-get install apt-file
$ apt-file update

Afterwards, to search for a file, just specify it as an argument for the apt-file's search command. For example, to find the package that contains the Magick-config file, you should execute this:

$ apt-file search Magick-config

Installing dependencies

As we do not need Bundler to come to a halt with errors, let's install in one run all the system dependencies, the lack can cause them:

$ sudo apt-get install ruby1.9.1-dev make zlib1g-dev libmysqlclient-dev libmagickcore-dev libmagickwand-dev

This command will install the development files for Ruby, the MySQL client, and the ImageMagick libraries, as well as the libraries themselves and all their dependencies.

Now let Bundler install the gem dependencies:

$ bundle install --without development test

This command will make Bundler install gems in system directories. To do this, it will use sudo, so it may ask for the password of your user account.

If the installation of the dependencies was successful, you should see something like the following:

Installing the MySQL server, Apache, and Passenger

As we plan to use the MySQL server and the Apache web server with the Passenger module and our system is clean, we need to install all of them as well. Generally, the procedure of their installation is identical to what was described in the previous section (Installing Redmine from a package):

$ sudo apt-get install mysql-server mysql-client apache2 libapache2-mod-passenger

Here, we will skip all the details related to their installation, as they have been reviewed before. Thus, you can check them out in the Configuring the MySQL server package and Installing Apache and Passenger subsections of the Installing Redmine from a package section.

Setting up the database

Now that we are ready to go further, let's create the database for Redmine. We'll do this in the console MySQL client, so run it:

$ mysql -u root -p

The client will ask for the password of the MySQL server's superuser (root), which you have specified during the installation of the MySQL server.

Execute the following SQL queries in the console of the MySQL client:

CREATE DATABASE redmine CHARACTER SET UTF8;
CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'your_password_here';
GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';

Don't forget to replace your_password_here with the password that you specified in the config/database.yml file while you were configuring the database for Redmine.

Once you've finished, type quit and press Enter to exit the client.

Finalizing the Redmine installation

At this moment, only a few things are left to do to prepare Redmine for running. We need to create a secret token for the Redmine session store:

$ bundle exec rake generate_secret_token

Next, we need to create the structure (tables, indexes, and so on) of the Redmine database:

$ RAILS_ENV=production bundle exec rake db:migrate

Be ready – this command will produce a lot of output.

Finally, we need to insert initial data (such as trackers, the administrator account, and so on) into the database:

$ RAILS_ENV=production bundle exec rake redmine:load_default_data

This command will ask you to select a language in which the role names, the tracker names, the issue statuses and priorities, and so on should be added. You should think carefully about what to answer (for example, are you sure that you want the tracker names to be non-English?).

Configuring Apache

So by now, Redmine has been installed and configured, but we can't access it. To be able to do this, we need to configure Apache. Then let's move on to Apache's configuration directory:

$ cd /etc/apache2

Now, create the redmine.conf file in the sites-available subdirectory with the following content (do this under root):

<VirtualHost *:80>
        RailsEnv production
        DocumentRoot /opt/redmine/redmine-3.2.0/public
        <Directory "/opt/redmine/redmine-3.2.0/public">
                Allow from all
                Require all granted
        </Directory>
</VirtualHost>

This is the configuration of the virtual host that will run Redmine. However, this is not the only virtual host that we currently have.

In Debian/Ubuntu, Apache comes with a default page, which must be disabled to let Redmine run (otherwise, we will be getting that page instead of Redmine). This can be done by running the following command:

$ sudo a2dissite 000-default

In fact, as mentioned in the previous section, this command removes a symbolic link to the sites-available/000-default.conf file from the sites-enabled directory. And, as you must have probably guessed, we need to do the opposite for our redmine.conf file. This can be done by executing the line shown here:

$ sudo a2ensite redmine

Ready to try? Then reload Apache:

$ sudo service apache2 reload

Now, if you open a browser and point it to the IP or hostname of your server, you should get the following result:

You can now log in to your new Redmine installation using admin as both the login and password.

Verifying and completing the installation

There is a page in Redmine that should always be checked after launching this application for the first time. This page is Information, and it can be found in the Administration menu.

The Information page was described in detail in the Verifying and completing the installation subsection of the previous section. So, please go there and check these details. Thus, you should change the password of the admin user as soon as possible. Also, you may want to install the ImageMagick convert tool.

Upgrading Redmine

As we have installed Redmine separately from the rest of the system (in other words, the system package manager won't able to see or recognize it), we will need to handle all its updates manually and on our own. The Redmine guys periodically issue maintenance releases aimed at fixing serious bugs. So by leaving the installation unmaintained, we risk having many issues, including but not limited to security and upgrade issues.

Also note that you will have to upgrade your Redmine installation to the next major or minor version when the Redmine guys stop maintaining the version that you are currently using. (For a package, this is not the case, as package maintainers usually handle security fixes and support the package as long as the corresponding release of the system is supported.) If you don't do this, you won't even know when a new serious bug is found in the version you use.

In other words, you need to keep a track of the new versions of Redmine to be sure that you upgrade as soon as a fix is available. But how do you know when a new Redmine version is released? To check this, you can subscribe to Redmine news using the ATOM feed at http://www.redmine.org/projects/redmine/news.atom. The appropriate news should mention the reason for the release—whether it is a security fix or it just contains new features.

Certainly, before performing an upgrade, you should always check the official Redmine upgrade documentation, which is available at http://www.redmine.org/projects/redmine/wiki/RedmineUpgrade. Nevertheless, we are going to discuss this procedure shortly here as well (focusing on the particulars of our installation).

$mysqldump -u root -p redmine > /path/redmine.dump

As for the installation, we first need to download the recent version of Redmine. This can be done from the following URL (get the release in the tar.gz format): http://www.redmine.org/projects/redmine/wiki/Download. Unpack the archive into the /opt/redmine directory, where we already have redmine-3.2.0.

Now, we need to copy some configuration and other files from the old version of Redmine to the new one. In particular, we need config/database.yml, config/configuration.yml and everything inside the files directory.

Also, as for the installation, we will use Bundler to install all the Ruby dependencies. The command is the same:

$ bundle install --without development test

If anything goes wrong (say, any building errors), you know how to fix it (check out Resolving Bundler errors subsection).

Now copy the themes and plugins from the old version to the new one, but do this only if you are sure that each of them does support the new version of Redmine. If you are not sure, stop the upgrade procedure and go check if they do (see also Chapter 10, Plugins and Themes)! So, copy those themes and plugins that are known to work under the new version from the public/themes and plugins directories correspondingly, and install new versions of the plugins old versions of which do not work under the new version.

New versions of Redmine as well as those of plugins often come with changes to the database. So, it's important to execute the following commands:

$ RAILS_ENV=production bundle exec rake db:migrate
$ RAILS_ENV=production bundle exec rake redmine:plugins:migrate

These will update the database structure and will make any other fixes to the database, if needed.

As we have installed the new version in a separate directory under /opt/redmine, we need to update Apache to use this directory. So, open the /etc/apache2/sites-available/redmine.conf file in your favorite editor and replace redmine-3.2.0 with the appropriate name of the new directory. Next, restart Apache:

$ sudo service apache2 reload

As I have mentioned before, I can't guarantee that the described upgrade procedure is proper (because at the time of writing this subsection subsection, there were no new versions to upgrade to). So, if you have upgraded Redmine using these instructions—and only them—and it runs fine, you are lucky. Never do it this way again! The goal of this subsection was to give you an idea of what an upgrade of Redmine sources looks like. More complicated and riskier than an upgrade of a Redmine package, isn't it?

Afterwards, if everything works fine, you can remove the old version of Redmine (at least, you might want to remove its files directory, which often occupies a lot of disk space).