diff --git a/src/docs/user/installation_guide.diviner b/src/docs/user/installation_guide.diviner index 615ad63fda..4df177540e 100644 --- a/src/docs/user/installation_guide.diviner +++ b/src/docs/user/installation_guide.diviner @@ -167,23 +167,10 @@ If it doesn't show up, add: ..to "/etc/php.d/apc.ini" or the "php.ini" file indicated by "php -i". -= Updating Phabricator = - -Since Phabricator is under active development, you should update frequently. To -update Phabricator: - - - Stop the webserver (including `php-fpm`, if you use it). - - Run `git pull` in `libphutil/`, `arcanist/` and `phabricator/`. - - Run `phabricator/bin/storage upgrade`. - - Restart the webserver (and `php-fpm`, if you stopped it earlier). - -For more details, see @{article:Configuration Guide}. You can use a script -similar to this one to automate the process: - -http://www.phabricator.com/rsrc/install/update_phabricator.sh - = Next Steps = Continue by: - - configuring Phabricator with the @{article:Configuration Guide}. + - configuring Phabricator with the @{article:Configuration Guide}; or + - learning how to keep Phabricator up to date with + @{article:Upgrading Phabricator}. diff --git a/src/docs/user/upgrading.diviner b/src/docs/user/upgrading.diviner new file mode 100644 index 0000000000..e8b7228ade --- /dev/null +++ b/src/docs/user/upgrading.diviner @@ -0,0 +1,130 @@ +@title Upgrading Phabricator +@group intro + +This document contains instructions for keeping Phabricator up to date. + +Overview +======== + +Phabricator 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 weekly [[https://secure.phabricator.com/w/changelog | Changelog]], +which describes changes in the previous week. 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 Phabricator. The `stable` +branch is run in the [[ https://phacility.com | Phacility Cluster ]], and lags +about a week behind `master`. + +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` about once a week, then publish the changelog +and deploy the cluster. 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: + + phabricator/ $ git checkout stable + arcanist/ $ git checkout stable + libphutil/ $ git checkout stable + +You can now follow the upgrade process normally. + + +Upgrade Process +=============== + +IMPORTANT: You **MUST** restart Apache or PHP-FPM after upgrading. + +Phabricator 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 `phabricator/bin/phd stop`. + - Run `git pull` in `libphutil/`, `arcanist/` and `phabricator/`. + - Run `phabricator/bin/storage upgrade`. + - Start the daemons, with `phabricator/bin/phd start`. + - Restart the webserver (and `php-fpm`, if you stopped it earlier). + +For some more discussion details, see @{article:Configuration Guide}. + +This template script roughly outlines the steps required to upgrade Phabricator. +You'll need to adjust paths and commands a bit for your particular system: + +```lang=sh +#!/bin/sh + +set -e +set -x + +# This is an example script for updating Phabricator, similar to the one used to +# update . 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/, libphutil/, and phabricator/. + +ROOT=`pwd` # You can hard-code the path here instead. + +### UPDATE WORKING COPIES ###################################################### + +cd $ROOT/libphutil +git pull + +cd $ROOT/arcanist +git pull + +cd $ROOT/phabricator +git pull + + +### CYCLE WEB SERVER AND DAEMONS ############################################### + +# Stop daemons. +$ROOT/phabricator/bin/phd stop + +# If running the notification server, stop it. +# $ROOT/phabricator/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 + + +# Upgrade the database schema. You may want to add the "--force" flag to allow +# this script to run noninteractively. +$ROOT/phabricator/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/phabricator/bin/phd start + +# If running the notification server, start it. +# $ROOT/phabricator/bin/aphlict start +```