Project

General

Profile

RedmineUpgrade » History » Revision 70

Revision 69 (Toshi MARUYAMA, 2014-02-20 00:38) → Revision 70/84 (Jean-Philippe Lang, 2014-11-11 22:07)

h1. Upgrading 

 p{color:red}. The documentation below is based on upgrading to Redmine 2.x and higher. 2.x. 
 You can view a previous version for upgrading to 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> 


 


 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 a stable release [[Download|Downloaded release]] (tar.gz or zip file) 

 1. [[Download]] Uncompress the release in either tar.gz or zip format and 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 (this directory contains all your uploaded files). 

 5. Copy the folders of your *custom* installed plugins from your @plugins@ directory (or @vendor/plugins@ directory if (if upgrading from a 1.x version) 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. Install the required gems by running: 

   bundle install --without development test 

 If ImageMagick is not installed on your system, you should skip the installation 
 of the rmagick gem using: 

   

      bundle install --without development test rmagick 

 Only the gems that are needed by the adapters you've specified in your database 
 configuration file are actually installed (eg. if your config/database.yml 
 uses the 'mysql2' adapter, then only the mysql2 gem will be installed). Don't 
 forget to re-run `bundle install` when you change config/database.yml for using 
 other database adapters. 

 If you need to load some gems that are not required by Redmine core (eg. fcgi), 
 you can create a file named Gemfile.local at the root of your redmine directory. 
 It will be loaded automatically when running `bundle install`. 

 7. Run the following command from your new Redmine root directory: 

   

  rake generate_secret_token 

 This will generate a file (@config/initializers/secret_token.rb@) with a random secret used to secure session data. 

 8. 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 checkout 

 1. Go to the Redmine root directory and run the following command: 
 <pre> 
 svn update 
 </pre> 

 2. Install the required Updating gems by running 

 run the following command: 

   bundle update 

 3. 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 redmine: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. puma, 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 @secret_token.rb@ 

 Before version:2.0.0, a @session_store.rb@ file needed to be generated in Redmine's @config@ directory for the cookie based sessions to work. 

 Starting from version:2.0.0, the @session_store.rb@ file should not exist. Instead, the following command 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 file, it is created by the above rake command._ 

 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: 

 * Error while browsing the wiki history after upgrading from Redmine 1.x with SQLite: see #12501 
 * "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)