From 91447c54bce00abd2b18a6c4627ad1cfabff71ca Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Wed, 2 Dec 2015 09:06:32 -0800
Subject: [PATCH] Write 500 words on how to restart webservers

Summary:
Fixes T9874.

  - Stop using the phrase "restart your webserver". Instead, say "restart Phabricator".
  - Write a document explaining that "Restart Phabricator" means to restart all of the server processes, depending on how your configuration is set up, and approximately how to do that.
  - Link to this document.
  - In places where we are not specifically giving instructions and the user isn't expected to do anything, be intentionally vague so as to avoid being misleading.

Test Plan:
  - Read document.
  - Hit "exetnsion" and "PHP config" setup checks, got "restart Phabricator" with documentation links in both cases.

Reviewers: chad

Maniphest Tasks: T9874

Differential Revision: https://secure.phabricator.com/D14636
---
 .../provider/PhabricatorJIRAAuthProvider.php  |   2 +-
 .../cache/spec/PhabricatorOpcodeCacheSpec.php |   6 +-
 .../option/PhabricatorUIConfigOptions.php     |   2 +-
 .../config/view/PhabricatorSetupIssueView.php |  25 +++-
 .../advanced_configuration.diviner            |   7 +-
 .../user/configuration/custom_fields.diviner  |   8 +-
 src/docs/user/field/restarting.diviner        | 116 ++++++++++++++++++
 src/docs/user/upgrading.diviner               |   3 +-
 8 files changed, 151 insertions(+), 18 deletions(-)
 create mode 100644 src/docs/user/field/restarting.diviner

diff --git a/src/applications/auth/provider/PhabricatorJIRAAuthProvider.php b/src/applications/auth/provider/PhabricatorJIRAAuthProvider.php
index 8bbbedc3c6..4b9d53db85 100644
--- a/src/applications/auth/provider/PhabricatorJIRAAuthProvider.php
+++ b/src/applications/auth/provider/PhabricatorJIRAAuthProvider.php
@@ -171,7 +171,7 @@ final class PhabricatorJIRAAuthProvider extends PhabricatorOAuth1AuthProvider {
           "The PHP 'openssl' extension is not installed. You must install ".
           "this extension in order to add a JIRA authentication provider, ".
           "because JIRA OAuth requests use the RSA-SHA1 signing algorithm. ".
-          "Install the 'openssl' extension, restart your webserver, and try ".
+          "Install the 'openssl' extension, restart Phabricator, and try ".
           "again."));
     }
 
diff --git a/src/applications/cache/spec/PhabricatorOpcodeCacheSpec.php b/src/applications/cache/spec/PhabricatorOpcodeCacheSpec.php
index f9739a0328..37c02a437b 100644
--- a/src/applications/cache/spec/PhabricatorOpcodeCacheSpec.php
+++ b/src/applications/cache/spec/PhabricatorOpcodeCacheSpec.php
@@ -87,7 +87,7 @@ final class PhabricatorOpcodeCacheSpec extends PhabricatorCacheSpec {
           'The "%s" setting is currently disabled in your PHP configuration, '.
           'but Phabricator is running in development mode. This option should '.
           'normally be enabled in development so you do not need to restart '.
-          'your webserver after making changes to the code.',
+          'anything after making changes to the code.',
           'apc.stat');
 
         $this
