Deploying Redmine with Capistrano

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

With your own Redmine repository, it's time ...

Automate Deployment

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

Deployment automation is a one-time investment that pays off for the time and effort saved every 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 run with a single command.

I ask you to learn how “pros” (that is, people who make a living by developing and running Rails applications, deploy their systems. And no matter who you are, the local server administrator or the Python developer who is tasked with supporting Redmine Over the years, many smart people have spent a lot of time developing a set of tools that, after installing it with one simple click of a button, reduces the downtime of Rails applications to zero. Such tools exist, you just need to use them I. And it’s quite possible that you will learn a couple of new tricks that will come in handy outside the context of Redmine.

Capistrano

Capistrano , a remote multi-server automation tool, is the perfect choice when it comes to deployment automation. It is embedded in Ruby, but is not limited to deploying Ruby or Rails applications. With Capistrano, you can really automate all the activities that occur in SSH. And this can be done on any number of servers in parallel. As Chef is designed to deploy servers, Capistrano is designed to deploy systems, but it's much easier to use.

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

Install Capistrano

In the branch, Redmine local/x.y-stablecreate a file with the name Gemfile.local. This will keep any gems local to a private Redmine installation.

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 command bundle installand add / commit both the file Gemfile.localand the one that appears Gemfile.lock.

Now run the command bundle exec cap installto configure Capistrano. This will add a few new files: config/deploy.rband two files in the directory config/deploy/that correspond to the two default settings (or "stages" - "stages" ) by default. If you have a separate installation of Redmine for testing, for example, new plugins, then this will be your "staging target" , while the live (working) stage is production . The main idea is that everything in common goes to deploy.rb, and different for different stages - to the corresponding files in the directoryconfig/deploy. Most often, only the target host is specified here, and perhaps another git branch or username for deployment is configured.

Basic installation of Capistrano for Redmine

Here's what a minimal Capistrano 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 on which you are going to deploy, the Capistrano user to log in to this server and the 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 use the same machine for testing and production, simply transfer the parameter deploy_toto the stage configuration files to be able to set a separate directory for each stage . Remember to add and commit the Gemfile.local, Gemfile.lock, and Capistrano configuration you just configured. These files are part of the custom Redmine and must be saved with it in the version control system.

If you use Git submodules to add plugins or themes for Redmine, pay attention to the strategy of Git submodules for Capistrano to automatically deploy them too.

Authentication

Capistrano uses SSH and relies on properly configured key-based authentication. It is also very convenient when using any SSH agent or agent redirection 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.

To run!

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

$ bundle exec cap production deploy

If you configured everything correctly, this team will deploy Redmine for you. Failures usually happen due to permission or authentication problems, but in most cases they are easy to fix.

References

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