h1. Upgrading

{{>toc}}

h2. Step 1 - Backup

It is recommended that you backup your database and modifications to Foreman files(config/settings.yaml, unattended installations etc). Most upgrades are safe but it never hurts to have a backup just in case.

h3. MySQL database

The @mysqldump@ command can be used to backup the contents of your MySQL database to a text file.

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.

h2. Step 2 - Perform the upgrade

Now it's time to perform the actual upgrade. This process if different depending on how you downloaded Foreman. You only need to perform *one* of the following options.

h3. Option 1 - Downloaded release (tar.bz2)

# Uncompress the new program archive in a *new directory*.
# Copy your database settings-file @config/database.yml@ into the new @config@ directory.
if your database is a simple file (e.g. SQLite), don't forget to make it available in the new directory.

VERY IMPORTANT: do NOT overwrite @config/settings.yml@ with the old one.

h3. Option 2 - Upgrading from git

*Please note* now that the development branch has moved to Rails 3, you MUST take care to select a branch and make sure you get the correct one.

1. Go to the Foreman root directory and run the following command:

For staying on the stable branch:
<pre><code>
git checkout 0.4-stable
git pull
git submodule init
git submodule update
</code></pre>

> *Or if you have to access github through a proxy using the HTTP urls*
<pre>
git checkout 0.4-stable
git pull
sed -i 's/git:\/\//http:\/\//g' .gitmodules
git submodule init
git submodule update
</pre>

For upgrading to the Rails 3 based "develop" branch:
<pre><code>
create a new directory
checkout a new copy of the code in the new directory using [[Installing_latest_code_]]
manually copy relevant config files
</code></pre>

For upgrading within the Rails 3 develop branch:
<pre><code>
git checkout branch develop
git pull
</code></pre>

h3. Option 3 - Upgrading from a package (RPM, DEB)

Simply update your package via your normally, and you can skip Step 4

h2. Step 4 - Update the database

This step is the one that could change the contents of your database. Go to your new Foreman directory (or the git dir), then migrate your database:

<pre>
rake db: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)

h2. Common issues

see [[Troubleshooting]]