@@ -135,8 +135,8 @@ final class PhabricatorOpcodeCacheSpec extends PhabricatorCacheSpec {
 
         $message = pht(
           'In development, OPcache should be configured to always reload '.
-          'code so the webserver does not need to be restarted after making '.
-          'changes. To do this, enable "%s" and set "%s" to 0.',
+          'code so nothing needs to be restarted after making changes. To do '.
+          'this, enable "%s" and set "%s" to 0.',
           'opcache.validate_timestamps',
           'opcache.revalidate_freq');
 
diff --git a/src/applications/config/option/PhabricatorUIConfigOptions.php b/src/applications/config/option/PhabricatorUIConfigOptions.php
index d97225979d..84a7b4be6b 100644
--- a/src/applications/config/option/PhabricatorUIConfigOptions.php
+++ b/src/applications/config/option/PhabricatorUIConfigOptions.php
@@ -85,7 +85,7 @@ EOJSON;
               'is true and otherwise view policy user; mismatches in these '.
               'policy settings will result in a broken logo for some users.'.
               "\n\n".
-              'You should restart your webserver after updating this value '.
+              'You should restart Phabricator after updating this value '.
               'to see this change take effect.'.
               "\n\n".
               'As this feature is experimental, please read [[ %s | T4214 ]] '.
diff --git a/src/applications/config/view/PhabricatorSetupIssueView.php b/src/applications/config/view/PhabricatorSetupIssueView.php
index cb8859bb86..ed82ffa7b7 100644
--- a/src/applications/config/view/PhabricatorSetupIssueView.php
+++ b/src/applications/config/view/PhabricatorSetupIssueView.php
@@ -87,9 +87,10 @@ final class PhabricatorSetupIssueView extends AphrontView {
         "OS X, you might want to try Homebrew.");
 
       $restart_info = pht(
-        'After installing new PHP extensions, <strong>restart your webserver '.
-        'for the changes to take effect</strong>.',
-        hsprintf(''));
+        'After installing new PHP extensions, <strong>restart Phabricator '.
+        'for the changes to take effect</strong>. For help with restarting '.
+        'Phabricator, see %s in the documentation.',
+        $this->renderRestartLink());
 
       $description[] = phutil_tag(
         'div',
@@ -412,9 +413,10 @@ final class PhabricatorSetupIssueView extends AphrontView {
       'p',
       array(),
       pht(
-        'After editing the PHP configuration, <strong>restart your '.
-        'webserver for the changes to take effect</strong>.',
-        hsprintf('')));
+        'After editing the PHP configuration, <strong>restart Phabricator for '.
+        'the changes to take effect</strong>. For help with restarting '.
+        'Phabricator, see %s in the documentation.',
+        $this->renderRestartLink()));
 
     return phutil_tag(
       'div',
@@ -547,4 +549,15 @@ final class PhabricatorSetupIssueView extends AphrontView {
       ));
   }
 
+  private function renderRestartLink() {
+    $doc_href = PhabricatorEnv::getDoclink('Restarting Phabricator');
+    return phutil_tag(
+      'a',
+      array(
+        'href' => $doc_href,
+        'target' => '_blank',
+      ),
+      pht('Restarting Phabricator'));
+  }
+
 }
