RefractTrack Upgrading

Upgrading

This page covers moving an existing, already-installed RefractTrack up to a newer version. If you're setting RefractTrack up for the very first time, you want Getting Started instead.

Upgrading is a files-only operation — it never touches your database directly. Your projects, tasks, users, uploaded attachments, and settings are never copied over or replaced, since the new files simply sit down next to config/ and uploads/ without touching either. If the new version needs anything to change about the shape of the database (a new column, for example), that's handled separately, automatically, the next time an admin logs in — see Database updates below.

The upgrade script

Every RefractTrack download includes an upgrade.sh script for this, in two places:

refracttrack/scripts/upgrade.sh — a short, no-questions-asked version for people comfortable typing a path or two on the command line.
refracttrack_server/upgrade.sh — a guided, prompt-you-for-everything version of the same thing, better if you'd rather not have to remember exact paths.

Both do exactly the same underlying copy, and it's safe to use either one — pick whichever fits how you like to work. This page walks through the guided version, since it explains itself as it goes.

You'll need root (administrator) access on the server to run either one — the live install is normally owned by the web server's own account (commonly www-data), and only root can safely copy files into it while preserving that ownership.

Running it

Download the new version and unzip it, the same way you did the first time — you should end up with a refracttrack/ folder and a refracttrack_server/ folder sitting next to each other.
From that location, run refracttrack_server/upgrade.sh as root.
It'll ask where the new code is (it defaults to the sibling refracttrack/ folder it just found, so you can usually just press enter).
It'll ask where your live install is. It tries to find this for you automatically by scanning your Apache configuration for a site that already looks like a RefractTrack install — if it finds exactly one, it'll offer that as the default. If it finds none, or more than one, it'll just ask you to type or paste the path.
It shows you a preview of exactly what would change — every file that would be added, replaced, or removed — before it asks you to confirm anything. Nothing is copied yet at this point, so it's a safe point to stop and double-check if something looks off.
Once you confirm, it copies the new files over, deliberately skipping your config/ folder and your uploads/ folder entirely — your database credentials and every attachment your team has ever uploaded are untouched, by construction.
It offers to fix up file ownership on the newly-copied files to match whatever your live install was already using, so you don't end up with a permissions headache afterward.

That's it — no database step, no restart to remember, no service to bounce.

Database updates

Some versions of RefractTrack add something new to the database itself, not just to the application code — a new column to support a new feature, for example. When that happens, upgrading the files alone isn't quite the whole story, but you don't need to do anything special for it either:

The moment an admin next logs in after the file upgrade, RefractTrack notices the database is a step behind the code and automatically walks them through a one-click "Apply Update" screen. It's quick, safe to run more than once if you're not sure whether it already ran, and doesn't require any command-line work.
Everyone else just sees a brief "please wait, an update is being applied" message for the short window before an admin gets to that screen — nobody is locked out, and nothing is lost.
If you'd rather trigger this from the command line as part of a deploy script instead of waiting for someone to click through a web page, there's a CLI equivalent: php scripts/migrate.php, run from inside the refracttrack/ folder. It's safe to run this even if there's nothing pending (it just does nothing), and it's safe to run at the same time someone else happens to click through the web version — they won't step on each other.

Because the file copy and the database update are two separate, independent steps, there's a brief window right after a file upgrade where the newly-copied code is running against an old-shaped database. RefractTrack is built to tolerate this gracefully rather than error out — but it's still worth getting an admin to log in (and click through the update screen, if one appears) soon after upgrading, rather than leaving it for days.

A quick note for older installs

If your install has been running for a long time without ever having the php-zip PHP extension (needed for the zip backup system), an upgrade won't install it for you automatically — upgrading is deliberately files-only and never touches installed system packages. If project backups stop working after an upgrade, that's the first thing to check with your host (apt-get install php-zip on a Debian/Ubuntu server, then a reload of PHP/Apache, is normally all it takes).

Related pages