RedmineUpgrade » History » Revision 58
Revision 57 (Etienne Massip, 2012-06-06 14:30) → Revision 58/84 (Etienne Massip, 2012-06-06 14:35)
h1. Upgrading
The documentation below is based on Redmine 2.x. You can view a previous version for Redmine 1.x "here":/projects/redmine/wiki/RedmineUpgrade?version=53.
{{>toc}}
h2. Step 1 - Check requirements
The first step to upgrading Redmine is to check that you meet the [[RedmineInstall#Requirements|requirements]] for the version you're about to install.
h2. Step 2 - Backup
It is recommended that you backup your database and file uploads. Most upgrades are safe but it never hurts to have a backup just in case.
h3. Backing up the files
All file uploads are stored to the @files/@ directory. You can copy the contents of this directory to another location to easily back it up.
h3. MySQL database
The @mysqldump@ command can be used to backup the contents of your MySQL database to a text file. For example:
<pre>
/usr/bin/mysqldump -u <username> -p<password> <redmine_database> | gzip > /path/to/backup/db/redmine_`date +%y_%m_%d`.gz
</pre>
h3. SQLite database
SQLite databases are all contained in a single file, so you can back them up by copying the file to another location.
h3. PostgreSQL
The @pg_dump@ command can be used to backup the contents of a PostgreSQL database to a text file. Here is an example:
<pre>
/usr/bin/pg_dump -U <username> -Fc --file=redmine.sqlc <redmine_database>
</pre>
A decent blog (self plug) can be found here: http://www.commandprompt.com/blogs/joshua_drake/2010/07/a_better_backup_with_postgresql_using_pg_dump/
h2. Step 3 - Perform the upgrade
Now it's time to perform the actual upgrade. This process is different depending on how you downloaded Redmine. You only need to perform *one* of the following options.
h3. Option 1 - [[Download|Downloaded release]] (tar.gz or zip file)
1. Uncompress the new program archive in a new directory.
2. Copy your database settings-file @config/database.yml@ into the new @config@ directory. If you're running Redmine >= 1.4 with mysql and ruby1.9, change the database adapter to `mysql2`.
3a. Copy your base configuration settings-file @config/configuration.yml@ into the new @config@ directory.
3b. Or, *if upgrading from version older than 1.2.0*, copy your email settings from your @config/email.yml@ into the new @config/configuration.yml@ file that can be created by copying the available @configuration.yml.example@ file.
4. Copy the @files@ directory content into your new installation.
5. Copy the folders of your *custom* installed plugins from your @vendor/plugins@ directory (if upgrading from a version prior to version:2.0.0) or @plugins@ directory (else, upgrading from a version >= version:2.0.0) into new installation @plugins@ directory. Make sure that you copy only plugins that are were not initially bundled with your previous Redmine setup.
6. Run the following command from your new Redmine root directory:
rake config/initializers/session_store.rb
If you're using a newer version of Redmine, the above file will no longer exist. On these versions, run
rake generate_session_store
This will generate a file (@config/initializers/session_store.rb@) with a random secret used to secure session data.
7. Check for any themes that you may have installed in the @public/themes@ directory. You can copy them over but checking for updated version is ideal.
VERY IMPORTANT: do NOT overwrite @config/settings.yml@ with the old one.
h3. Option 2 - Upgrading from a SVN [[CheckingoutRedmine|checkout]]
1. Go to the Redmine root directory and run the following command:
<pre>
svn update
</pre>
2. If you are upgrading from an older version to 0.8.7+ or from the trunk version of Redmine to r2493 or above, you must generate a secret for cookie store. See the note at the bottom about generating a @session_store@.
h2. Step 4 - Update the database
This step is the one that could change the contents of your database. Go to your new redmine directory, then migrate your database:
<pre>
rake db:migrate RAILS_ENV=production
</pre>
If you have installed any plugins, you should also run their database migrations:
<pre>
rake db:plugins:migrate RAILS_ENV=production
</pre>
h2. Step 5 - Clean up
1. You should clear the cache and the existing sessions:
<pre>
rake tmp:cache:clear
rake tmp:sessions:clear
</pre>
2. Restart the application server (e.g. mongrel, thin, passenger)
3. Finally go to _"Admin -> Roles & permissions"_ to check/set permissions for the new features, if any.
h2. Common issues
h3. Errors with repository management
There were several new features added to the reposman.rb file, make sure you have a group specified if you're having issues ( --group=groupnamehere). Also, make sure you follow the instructions [[Repositories_access_control_with_apache_mod_dav_svn_and_mod_perl|here]] again if you only copied your Redmine.pm, and update your Apache configuration as the recommended configuration has changed.
h3. Generating a new @session_store.rb@ / @secret_token.rb@
Before version:2.0.0, a an @session_store.rb@ file needed needs to be generated in Redmine's @config@ directory for the cookie based sessions to work. Just run the following command and Redmine will create one for you:
@rake generate_session_store@
Starting from version:2.0.0, it has been replaced by the @session_store.rb@ file should not exist. Instead, the following command that will generate the @secret_token.rb@ file:
@rake generate_secret_token@
_Note: The code repository for Redmine does not contain the config/initializers/secret_token.rb config/initializers/session_store.rb file, it is created by the above rake command._
command. If the above command does not work, make sure you are running Ruby 1.8.7 and have Rails 2.3.x(see Error about the Rails version below)._
h3. Errors about a missing session_store.rb
If you see any errors about a missing @session_store.rb@ file, run the command above to create a new one.
h3. Error about member_roles
If you have had a failed upgrade/migration in the past then you may have a member_roles and/or group_users table already created. The db migration noted above will fail. Simply rename the tables by logging into MySQL command line and executing the rename table command:
@mysql> rename table member_roles to member_roles_saved
mysql> rename table groups_users to groups_users_saved
@
h3. Error about "undefined method `add_frozen_gem_path'"
If you see this error, check if the directory @vendor/rails@ exists and remove or rename it if it does, it might have an old RoR version.
h3. Related Resources
These resources may help you with your Redmine upgrade:
* "mod_fcgid for Apache2":http://httpd.apache.org/mod_fcgid/ helped us get Rails running on Apache 2
* "Running Redmine on Apache":http://www.redmine.org/wiki/redmine/HowTo_configure_Apache_to_run_Redmine
* "Notes about our 0.8.6 to 0.9.3 upgrade issues and how to resolve them":http://www.cybersprocket.com/2010/project-management/upgrading-redmine-from-8-6-to-9-3/ --cybersprocket (2010-04-25)
* "Notes about our 0.9.6 to 1.0(RC) upgrade process":http://www.cybersprocket.com/2010/tips-tricks/upgrading-redmine-from-0-9-6-to-1-0-0/ --cybersprocket (2010-08-14)