diff --git a/src/docs/user/configuration/advanced_configuration.diviner b/src/docs/user/configuration/advanced_configuration.diviner
index 70a78fc902..17212ad4ee 100644
--- a/src/docs/user/configuration/advanced_configuration.diviner
+++ b/src/docs/user/configuration/advanced_configuration.diviner
@@ -107,9 +107,10 @@ setenv.add-environment = (
 )
 ```
 
-After creating and selecting a configuration file, restart your webserver. Any
-configuration you set should take effect immediately, and your file should be
-visible in the Config application when examining configuration.
+After creating and selecting a configuration file, restart Phabricator (for
+help, see @{article:Restarting Phabricator}). Any configuration you set should
+take effect immediately, and your file should be visible in the Config
+application when examining configuration.
 
 = Next Steps =
 
diff --git a/src/docs/user/configuration/custom_fields.diviner b/src/docs/user/configuration/custom_fields.diviner
index 7ecfa98723..9bd1bb0e28 100644
--- a/src/docs/user/configuration/custom_fields.diviner
+++ b/src/docs/user/configuration/custom_fields.diviner
@@ -170,9 +170,11 @@ want to add a field to:
 | Projects | @{class:PhabricatorProjectCustomField} |
 
 The easiest way to get started is to drop your subclass into
-`phabricator/src/extensions/`, which should make it immediately available in the
-UI (if you use APC, you may need to restart your webserver). For example, this
-is a simple template which adds a custom field to Maniphest:
+`phabricator/src/extensions/`. If Phabricator is configured in development
+mode, the class should immediately be available in the UI. If not, you can
+restart Phabricator (for help, see @{article:Restarting Phabricator}).
+
+For example, this is a simple template which adds a custom field to Maniphest:
 
   name=ExampleManiphestCustomField.php
   <?php
diff --git a/src/docs/user/field/restarting.diviner b/src/docs/user/field/restarting.diviner
new file mode 100644
index 0000000000..5bdd92da78
--- /dev/null
+++ b/src/docs/user/field/restarting.diviner
@@ -0,0 +1,116 @@
+@title Restarting Phabricator
+@group fieldmanual
+
+Instructions on how to restart HTTP and PHP servers to reload configuration
+changes in Phabricator.
+
+
+Overview
+========
+
+Phabricator's setup and configuration instructions sometimes require you to
+restart your server processes, particularly after making configuration changes.
+This document explains how to restart them properly.
+
+In general, you need to restart both whatever is serving HTTP requests and
+whatever is serving PHP requests. In some cases, these will be the same process
+and handled with one restart command. In other cases, they will be two
+different processes and handled with two different restart commands.
+
+{icon exclamation-circle color=blue} If you have two different processes (for
+example, nginx and PHP-FPM), you need to issue two different restart commands.
+
+It's important to restart both your HTTP server and PHP server because each
+server caches different configuration and settings. Restarting both servers
+after making changes ensures you're running up-to-date configuration.
+
+To restart properly:
+
+  - Identify which HTTP server you are running (for example, Apache or nginx).
+  - Identify which PHP server you are running (for example, mod_php or PHP-FPM).
+  - For each server, follow the instructions below to restart it.
+  - If the instructions tell you to do so, make sure you restart **both**
+    servers!
+
+
+Quick Start
+===========
+
+**Apache**: If you use Apache with `mod_php`, you can just restart Apache. You
+do not need to restart `mod_php` separately. See below for instructions on how
+to do this if you aren't sure. This is a very common configuration.
+
+**nginx**: If you use nginx with PHP-FPM, you need to restart both nginx and
+PHP-FPM. See below for instructions on how to do this if you aren't sure. This
+is also a very common configuration.
+
+It's possible to use Apache or nginx in other configurations, or a different
+webserver. Consult the documentation for your system or webserver if you aren't
+sure how things are set up.
+
+
+Universal Restart
+=================
+
+If you are having trouble properly restarting processes on your server, try
+turning it off and on again. This is effective on every known system and
+under all configurations.
+
+
+HTTP Server: Apache
+===================
+
+If you are using Apache with `mod_php`, you only need to restart Apache.
+
+If you are using Apache in FastCGI mode, you need to restart both Apache and
+the FCGI server (usually PHP-FPM). This is very unusual.
+
+The correct method for restarting Apache depends on what system you are
+running. Consult your system documentation for details. You might use a command
+like one of these on your system, or a different command:
+
+```
+$ sudo apachectl restart
+$ sudo /etc/init.d/httpd restart
+$ sudo service apache2 restart
+```
+
+
+HTTP Server: Nginx
+==================
+
+If you're using Nginx with PHP-FPM, you need to restart both of them. This is
+the most common Nginx configuration.
+
+The correct method for restarting Nginx depends on what system you are running.
+Consult your system documentation for details. You might use a command like
+one of these on your system, or a different command:
+
+```
+$ sudo /etc/init.d/nginx restart
+$ sudo service nginx restart
+```
+
+
+PHP Server: mod_php
+===================
+
+This is a builtin PHP server that runs within Apache. Restarting Apache (see
+above) is sufficient to restart it. There is no separate restart command for
+`mod_php`, so you don't need to do anything else.
+
+
+PHP Server: PHP-FPM
+===================
+
+If you're using FastCGI mode, PHP-FPM is the most common PHP FastCGI server.
+You'll need to restart it if you're running it.
+
+The correct method for restarting PHP-FPM depends on what system you are
+running. Consult your system documentation for details. You might use a command
+like one of these on your system, or a different command:
+
+```
+$ sudo /etc/init.d/php-fpm restart
+$ sudo service php5-fpm reload
+```
diff --git a/src/docs/user/upgrading.diviner b/src/docs/user/upgrading.diviner
index 4291ded636..d9eca240ec 100644
--- a/src/docs/user/upgrading.diviner
+++ b/src/docs/user/upgrading.diviner
@@ -51,7 +51,8 @@ You can now follow the upgrade process normally.
 Upgrade Process
 ===============
 
-IMPORTANT: You **MUST** restart Apache or PHP-FPM after upgrading.
+IMPORTANT: You **MUST** restart Phabricator after upgrading. For help, see
+@{article:Restarting Phabricator}.
 
 IMPORTANT: You **MUST** upgrade `libphutil`, `arcanist` and `phabricator` at
 the same time.