src/docs/user/upgrading.diviner

   1 @title Upgrading Phabricator
   2 @group intro
   3
   4 This document contains instructions for keeping Phabricator up to date.
   5
   6 Overview
   7 ========
   8
   9 Phabricator is under active development, and new features are released
  10 continuously. Staying up to date will keep your install secure.
  11
  12 We recommend installs upgrade regularly (every 1-2 weeks). Upgrades usually go
  13 smoothly and complete in a few minutes. If you put off upgrades for a long
  14 time, it may take a lot more work to bring things up to date if you want access
  15 to a useful new feature or an important security change.
  16
  17
  18 Staying On Top of Changes
  19 =========================
  20
  21 We release a weekly [[https://secure.phabricator.com/w/changelog | Changelog]],
  22 which describes changes in the previous week. You can look at the changelogs
  23 for an idea of what new features are available, upcoming changes, security
  24 information, and warnings about compatibility issues or migrations.
  25
  26
  27 Stable Branch
  28 =============
  29
  30 You can either run the `master` or `stable` branch of Phabricator. The `stable`
  31 branch is run in the [[ https://phacility.com | Phacility Cluster ]], and lags
  32 about a week behind `master`.
  33
  34 The `stable` branch is a little more stable than `master`, and may be helpful
  35 if you administrate a larger install.
  36
  37 We promote `master` to `stable` about once a week, then publish the changelog
  38 and deploy the cluster. During the week, major bugfixes are cherry-picked to
  39 the `stable` branch. The changelog lists the `stable` hashes for that week,
  40 as well as any fixes which were cherry-picked.
  41
  42 To switch to `stable`, check the branch out in each working copy:
  43
  44   phabricator/ $ git checkout stable
  45   arcanist/ $ git checkout stable
  46
  47 You can now follow the upgrade process normally.
  48
  49
  50 Upgrade Process
  51 ===============
  52
  53 IMPORTANT: You **MUST** restart Phabricator after upgrading. For help, see
  54 @{article:Restarting Phabricator}.
  55
  56 IMPORTANT: You **MUST** upgrade `arcanist` and `phabricator` at the same time.
  57
  58 Phabricator runs on many different systems, with many different webservers.
  59 Given this diversity, we don't currently maintain a comprehensive upgrade
  60 script which can work on any system. However, the general steps are the same
  61 on every system:
  62
  63   - Stop the webserver (including `php-fpm`, if you use it).
  64   - Stop the daemons, with `phabricator/bin/phd stop`.
  65   - Run `git pull` in `arcanist/` and `phabricator/`.
  66   - Run `phabricator/bin/storage upgrade`.
  67   - Start the daemons, with `phabricator/bin/phd start`.
  68   - Restart the webserver (and `php-fpm`, if you stopped it earlier).
  69
  70 For some more discussion details, see @{article:Configuration Guide}.
  71
  72 This template script roughly outlines the steps required to upgrade Phabricator.
  73 You'll need to adjust paths and commands a bit for your particular system:
  74
  75 ```lang=sh
  76 #!/bin/sh
  77
  78 set -e
  79 set -x
  80
  81 # This is an example script for updating Phabricator, similar to the one used to
  82 # update <https://secure.phabricator.com/>. It might not work perfectly on your
  83 # system, but hopefully it should be easy to adapt. This script is not intended
  84 # to work without modifications.
  85
  86 # NOTE: This script assumes you are running it from a directory which contains
  87 # arcanist/, and phabricator/.
  88
  89 ROOT=`pwd` # You can hard-code the path here instead.
  90
  91 ### STOP WEB SERVER AND DAEMONS ###############################################
  92
  93 # Stop daemons.
  94 $ROOT/phabricator/bin/phd stop
  95
  96 # If running the notification server, stop it.
  97 # $ROOT/phabricator/bin/aphlict stop
  98
  99 # Stop the webserver (apache, nginx, lighttpd, etc). This command will differ
 100 # depending on which system and webserver you are running: replace it with an
 101 # appropriate command for your system.
 102 # NOTE: If you're running php-fpm, you should stop it here too.
 103
 104 sudo /etc/init.d/httpd stop
 105
 106 ### UPDATE WORKING COPIES ######################################################
 107
 108 cd $ROOT/arcanist
 109 git pull
 110
 111 cd $ROOT/phabricator
 112 git pull
 113
 114 # Upgrade the database schema. You may want to add the "--force" flag to allow
 115 # this script to run noninteractively.
 116 $ROOT/phabricator/bin/storage upgrade
 117
 118 # Restart the webserver. As above, this depends on your system and webserver.
 119 # NOTE: If you're running php-fpm, restart it here too.
 120 sudo /etc/init.d/httpd start
 121
 122 # Restart daemons.
 123 $ROOT/phabricator/bin/phd start
 124
 125 # If running the notification server, start it.
 126 # $ROOT/phabricator/bin/aphlict start
 127 ```