Deploying and maintaining Redmine, the right way

Disclaimer: this is not the usual guide of the form "How to install Redmine" In it, I will not dive into setting up a database or setting up a web server. I also will not talk about configuring Redmine. The Redmine documentation in this regard is quite complete. And for what is not mentioned in the official documentation, there is a general procedure for launching Rails applications, which can be easily found on the Internet.

Instead, it will be about maintaining your own, more or less customized version of Redmine, which can be deployed with a single shell command when necessary.

Ready? Then let's get started.

Postpone all-in-one builds and ready-to-run virtual machines

Bitnami installation packages or pre-installed virtual machines are good for a quick Redmine sample, but are not suitable for productive use. Why? Because they have no update. Oh, wait a second, Bitnami has it. True, it looks more like a joke. “Install a new version of the entire stack in a different directory and move your data there” is not an update. Not a word about customization, customization and plugins, which probably also need to be saved and reinstalled. Good luck with this “update.”

Redmine patch releases are released once or twice a month. Security bug fixes are released as needed - you don’t want to miss them?

A fact that people often forget about: the time of the update does not always depend on you. Of course, you can postpone the update until the next lower version of Redmine is released - for a few weeks (probably, even for a longer period). But you don’t want to sit with an unpatched system when you discover new security issues in Redmine or Rails, until you manage to free up time to install and configure the new Bitnami stack and manually move all the data?

Installation is only the tip of the iceberg. Updating is what you have to do regularly .

The search for the simplest installation method definitely ceases to be relevant as soon as a decision is made to use Redmine in production. Simple maintenance and upgradeability is what you need to focus on to minimize the costs and risks associated with using your own Redmine.

Below I will tell you how easy it is to keep Redmine up to date.

Use git

Even if you intend to run Stock Redmine without any settings or plugins, still use the Git repository to store a copy of Redmine. At the very least, having a specialized repository will give you a place to store everything you need to deploy (this will be discussed in more detail later). Sooner or later, you (or your users) will want to install some kind of plugin or custom theme, and the infrastructure will be ready for this. Experiments with changes and testing of plugins and themes in local branches without violations in the production code become very simple if you have your own git repository with Redmine. So now we start by setting up the repository.

Although the main Redmine repository is a Subversion instance, there is a semi-official repository on Github , which is maintained by the main committer and is constantly updated. Use it to set up your own repository:

Setting up a local Redmine clone

$ git clone git@github.com:redmine/redmine.git $ cd redmine $ git remote rename origin upstream $ git remote add origin git@yourserver.com:redmine.git $ git checkout -b redmine/3.2-stable upstream/3.2-stable $ git checkout -b local/3.2-stable $ git push --set-upstream origin local/3.2-stable 

Change the version of 3.2-stable to the number of the latest stable version of Redmine.

The remote repository git@yourserver.com should be private, as it will store the deployment configuration (and possibly other information that you should not publish). Since the deployment process described below will extract code from this repository, the repository must be available during deployment, so do not place it on desktop computers. The ideal situation would be when the repository will also be accessible from the web server on which the deployment takes place. But this can be circumvented if necessary.

Now you have two local branches:
redmine/3.2-stable , which tracks Redmine 3.2 without additional functionality from the github / redmine repository, represented by the above remote upstream repository,
local/3.2-stable where all deployment, customization, themes and plugins will be placed.

Patch versions update

Redmine uses the following version numbering scheme: xyz Major / Minor / Patch. Each minor version has its own stable branch , in which fixes and security patches will be applied over time (as long as this version is still supported). In our case, this is the 3.2-stable branch.

From time to time this ascending branch will receive some new commits. Your task is to include new commits in the local local/3.2-stable branch for deployment.

Although it is possible and simple to regularly supplement the upstream branch, I suggest using git rebase to support your own set of changes over the Redmine stock code:

Relocation of local changes on top of bare Redmine:

 $ git checkout redmine/3.2-stable $ git pull # new upstream commits coming in $ git checkout local/3.2-stable $ git rebase redmine/3.2-stable 

The rebase command:

• Cancel all local changes to local/3.2-stable .
• Update local/3.2-stable to reflect changes in redmine/3.2-stable .
• Reapply all local changes on top of the “bare” version.

The result will be a clean history in which your (local) commits are always on top of the last (ascending) Redmine commits.

Minor and major updates

Now, when there is a new stable branch (say, 3.3-stable ), do the same - relocate your changes on top of it. The git commands will differ slightly due to the change in the ascending branch:

Transferring local changes to a new stable branch

 $ git fetch upstream $ git checkout -b redmine/3.3-stable upstream/3.3-stable $ git checkout -b local/3.3-stable local/3.2-stable $ git rebase --onto redmine/3.3-stable redmine/3.2-stable local/3.3-stable 

These commands first create two new local branches for version 3.3: one from the ascending one and the other from the local branch 3.2. Then they relocate local changes on top of redmine/3.3-stable . The local change here is the difference between redmine/3.2-stable and local/3.3-stable (which is still redmine/3.2-stable ). Now local/3.3-stable contains Redmine 3.3 plus any local changes.

For a new older version, you need to do the same.

My God, I have conflicts!

Sooner or later (probably already during the first update to the newer version) you will encounter merge conflicts. During rebase, Git commits one by one and stops every time a commit is used with errors. In this case, the git status command will show the problem files.

Check which of the commits failed, find out what it was intended for (meaningful commit messages help you well), correct the files, use the git add command to add each corrected file when done. If conflicts have been resolved, you can view the changes that will be committed using the git diff --cached . Once you find the result satisfactory, you can continue rebasing with the git rebase --continue .

If you unexpectedly get a lot of conflicts, and there is no time to solve this problem, you can simply interrupt the current rebase using the --abort parameter, which will restore the working copy to its original state.

What's next?

Now that the Git workflow is properly configured, it's time to automate the deployment, which I will cover in the second part of this tutorial (note: the translation of the second part will be available in a few days).

Links

1. Deploy and maintain Redmine the right way
2. Deploy Redmine with Capistrano (second part) .