Deploying Redmine with Capistrano

This is the second part of my guide on how to administer Redmine independently in the long term. The first part was devoted to managing your own version of Redmine using Git (link to translation).

Having your own Redmine repository, the time has come ...

Automate Deployment

Seriously. Do not try to deploy the old-fashioned way by copying everything manually.

Deployment automation is a one-time investment that pays off with the time and effort saved each time you need (well, or have to) upgrade Redmine. The goal of automation is to make subsequent deployments as easy as possible. Even the smallest correction or improvement can be performed instantly, because the automated update procedure is fast, reliable and can be started with a single command.

I ask you to learn how to "pro" (that is, people who make a living by developing and running Rails applications, deploying their systems. And it doesn't matter if you are a local server administrator or a Python developer who is assigned to support Redmine in an organization. Over the past years, many smart people have spent a lot of time developing a set of tools that, after installing with one easy keystroke, reduces the downtime of Rails applications to zero. Such tools exist, they just need to be used I. And quite possibly, you will learn a couple of new magic tricks that will be useful outside the context of Redmine.

Capistrano

Capistrano is a remote multi-server automation tool — the ideal choice when it comes to automating deployment. It is embedded in Ruby, but is not limited to deploying Ruby or Rails applications. With the help of Capistrano, it is really possible to automate all actions performed in SSH. And this can be done on any number of servers in parallel. As Chef is designed for server deployment, Capistrano is designed for system deployment, but it is much easier to use.

I give a very brief introduction to the specifics of Redmine, you can read more at capistranorb.com . A readme for this is a good starting point.

Install capistrano

In the Redmine local/xy-stable branch, create a file called Gemfile.local . This will keep any gems local to the private installation of Redmine.

Gemfile.local

 group :development do # uncomment if you're using modern (and secure!) ed25519 ssh keys # gem 'net-ssh', '4.0.0.alpha2' gem 'capistrano', '~> 3.4.0' gem 'capistrano-rails', require: false end 

After creating this file, run the bundle install command and add / fix both the Gemfile.local file and the appeared Gemfile.lock .

Now run the bundle exec cap install command to configure Capistrano. This will add several new files: config/deploy.rb and two files in the config/deploy/ directory, which correspond to two default settings (or "stages" ) "stages" ). If you have a separate Redmine installation for testing, for example, new plug-ins, then this will be your "staging target" , while the live (working) stage is production . The basic idea is that everything common goes in deploy.rb , and different for different deploy.rb in the corresponding files in the config/deploy directory. Most often, only the target host is indicated here and it is possible that another git branch or username is being configured for deployment.

Basic installation of Capistrano for Redmine

Here is what the Capistrano minimum configuration might look like:

config / deploy.rb

 # config valid only for current version of Capistrano lock '3.4.0' set :application, 'redmine' set :scm, :git set :repo_url, 'git@code.yourcompany.com:redmine.git' # Target directory in the server. # Should exist and the user account you're using for deployment should # have write access. set :deploy_to, '/srv/webapps/redmine' set :pty, true set :log_level, :info # Linked files are expected to exist below /srv/webapps/redmine/shared and will be # symlinked into the deployed # code. Create them either manually or through an # automation tool like chef. The reason for doing so is to not keep database # credentials and server secrets in your git repository. set :linked_files, fetch(:linked_files, []).push('config/database.yml', 'config/secrets.yml') # Directories with contents you want to keep across deployments are declared here. # Most important is files where Redmine stores any uploaded files. set :linked_dirs, fetch(:linked_dirs, []).push('log', 'tmp', 'vendor/bundle', 'files') # keep the last 5 deployed versions on the server. # Useful in case you have to revert to an older version. set :keep_releases, 5 namespace :deploy do # Declares a task to be executed once the new code is on the server. after :updated, :plugin_assets do on roles(:app) do within release_path do with rails_env: fetch(:rails_env) do # Copy over plugin assets execute :rake, 'redmine:plugins:assets' # Run plugin migrations execute :rake, 'redmine:plugins:migrate' end end end end # This will run after the deployment finished and is used to reload # the application. You most probably have to change that depending on # your server setup. after :published, :restart do on roles(:app) do sudo "/etc/init.d/unicorn reload redmine" end end # cleans up old versions on the server (keeping the number of releases # configured above) after :finished, 'deploy:cleanup' end 

It remains only to configure the server to which you intend to deploy a Capistrano user to log in to this server and branch for deployment:

config / deploy / production.rb

 set :branch, 'local/3.2-stable' server 'redmine.yourcompany.com', user: 'deploy', roles: %w{web app db} 

If you are using the same machine for testing and production, simply transfer the deploy_to parameter to the stage configuration files to be able to set a separate directory for each stage . Don't forget to add and commit the Gemfile.local, Gemfile.lock and the Capistrano configuration you just configured. These files are part of the custom Redmine and should be saved with it in the version control system.

If you are using Git submodules to add plugins or themes for Redmine, look at the Capitrano Git submodules strategy to automatically deploy them too.

Authentication

Capistrano uses SSH and relies on properly configured key-based authentication. This is also very useful when using any SSH agent or redirecting agents to access the git repository through the deployment server with its local key.

Be sure to read the “Authentication and Authorization” chapter in the Capistrano Manual.

Run!

Now that everything is in place, it's time for the first deployment:

 $ bundle exec cap production deploy 

If you set everything up correctly, this command will deploy Redmine for you. Usually, failures happen because of permissions or authentication problems, but in most cases they are easy to fix.

Links

1. Deploying Redmine with Capistrano .
2. Deploy and maintain Redmine the right way .
3. Deploying and maintaining Redmine, the right way .