Upgrading ChiliProject¶

Contents

• Upgrading ChiliProject
  • Step 1 - Check requirements
  • Step 2 - Backup data
  • Step 3 - Update the code
    • Git clone from the official repository
      • Upgrade to an official tagged release
      • Upgrade to an official branch
    • Zip or Tar archive
  • Step 4 - Library installation
  • Step 5 - Configuration
    • Server configuration
    • Session storage
  • Step 6 - Database update
  • Step 7 - Plugin Database update
  • Step 8 - Clean up
    • Clear caches and sessions
    • Clear logs (optional)
  • Step 9 - Restart Application Server
  • Step 10 - Final check

If you are looking to upgrade from Redmine to ChiliProject, please read Migrate From Redmine.

Step 1 - Check requirements¶

In order to successfully install and run ChiliProject, make sure you meet the system requirements.

Step 2 - Backup data¶

Always backup you data before any upgrade. You will need to backup:

• File uploads - stored in files/ or another custom directory as defined in your Configuration File.
• Database

For major upgrades (e.g. 1.1.0 to 2.0.0) or migrations from another system it is also recommended that you backup your entire installation directory too.

You should reset UI theme to default before upgrading from 2.x to 3.x to avoid problems after upgrade. Go to Administration → Settings → Display and set theme to "Default". If you missed that step you can edit settings table manually and set ui_theme parameter to an empty string.

Step 3 - Update the code¶

The exact process to upgrade the code is different depending on how you have installed the system.

Git clone from the official repository¶

If you have a clone of the official repository, "gitting" the latest code is quite easy.

If you have made code changes to your ChiliProject, you will need to use git merge in order to keep them.

Upgrade to an official tagged release¶

Assuming you are following the releases and want to get the official 3.1.0 release (you will probably need to adapt the version number here):

git fetch origin       # Grabs the latest official code
git checkout v3.1.0    # Checks out the v3.1.0 tag version

Upgrade to an official branch¶

If you want to follow an official branch in order to get updates more often than the official releases, you can just change what version to merge in your git command. Make sure to read ChiliProject Repository to see the branch names, how stable they are, and what you can expect.

git fetch origin              # Grabs the latest official code
git checkout origin/master    # Checks out the master branch, which will become the "next-release" 

Zip or Tar archive¶

To upgrade from a zip or tar archive you will basically be setting up the new version and swapping your existing configuration over.

Assuming your current install directory is called "chiliproject"

1. Rename the directory for your old install to something like "chiliproject-old"
2. Extract the archive to the name of your old install ("chiliproject")
3. Copy over the configuration files from the old install to the upgrade directory. If your old install didn't have a file, you can skip it
   • config/database.yml
   • config/configuration.yml
   • config/initializers/session_store.rb
   • config/additional_environment.rb
4. Copy your file uploads from your old install. These are stored in the files/ directory by default.
5. Copy any third party themes you had installed. These are stored in public/themes by default.
6. Copy any third party plugins you had installed. These are stored in vendor/plugins but there are several plugins that come with ChiliProject so you only want to copy the ones that are missing that you installed.

Once this is complete, you can continue with the rest of the upgrade.

Step 4 - Library installation¶

After updating the code, you will need to use bundler in order to get updates to any libraries (RubyGems). This can be done using the bundle command in the root directory of ChiliProject

bundle update

See our documentation for setting up bundler for some additional settings and configuration options.

Step 5 - Configuration¶

Server configuration¶

ChiliProject has a system configuration file that is used to configure various options for your server. There are good defaults for most of the values but take a look at the Configuration File page to see if you want to change anything.

If you want to setup a new configuration file just copy the example file with a command like:

cp config/configuration.yml.example config/configuration.yml

Session storage¶

Next you should generate a session storage file. This is a small bit of code that is used to encrypt ChiliProject's login cookies. To generate it, run the following command. It should save a file in config/initializers/session_store.rb.

bundle exec rake generate_session_store

Step 6 - Database update¶

The database migrations (steps 6 and 7) can be very sensitive to the consistency of your data, especially scenarios in which some data has been deleted "by hand" leaving orphaned records behind which don't impact day-to-day operation but are known to cause database migrations to break and abort. If you ever encounter such a case, please seek help in the forums, we will try our best to help you bring your database to a consistent enough state.

Next you will need to run the rake command to upgrade the schema and contents of your database. Go to the directory of your ChiliProject install and run:

bundle exec rake db:migrate RAILS_ENV=production

Step 7 - Plugin Database update¶

Core and third party plugins may include database updates too so you will want to run the following command to upgrade them also.

bundle exec rake db:migrate:plugins RAILS_ENV=production

Step 8 - Clean up¶

Now your code and data is upgraded and you are ready to finish the process by loading the new code.

Clear caches and sessions¶

In order to make sure old code isn't running you should clear any old caches and sessions.

bundle exec rake tmp:cache:clear
bundle exec rake tmp:sessions:clear

Clear logs (optional)¶

If you are not rotating your log files automatically, it would be a good time to clear your log files.

1. Backup your existing log files if you want to save them, cp -a log/*.log /some/safe/archiving_place/
2. Run the rake command to clear all of the logs rake log:clear

Step 9 - Restart Application Server¶

Next the application servers should be restarted so the new code is loaded. The application servers are processes like mongrel, thin, or passenger. You do not need to reboot the entire server. It depends on your application server which process you have to follow.

Step 10 - Final check¶

Now your ChiliProject is upgraded and running. You should login as an Administrator and do a few quick checks:

• Visit "Admin > Information"
  • Make sure that the version has been updated.
  • Make sure that all of the required options are green.
• Visit "Admin > Settings"
  • Check all of the tabs for any new options and set them as needed.
• Visit "Admin > Roles & Permisisons"
  • Check for any new permissions and configure them for your system