This is part two of my guide on how to self-administer Redmine for the long run. The first part was about Managing your own version of Redmine with Git.
With your own Redmine repository in place, it’s time to…
Automate Your Deployment
Really. Don’t try to do it the oldfashioned way and copy things around manually.
Automating your deployment is a one time investment that pays back in saved time and trouble everytime you want (or have) to upgrade your Redmine. The goal is to make deployments so easy that even the tiniest bug fix or enhancement can be deployed instantly because it’s fast, reliable and can be triggered with a single command.
Wether you’re the local server admin or a Python developer tasked with setting up Redmine in your organization, I’m asking you to learn how “the Pros”, that is, the people that develop and run Rails apps for a living, deploy and run their stuff. Over the years a lot of bright people spent a lot of time developing a toolchain that, once set up, makes zero downtime deployments of Rails apps with a single keystroke a breeze. It’s all there, you just have to use it. And it’s quite possible you’ll learn a thing or two that are useful outside the context of Redmine.
Capistrano, the Remote multi-server automation tool, is the weapon of choice when it comes to deployment automation. It’s implemented in Ruby but not restricted to deploying Ruby or Rails applications. Anything that can be done via SSH, you can automate with Capistrano. And you can do it on any number of servers in parallel. Capistrano is for deployment what Chef is for server provisioning (but much easier to use).
I’ll give you just a very short intro mentioning some Redmine specifics, be sure to read on over at capistranorb.com. The Readme is a good starting point.
local/x.y-stable Redmine branch, create a file named
Gemfile.local. That’s going to hold any gems local to your private Redmine installation.
After creating this file, run
bundle install and add/commit
Gemfile.local as well as the resulting
bundle exec cap install to set up Capistrano.
This will give you a few new files -
config/deploy.rb and two files in
config/deploy/, which correspond to the two default deployment targets or stages.
If you have separate Redmine installation for testing purposes like trying out new plugins, that would be your staging target, while the live (productive) stage is production.
The basic idea is that everything common goes into
deploy.rb, and the things that set the different stages apart go into their corresponding files in
Most often you’ll only specify the target host there, and maybe set a different git branch or deployment user name.
A Basic Capistrano Setup for Redmine
Here’s what a minimal Capistrano config might look like:
The only things left to configure are which server you’re going to deploy to, the user Capistrano should use to log in on that server, and the branch to deploy:
If you’re using the same machine for staging and production, just move the
deploy_to setting to the stage configuration files so you can set a different directory for each stage.
Don’t forget to add and commit Gemfile.local, Gemfile.lock and the Capistrano configuration you just set up - it’s a part of your custom Redmine and should be kept in source control along with it.
If you’re using Git submodules for adding plugins or themes to Redmine, have a look at the Capistrano Git submodule strategy to have them automatically deployed as well.
Update (July 2017): For current versions of Capistrano (3.7+) use the capistrano-git-with-submodules gem instead.
Capistrano is based on SSH, and relies on key-based authentication to be set up properly. It is also very convenient if you’re using some sort of SSH Agent and Agent Forwarding so you can use your local key to access the git repository via the deployment server.
Be sure to read the Authentication & Authorisation chapter of the Capistrano docs.
With everything in place, it’s time for a your first deployment:
If you set up everything correctly, this should deploy Redmine for you. If it fails, this is often due to permission or authentication problems which are usually easy to fix.