Redmine is a great project, but it has a pretty complex multisteps installation procedure and upgrade is a little pain. In order to semplify installation I tried to develop a Capistrano (+RVM) recipe to install and upgrade it. I made it available on github for who wants to try it. You should know a little bit how capistrano works to follow this guide, you can find a lot of documentation on it here.
Prerequisites
In order to install Redmine from a local machine you should have ssh access to the host where to install, rvm installed on both machines, git installed on both machines and the following gems on your local machine:
- capistrano
- capistrano-ext
- capistrano-tags
Then you can clone my repository (which is a fork of the official redmine git mirror) on your local machine with
git clone git://github.com/fabn/redmine.git
Installation
Once you’ve cloned the repository you should define your deploy configuration by using one or more stage files in config/deploy/ folder inside redmine root. This is a minimal example of such file (named production.rb, the name will be useful later).
# roles definition, on single machine deployment all the roles are played by the same host role :web, "redmine.example.org" role :app, "redmine.example.org" role :db, "redmine.example.org", :primary => true # used on redmine install to load default data when installing #set :load_default_data, false # default: true # Customize here your start, stop and restart tasks if you need # To use them you MUST deploy using explicit environment i.e. cap production redmine:upgrade #namespace :deploy do # task :stop do # logger.important "Overridden" # end #end
After you’ve created this file (it’s not included in the repository) your should edit redmine settings provided in .example files in the config folder, especially the database.yml.example file, all those files will be copied during the setup phase. Don’t change their names, simply edit them.
I don’t think that someone uses sqlite in production, anyway if you want to deploy with that db engine you MUST put your db files in the db/sqlite folder, otherwise they will NOT kept across different releases.
Then the first step on the remote machine is to prepare the environment for the installation, this could be achieved with the command
cap production deploy:setup
This command will prepare the typical capistrano structure under /var/rails/redmine (ensure your ssh user has write permission on /var/rails, otherwise capistrano will fail) on your remote machine adding some directories inside the shared folder and it will copy the yml files you’ve edited in the shared/config folder.
Now you should login on the remote machine and ensure that you’ve all the redmine dependencies installed, I choose to use rvm gemset to avoid mess in gem environment and to keep multiple projects with different dependencies installed on the same machine I used gemsets. So on the remote machine you must create a dedicated gemset called “redmine” and install redmine gems inside that gemset. This can be done with
rvm use 1.8.7@redmine --create gem install rails -v=2.3.11 gem install i18n -v=0.4.2 gem install mysql # (or gem install sqlite3)
This should meet all redmine requirements, just check that your rvm installation has gem <= 1.5.0, if not you must downgrade it or you'll have problems.
Last manual task (optional), on the remote machine install your RM themes under shared/themes and your RM plugins under shared/plugins and you're ready to go with the installation.
To perform the installation just type the following command
cap production redmine:install
You'll be prompted to choose the tag to deploy (tested with 1.1.2 and 1.2.0) or leave it blank to deploy from master branch, you'll see a lot a screens and at the end RM is installed. I overridden the default capistrano start, stop and restart task because they are pretty obsolete, you have two choices here to handle redmine start and stop: starting it manually in your server, or redefine those tasks in your production.rb file (sample provided). A last note, if you want to deploy any < 1.2.0 RM version you should change the installed gems in the gemset or replacing the gemset with a different one because with 1.2 RM has moved to rails 2.3.11.
Upgrade
Now the funny part, suppose you've just deployed the 1.2 release and the 1.2.1 come out (or you want to switch to the devel version). Instead of doing all the manual steps listed here on your machine type the following command an it will do all that work for you
cap production redmine:upgrade
This task will upgrade the codebase in a new release folder, will symlink all the shared folders (files, logs, themes and plugins), will run the migrations (both for RM and plugins) and it will update the symlink. In a couple of minutes you're done.
Final Notes
I tried this procedures a dozen of times in my environment before publishing it and eventually I ran the update task against my production installation to upgrade it from 1.1.2 to 1.2 and everything has worked as expected, but this is experimental code, so try it at your own risk and most important backup, backup, backup.
If someone is interested I can write on how to import an existing RM installation into this structure, let me know in the comments and I'll update the post.
I just published the steps needed to import your existing installation.
