Mastering Redmine

As you can read in the book, I decided to store the Redmine code for the book’s project in the directory /opt/redmine/redmine-x.y.z, where x.y.z is the version number. I chose such location to be able to easily switch back to the previous version of Redmine in a case of upgrade failure.

However, such approach introduced a need to copy all the user and state data, such as logs, from the old version to the new one during the upgrade. And, there are quite a lot of such data. So, to simplify this process, I decided to modify the Redmine file structure a little.

Restructure the file structure in the previous version of Redmine

User and state files are not (and should not be) altered during the Redmine upgrade process, so we can move them to the /opt/redmine directory (i.e., the parent one) and just create symlinks to these files under the corresponding Redmine version directories.

The following steps should be done only once and won’t be needed during further upgrades.

Before proceeding, it is better to stop Redmine to prevent these files from being modified during restructuring (what can lead to loss of new data):

$ sudo service apache2 stop

Now, move files and log subdirectories from the Redmine root directory (i.e., redmine-3.2.0) to /opt/redmine (i.e., to the parent directory).

After that, create files and log symlinks in the Redmine root directory (execute these commands while being inside that directory):

redmine-3.2.0~$ ln -sf ../files files
redmine-3.2.0~$ ln -sf ../log log

Now, in /opt/redmine create the redmine symlink, that will point to the current Redmine version (i.e., to the previous version, for now):

redmine~$ ln -sf redmine-3.2.0 redmine

Then, modify your Apache configuration, so it will point to this symlink instead of the real directory:

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

Now, you can start Redmine again, as the next steps won’t affect its work. But, you can also leave it stopped, until we complete the whole upgrade process.

Install the new version of Redmine

It’s the time to fetch the new 3.3 release from the official Redmine website (run the following under the /opt/redmine directory):

redmine~$ wget http://www.redmine.org/releases/redmine-3.3.1.tar.gz

And, unpack it:

$ tar -xzf redmine-3.3.1.tar.gz

After this, the new directory redmine-3.3.1 will appear in /opt/redmine. Go there and replace files and log directories with symlinks to appropriate directories in /opt/redmine:

redmine-3.3.1~$ ln -sfn ./files files
redmine-3.3.1~$ ln -sfn ../log log

Now, it’s the time to copy the following files from the old Redmine to the new one (use cp or any other command, that you prefer):

config/configuration.yml
config/database.yml
config/initializers/secret_token.rb
db/schema.rb

Next, we need to copy plugins and themes to new Redmine. But, before doing this, be sure to check, that all the themes and, especially, plugins support the Redmine version, you are about to copy them to (i.e., Redmine 3.3.x in this case). If you are sure, that all plugins and themes of the old version are compatible with the new one, copy corresponding subdirectories from the following locations of the old Redmine to the same locations of the new one (copy only those subdirectories under public/themes, which do not exist in new Redmine – i.e., skip native themes):

plugins/
public/plugin_assets/
public/themes/

After that, you can install new versions of the plugins and themes, old versions of which do not support Redmine 3.3.x.

Now, this is the moment, when you need to stop your Redmine again, if you have it running. Then, we need to make our redmine symlink to point to the new version of Redmine:

redmine~$ ln -sfn redmine-3.3.1 redmine

The next step is what’s in the official upgrade guide: You need to run bundle to make sure, that all the dependencies are installed (do this under the Redmine root directory):

redmine-3.3.1~$ bundle install --without development test

If you got any error (what’s unlikely, as I did not), refer to the “Resolving Bundle errors” subsection of the book (page 38) to get rid of it. When ready, you also need to run database migrations:

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

The first command will update the main Redmine database tables and the second one will do the modifications, which are needed by plugins, if any.

That’s it! Finally, it’s the time to start Redmine and play with its new version:

$ sudo service apache2 start

Enjoy it!