Item11262: Install guide updates

core/data/System/InstallationGuide.txt

@@ -1,11 +1,15 @@
 %META:TOPICINFO{author="ProjectContributor" comment="reprev" date="1429736137" format="1.1" reprev="6" version="1"}%
 <noautolink>
 ---+!! Installation Guide
+<div class='foswikiHelp' style='border:2px orange solid' >
+This guide describes the steps for manually installing Foswiki, with __specific steps for installations on Linux with the Apache web server__.%BR%
+If you would prefer to use a different web server, please refer to supplemental documentation when you reach the Apache-specific steps:
+   * *Nginx:* [[http://foswiki.org/Support/FoswikiOnNginx][Foswiki on Nginx]]
+   * *Lighttpd:* [[http://foswiki.org/Support/LighttpdBestPractice][Foswiki on Lighttpd]]
+</div>
 
 %TOC{title="Contents"}%
 
-*This guide describes the steps for manually installing Foswiki, with specific steps for installations on Linux with the Apache web server.*
-
 *Rather not install manually?* Visit Foswiki:Download.OtherFoswikiInstallers for automated installers, and virtual machine images. These automate much of the install process and may help some users get started more easily. For instructions for using those packages, refer to documentation provided there. Note that the installers are optimized for the target system, and do not necessarily follow the normal Foswiki directory structure documented below.
 
 *Upgrading?* Please see the [[Foswiki:System.UpgradeGuide][upgrade guide]].
@@ -14,10 +18,10 @@
 
 *Need help?* Visit Foswiki:Support web or Foswiki:Community.InternetRelayChat (irc.freenode.net, channel #foswiki).
 
-This guide assumes the a basic knowledge of server administration on the system being used. For more information, see Foswiki:System.AdminSkillsAssumptions.
 
 ---++ Before you start
 
+   * This guide assumes the a basic knowledge of server administration on the system being used. For more information, see Foswiki:System.AdminSkillsAssumptions.
    * Review the [[#SystemRequirements][System Requirements]] (below) to make sure you have server prerequisites installed.
    * If you need to install any Perl libraries from CPAN, see Foswiki:Support.HowToInstallCpanModules for more information.
 
@@ -26,13 +30,14 @@ This guide assumes the a basic knowledge of server administration on the system
 Here's the quick version of the instructions, for those that are already comfortable with performing such installations. More detailed instructions follow.
 
    1 [[Foswiki:Download/][Download]] and unpack the latest version of Foswiki.
-   1 Configure Apache using the Foswiki:Support.ApacheConfigGenerator tool to generate a safe, working config file for your Foswiki installation. (Install the file and restart Apache).
-      * In shared hosting environment where you don't have access to Apache config files, copy the 4 files named "[directory]-htaccess.txt" from the root of Foswiki installation into the 8 the subdirectores, renamed to ".htaccess".  (include the leading period).  Tailor them per embedded comments.  (see [[#ConfigWithHtaccess][more details below]]).
+   1 Configure Apache using the Foswiki:Support.ApacheConfigGenerator tool to generate a safe, working config file for your Foswiki installation.
+      * Install the generated file and restart Apache.
+      * In shared hosting environment where you don't have access to Apache config files, see [[#ConfigWithHtaccess][the instructions in step 4 below for configuring using =.htaccess= files]].
    1 Bootstrap your the install by browsing to the default view URL for your site in your web browser. Depending upon your Apache configuration, your view URL might look something like:
       * =http<nop>://yoursite.com=
       * =http<nop>://yoursite.com/bin/view=
       * =http<nop>://yoursite.com/foswiki/bin/view=
-   1 Follow the link in the Bootstrap banner of the returned page to the bin/configure tool, address any warnings and save your configuration.
+   1 Follow the link in the Bootstrap banner to the configure tool, address any warnings and save your configuration.
 
 That's it! You Foswiki should now be installed. Browse to =/bin/view= and start editing!
 
@@ -47,9 +52,8 @@ At some point, you will want to re-visit [[#ConfigureFoswiki][Configuring Foswik
       * If you have shell access, you can download the distribution directly using using this command: <pre>wget  https://sourceforge.net/projects/foswiki/files/latest/download</pre>
       * If you do not have shell access to your web server host, see the section [[#UploadingFoswikiDistribution][Uploading the Foswiki distribution to your web server host]] below.
    3 *Unpack the distribution file:*
-      * Untar and gunzip the distribution using this command: (modify to match version number)<verbartim>
-       tar -xzvf foswiki-VERSION.tgz
-      </verbatim>A new subdirectory called Foswiki-VERSION will be created.
+      * Untar and gunzip the distribution using this command: (modify to match version number)<verbatim>
+tar -xzvf foswiki-VERSION.tgz</verbatim>A new subdirectory called =Foswiki-VERSION= will be created.
       * You can rename this subdirectory to a shorter name. For the rest of this document, this subdirectory is assumed to be at =/path/to/foswiki=.
       * *Note:* Foswiki does not support directory paths that contain spaces, so ensure that all of its directory paths do not contain any spaces (particularly on Windows).
 
@@ -87,28 +91,32 @@ If you get an error about perl command not found,  the you need to find where yo
 #ConfigureApache
 ---+++ Step 4: Configure the web server
 
-Foswiki provides three methods to configure Apache. The first two use an a Apache config file, which is preferable as it provides better performance and requires editing only one file. However, it requires root or sudo access. Refer to your server's documentation for the particulars of how site configuration files are handled. The third method is for cases where you do not have root access (such as on hosted sites) and involves creating =.htaccess= files for each directory is the foswiki installation.
+There are three methods to configure Apache (listed below). The first two require root or sudo access to the host server, and use an a Apache config file,
+This is preferable as it provides better performance and requires editing only one file.
+Refer to your server's documentation for the particulars of how site configuration files are handled.
+The third method is for cases where you do not have root access (such as on hosted sites). It involves creating =.htaccess= files for each directory in the foswiki installation.
 
-*Method 1: Use Foswiki's automated configuration generator*
+*Method 1: Use Foswiki's automated configuration generator* _(needs root access)_
    * See Foswiki:Support.ApacheConfigGenerator.
    * This is the easiest and best way to generate a smooth-running and secure configuration file.
-   * After installing the config file as per your distribution's guidelines, remember to restart Apache each time you edit the file to apply your changes.
+   * After installing the config file as per your distribution's guidelines, remember to restart or reload Apache each time you edit the file to apply your changes.
 
-*Method 2: Use the config template file included in distribution*
+*Method 2: Customize the config template file included in distribution* _(Needs root access)_
    * A sample config file called =foswiki_httpd_conf.txt= can be found in the root of the foswiki installation.
    * This is provided in case you can not access the online configuration generator.
    * Instructions are provided in the file for tailoring the configuration to you server.
+   * *Be careful* The configuration shipped with Foswiki is for Apache 2.2 or earlier. Apache 2.4 has changed the syntax of the configuration file. Ensure that mod_access_compat is enabled for backwards compatibility when using Apache 2.4
    * As with Method 1, remember to restart Apache each time you edit the file to apply your changes.
 
 #ConfigWithHtaccess
-*Method 3: Using =.htaccess= template files included in distribution*
+*Method 3: Customize the =.htaccess= template files included in distribution* _(Useful on shared hosting sites)_
    * Sample =.htaccess= files for the Foswiki root and each subdirectory are included in the root of your installation. Each file contains instructions on modifying it for your installation. For more information, see Foswiki:Support.SupplementalDocuments. <sticky>
 %TABLE{sort="off"}%
    | *location and name of sample .htaccess file* | *copy sample file to the following location* | *tailoring required (Detailed instuctions in each file)* |
    | =foswiki/root-htaccess.txt= | =foswiki/.htaccess= | _Optional:_ redirect to a default page for empty URL. |
    | =foswiki/bin-htaccess.txt= | =foswiki/bin/.htaccess= | Yes - Must find/replace all instances of ={DataDir}=, ={DefaultUrlHost}= and ={ScriptUrlPath}= with valid information. The setting =SetHandler cgi-script= is critical to make sure that scripts in the =bin= directory will be executed by Apache. |
    | =foswiki/pub-htaccess.txt= | =foswiki/pub/.htaccess= | Yes - Must set correct url path on =ErrorDocument= |
-   | =foswiki/subdir-htaccess.txt= | =foswiki/&lt;subdir&gt;/.htaccess= <br />Copy to all other subdirectories below =foswiki=, including =data=, =lib=, =locale=, =templates=, =tools=, =working=.  Copy to any other directories except for =bin= and  =pub= addressed above. | No |</sticky>
+   | =foswiki/subdir-htaccess.txt= | =foswiki/&lt;subdir&gt;/.htaccess= <br /> *Copy to all other subdirectories below =foswiki=, including =data=, =lib=, =locale=, =templates=, =tools=, =working=.*  Copy to any other directories except for =bin= and  =pub= addressed above. | No |</sticky>
 
 <div class='foswikiHelp'>
 %T% *General points to keep in mind with any of the above Apache configuration approaches:*