View source for RefractSurvey Upgrading

Upgrading RefractSurvey is two separate things: getting the new '''files''' onto your server, and letting the '''database''' catch up. This is a technical page &mdash; if something here doesn't make sense, an upgrade is a good time to ask whoever manages your server.

== Step 1: Copy the new files over ==

Unzip the new release somewhere on the server, then from inside it, run:

<pre>
sudo refractsurvey_server/upgrade.sh
</pre>

This copies the new application files over your existing live install. It's non-destructive on purpose:

* <code>config/</code> (your database credentials and settings) is left completely untouched.
* <code>uploads/</code> (your survey images) is left completely untouched.
* Nothing is ever deleted from the live install &mdash; files are only added or overwritten.

That's the entire file-copying step. You don't need to stop Apache or take the site offline to run it.

== Step 2: Let the database catch up ==

You usually don't have to do anything for this part. The next time an administrator logs in after an upgrade, if the new code needs a database change it doesn't have yet, they're automatically sent to a one-button '''"Database Update"''' page &mdash; click it, and the database is brought up to date on the spot. Everyone else just sees a brief "please wait" page until that happens.

If you'd rather apply the database update immediately, right after copying files, instead of waiting for someone to log in, run this from inside the (now-upgraded) application root:

<pre>
bash scripts/upgrade.sh
</pre>

This is a separate, CLI-only script that does '''only''' the database part &mdash; it checks that <code>config/config.php</code> exists, confirms the PHP CLI is available, and then applies any pending database migrations. It's the command-line equivalent of clicking the "Database Update" button in a browser, which makes it a good fit for a deploy script that shouldn't depend on a human visiting a web page. If there's nothing pending, it prints that the database is already up to date and exits cleanly &mdash; safe to run even when you're not sure whether an update is needed.

== A note on permissions ==

<code>config/config.php</code> is deliberately locked down to be readable only by the web server's own user and group. If you run <code>scripts/upgrade.sh</code> as a different user, you may see a permission error reading that file. That's expected and not a bug &mdash; run the command as the web server's user (for example, with <code>sudo -u www-data bash scripts/upgrade.sh</code>), or as a user in the same group.

== See also ==

* [[RefractSurvey_Getting_Started|Getting Started]]
* [[RefractSurvey_Automated_Server_Setup|Automated Server Setup]]
* [[RefractSurvey_Security_Notes|Security Notes]]

[[Category:RefractSurvey]]