Upgrading Redmine

Step-by-step instructions for upgrading an existing Redmine installation to a new version.

Back up your database and files directory before starting the upgrade. Migrations cannot be reversed automatically.

1. Extract the new release

   Download the new Redmine release archive and extract it into a separate directory:

   tar -xzf redmine-x.x.x.tar.gz
   

   Do not overwrite the existing installation directory. Work from the new directory and copy configuration across.

2. Copy configuration files

   Copy your existing configuration files into the new config directory:

   cp /old/redmine/config/database.yml      /new/redmine/config/database.yml
   cp /old/redmine/config/configuration.yml /new/redmine/config/configuration.yml
   

   Before Redmine 1.2, SMTP configuration was stored in config/email.yml. It must now be in config/configuration.yml.

3. Copy attached files

   Copy the contents of the files directory from your old installation. This directory contains all uploaded attachments:

   cp -r /old/redmine/files/. /new/redmine/files/
   
4. Copy plugins and themes

   Copy your installed plugins and themes into the new installation:

   cp -r /old/redmine/plugins/. /new/redmine/plugins/
   cp -r /old/redmine/themes/.  /new/redmine/themes/
   

   Plugins from your previous Redmine version may not be compatible with the version you are upgrading to. Check each plugin’s changelog and compatibility notes before copying it.

5. Install required gems

   In the new installation directory, install the required gems:

   bundle install --without development test
   

   If ImageMagick is not installed on your system, skip the rmagick group:

   bundle install --without development test rmagick
   

   Re-run this command if you change the database adapter in config/database.yml.

6. Regenerate the secret token

   If you are upgrading from Redmine 2.x or earlier, first remove the old secret file if it exists:

   rm -f config/initializers/secret_token.rb
   

   Then generate a new secret:

   bundle exec rake generate_secret_token
   

   Do not replace or edit any other files during this step.

7. Compile assets (optional)

   Redmine recompiles assets automatically on startup. To precompile manually:

   bundle exec rake assets:precompile RAILS_ENV="production"
   

   For sub-URI deployments:

   bundle exec rake assets:precompile RAILS_ENV="production" RAILS_RELATIVE_URL_ROOT=/redmine
   

   If you encounter missing assets, clear the output first:

   bundle exec rake assets:clobber RAILS_ENV="production"
   bundle exec rake assets:precompile RAILS_ENV="production"
   
8. Migrate the database

   Apply any pending schema migrations:

   bundle exec rake db:migrate RAILS_ENV="production"
   

   If you have installed plugins, run their migrations as well:

   bundle exec rake db:migrate_plugins RAILS_ENV="production"
   

   If you are also upgrading from a very old Rails version (2.3.14), run plugin migration upgrades first:

   bundle exec rake db:migrate:upgrade_plugin_migrations RAILS_ENV="production"
   
9. Clear cache and sessions

   Clear the application cache and existing sessions:

   bundle exec rake tmp:cache:clear tmp:sessions:clear
   
10. Restart the application server

    Restart your application server (Puma, Passenger, Unicorn, etc.) to load the new code.

11. Check roles and permissions

    Log in as an administrator and navigate to Administration → Roles & permissions to review and configure permissions for any new features introduced in the upgraded version.

Plugin compatibility

Plugins are not guaranteed to be compatible across major Redmine versions. After upgrading:

1. Check each plugin’s repository or documentation for compatibility with the new Redmine version.
2. Update or remove plugins that are not compatible before running migrations.
3. Some plugins may require separate migration steps via rake db:migrate_plugins.