Upgrading Phorge

Phorge Administrator and User Documentation (Introduction)

This document contains instructions for keeping Phorge up to date.

Overview

Phorge is under active development, and new features are released continuously. Staying up to date will keep your install secure.

We recommend installs upgrade regularly (every 1-2 weeks). Upgrades usually go smoothly and complete in a few minutes. If you put off upgrades for a long time, it may take a lot more work to bring things up to date if you want access to a useful new feature or an important security change.

Staying On Top of Changes

We release a Changelog, which describes changes over time. You can look at the changelogs for an idea of what new features are available, upcoming changes, security information, and warnings about compatibility issues or migrations.

Stable Branch

You can either run the master or stable branch of Phorge. The stable branch is a little more stable than master, and may be helpful if you administrate a larger install.

We promote master to stable frequently, then publish the changelog. During the week, major bugfixes are cherry-picked to the stable branch. The changelog lists the stable hashes for that week, as well as any fixes which were cherry-picked.

To switch to stable, check the branch out in each working copy:

phorge/ $ git checkout stable
arcanist/ $ git checkout stable

You can now follow the upgrade process normally.

Upgrade Process

Phorge runs on many different systems, with many different webservers. Given this diversity, we don't currently maintain a comprehensive upgrade script which can work on any system. However, the general steps are the same on every system:

• Stop the webserver (including php-fpm, if you use it).
• Stop the daemons, with phorge/bin/phd stop.
• Run git pull in arcanist/ and phorge/.
• Run phorge/bin/storage upgrade.
• Start the daemons, with phorge/bin/phd start.
• Restart the webserver (and php-fpm, if you stopped it earlier).

For some more discussion details, see Configuration Guide.

This template script roughly outlines the steps required to upgrade Phorge. You'll need to adjust paths and commands a bit for your particular system:

#!/bin/sh

set -e
set -x

# This is an example script for updating Phorge, similar to the one used to
# update <https://we.phorge.it/>. It might not work perfectly on your
# system, but hopefully it should be easy to adapt. This script is not intended
# to work without modifications.

# NOTE: This script assumes you are running it from a directory which contains
# arcanist/, and phorge/.

ROOT=`pwd` # You can hard-code the path here instead.

### STOP WEB SERVER AND DAEMONS ###############################################

# Stop daemons.
$ROOT/phorge/bin/phd stop

# If running the notification server, stop it.
# $ROOT/phorge/bin/aphlict stop

# Stop the webserver (apache, nginx, lighttpd, etc). This command will differ
# depending on which system and webserver you are running: replace it with an
# appropriate command for your system.
# NOTE: If you're running php-fpm, you should stop it here too.

sudo /etc/init.d/httpd stop

### UPDATE WORKING COPIES ######################################################

cd $ROOT/arcanist
git pull

cd $ROOT/phorge
git pull

# Upgrade the database schema. You may want to add the "--force" flag to allow
# this script to run noninteractively.
$ROOT/phorge/bin/storage upgrade

# Restart the webserver. As above, this depends on your system and webserver.
# NOTE: If you're running php-fpm, restart it here too.
sudo /etc/init.d/httpd start

# Restart daemons.
$ROOT/phorge/bin/phd start

# If running the notification server, start it.
# $ROOT/phorge/bin/aphlict start