Skip to content

Commit

Permalink
Item11262: UpgradeGuide changes
Browse files Browse the repository at this point in the history 
Merge in changes  made by multiple users on the Foswiki.org sandbox.  As
well as fix some typos and wording.
  • Loading branch information
@gac410
gac410 committed May 5, 2015
1 parent 145154c commit 005ecdd
Show file tree
Hide file tree
Showing 3 changed files with 78 additions and 118 deletions.
4 changes: 2 additions & 2 deletions core/data/System/AdminSkillsAssumptions.txt
View file
@@ -1,4 +1,4 @@
%META:TOPICINFO{author="ProjectContributor" date="1429840432" format="1.1" version="1"}%
%META:TOPICINFO{author="ProjectContributor" date="1430799774" format="1.1" version="1"}%
%META:TOPICPARENT{name="InstallationGuide"}%
---+ Administrator Skills Assumptions

Expand Down Expand Up @@ -55,7 +55,7 @@ production environments.
If you don't know all of these skills, you can learn it! The Internet provides many sources of information about all these skills

There are many excellent resources for learning how to administer your OS and web server, including books, web sites, web forums, IM and e-mail lists. The
Foswiki:Support web must *not* be depended on as a resource for this purpose - in other words, it is not there to answer basic questions about operating
Foswiki:Support web should not be depended on as a resource for this purpose - in other words, it is not there to answer basic questions about operating
system and web server administration. Asking and answering questions is time consuming for all concerned and is best used for specific _Foswiki related_
issues, rather than helping you learn the OS and web server.

Expand Down
58 changes: 32 additions & 26 deletions core/data/System/InstallationGuide.txt
View file
@@ -1,4 +1,4 @@
%META:TOPICINFO{author="ProjectContributor" comment="reprev" date="1429736137" format="1.1" reprev="6" version="1"}%
%META:TOPICINFO{author="ProjectContributor" comment="reprev" date="1430799774" format="1.1" reprev="8" version="1"}%
<noautolink>
---+!! Installation Guide
<div class='foswikiHelp' style='border:2px orange solid' >
Expand All @@ -10,14 +10,15 @@ If you would prefer to use a different web server, please refer to supplemental

%TOC{title="Contents"}%

*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.
*Rather not install manually?* Visit Foswiki:Download.OtherFoswikiInstallers for automated installers, and virtual machine images. These automate much of the installation process and may help some users get started more easily. For instructions using those packages, refer to the 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]].

*Need further information?* Visit Foswiki:Support.SupplementalDocuments for additional notes on installing on different operating systems or shared web-hosting environments, performance tuning, security hardening and more.

*Need help?* Visit Foswiki:Support web or Foswiki:Community.InternetRelayChat (irc.freenode.net, channel #foswiki).

This guide assumes a basic knowledge of server administration on the system being used. For more information, see Foswiki:System.AdminSkillsAssumptions.

---++ Before you start

Expand All @@ -27,7 +28,7 @@ If you would prefer to use a different web server, please refer to supplemental

---++ 5-Minute Install

Here's the quick version of the instructions, for those that are already comfortable with performing such installations. More detailed instructions follow.
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.
Expand All @@ -37,7 +38,7 @@ Here's the quick version of the instructions, for those that are already comfort
* =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 to the configure tool, address any warnings and save your configuration.
1 Follow the link in the Bootstrap banner of the returned page to the bin/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!

Expand All @@ -52,8 +53,10 @@ 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)<verbatim>
tar -xzvf foswiki-VERSION.tgz</verbatim>A new subdirectory called =Foswiki-VERSION= will be created.
* go to your web directory (usually /var/www) or in any directory you what to install Foswiki (designed after by /path/to/foswiki/)
* 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.
* 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).

Expand Down Expand Up @@ -91,22 +94,23 @@ If you get an error about perl command not found, the you need to find where yo
#ConfigureApache
---+++ Step 4: Configure the web server

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.
Foswiki provides several methods to configure Apache depending of your access to *root and sudo* and your preference to set all in one file or several files.

*Method 1: Use Foswiki's automated configuration generator* _(needs root access)_
Method 1 and 2 provide *better performance and requires editing only one file*. However, they *require root or sudo* access. Method 3 is for *cases where you do not have root access* (such as on hosted sites).

In details:

*Method 1: Use Foswiki's 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 or reload Apache each time you edit the file to apply your changes.

*Method 2: Customize the config template file included in distribution* _(Needs root access)_
*Method 2: Customize the Apache 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.
* *Be carefull!* 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 or reload Apache each time you edit the file to apply your changes.

#ConfigWithHtaccess
*Method 3: Customize the =.htaccess= template files included in distribution* _(Useful on shared hosting sites)_
Expand All @@ -116,7 +120,7 @@ The third method is for cases where you do not have root access (such as on host
| =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:*
Expand All @@ -141,7 +145,7 @@ The third method is for cases where you do not have root access (such as on host
<div class='foswikiHelp'>
* %T% If the Foswiki installation can be accessed by more than one !protocol://domain, ensure the additional alternative URLs are set in ={PermittedRedirectHostUrls}=. *Example:* if ={DefaultUrlHost}= is set to =https://wiki.company.com=, an example ={PermittedRedirectHostUrls}= might contain: <verbatim class='html'>https://company.com, http://111.222.123.234</verbatim>
* If your server requires a Proxy in order to access external resources like your mail server, this is configured on the "Security and Authentication" tab, "Proxies" sub-tab. Complete that before proceeding with the E-mail configuration.
* If you do not want to or are unable to configure from the web interface, there is an alternate command line configuration documented in %IF{"$skin = 'plain'" then="<nop>System.<nop>InstallationGuidePart2#ConfiguringFoswikiManually in your installation" else="[[InstallationGuidePart2#ConfiguringFoswikiManually]]"}%.
* If you do not want to or are unable to configure from the web interface, there is an alternate command line configuration documented in %IF{"$skin = 'plain'" then="<nop>System.<nop>InstallationGuide#ConfiguringFoswikiManually in your installation" else="[[InstallationGuide#ConfiguringFoswikiManually]]"}%.
</div>

%IF{"$skin = 'plain'" then="<div class='foswikiHelp' style='border:2px orange solid' >$percntT$percntNow that your Foswiki installation is functional, you are encouraged to view this installation guide on your Foswiki site rather than the static =INSTALL.html= file included in the distribution. This will make it easier to implement the steps which follow because you will be able to use the embedded hyperlinks to jump directly to the referenced pages in your installation. To view this guide in your installation, follow the link provided in the bootstrap banner, or enter =System.InstallationGuide= in the jump-box.</div>"}%
Expand All @@ -151,12 +155,12 @@ The third method is for cases where you do not have root access (such as on host
Outgoing e-mail is required for Foswiki to send registration confirmations, notifications of changes, password reset requests, etc.

1 Select the =Mail= tab in left bar of confgiure and fill out the following parameters:
* The ={WebMasterEmail}= should be set to a valid e-mail address. This will be the From: ID used to send Foswiki Emails and will also appear on webmaster mailto: links. <div class='foswikiHelp'>If you are running on a <nop>*nix server with a configured local mail transport agent, you can try pressing the "%T%auto-configure email" button. If auto-configure succeeds, proceed to #4 below. If your server is a Windows server, if auto-configure failed, or you know a local transport agent is not available, continue with the SMTP e-mail configuration:</div>
* The ={WebMasterEmail}= should be set to a valid e-mail address. This will be the From: ID used to send Foswiki Emails and will also appear on webmaster mailto: links. <div class='foswikiHelp'>If you are running on a <nop>*nix server with a configured local mail transport agent, you can try pressing the "%T%auto-configure email" button. If auto-configure succeeds, proceed to the next step, to send a test email. If your server is a Windows server, if auto-configure failed, or you know a local transport agent is not available, continue with the SMTP e-mail configuration:</div>
* The ={SMTP}{MAILHOST}= should be set to your e-mail server hostame: ex: =smtp.gmail.com=
* On most systems, you will also have to configure ={SMTP}{Username}= and ={SMTP}{Password}=. These are used so that Foswiki can sign into the e-mail server for purposes of sending e-mail.
* Click the "%T%auto-configure email" button. (__This can run a long time as Foswiki probes all possible e-mail configurations__) This will probe the mail server to discover it's configuration, and will finish the configuration. If all goes well, the settings will have been fine tuned for your e-mail server and e-mail is automatically enabled.
4 Once auto-configure completes, *Click the "%T%Send test email" button. located on the ={WebMasterEmail}= field* This will verify if the configuration is correct and able to send mail. If e-mail is enabled, but not functional, you will be unable to register users.
5. Click the Save button in the upper right corner of the configuration page.
1 Once auto-configure completes, *Click the "%T%Send test email" button. located on the ={WebMasterEmail}= field* This will verify if the configuration is correct and able to send mail. If e-mail is enabled, but not functional, you will be unable to register users.
1 Click the Save button in the upper right corner of the configuration page.

<div class='foswikiHelp'>If auto-configure fails to complete, you can use the "Advanced settings" tab to manually configure the e-mail server. You will also need to configure the basic information tab.
Although outgoing email is necessary for user registration, it is not _required_ for Foswiki to run otherwise, so if you are setting up a test installation or don't plan on enabling user registration, you can skip this step.</div>
Expand All @@ -173,19 +177,21 @@ If there are problems, see [[#TestingAuthentication][authentication trouble-shoo
<div class='foswikiHelp'>%T% After completing initial installation, you are strongly encouraged to read %IF{"$skin = 'plain'" then="<nop>System.<nop>UserAuthentication in your installation" else="[[$percntSYSTEMWEB$percnt.UserAuthentication]]"}% and Foswiki:Support.UserAuthenticationSupplement for further information about managing users and access controls for your Foswiki site.</div>

#ProtectConfigure
---+++ Step 8: Protect configure
---+++ Step 8: Establish an Administrator user

The last step in your configuration is to restrict access to the configure tool. *This is critical for the security of your site, particularly on public sites.*
The last step in your configuration is to create and user with administration rights.

<div class='foswikiHelp'>%T% Although there are several options to achieve this, the steps outlined below is recommended for initial configuration. *You should complete this before closing the browser after the bootstrap process.* Once you close the browser you will lose your temporary admin status. Later on, you can review the further notes below regarding [[#AboutAdminUsers][about administrators]] and [[#WaysToProtectConfigure][options to protect configure]] and consider one of the more restrictive options.</div>
<div class='foswikiHelp'>%T% The steps outlined below are recommended for initial configuration. *You should complete this before closing the browser after the bootstrap process.* Once you close the browser you will lose your temporary admin status. Later on, you can review the further notes below regarding [[#AboutAdminUsers][about administrators]] and [[#WaysToProtectConfigure][options to protect configure]] and consider one of the more restrictive options.</div>

Once the Foswiki bootstrap process is closed, configure will be restricted to Foswiki's "AdminGroup", so let add you to that group:
Once the Foswiki bootstrap process is closed, configure will be restricted to Foswiki's "AdminGroup". Add your ID to the administrators group:
1 Go to %IF{"$skin = 'plain'" then="<nop>Main.<nop>AdminGroup in your installation" else="$percntUSERSWEB$percnt.AdminGroup"}%.
1 Scroll down to the "Administration" section and click on "Add Members"
1 Enter your %IF{"$skin = 'plain'" then="$quot<nop>WikiName$quot" else="$percntSYSTEMWEB$percnt.WikiName"}% as defined when you registered yourself in Step 7.
1 Click the Add Member button
1 Return to the <nop>AdminGroup by clicking the group name on the confirmation page and look under "Members" to confirm you have been added.

<div class="foswikiHelp">Foswiki provides multiple ways to protect configure. See [[#AboutAdminUsers]] for more details on how to protect your configuration.</div>

---+++ Step 9. Save your configuration!

Click the Save button in the upper right corner of the configuration page.
Expand All @@ -205,8 +211,8 @@ If you are having problems with your installation, try the following:

* Review the %IF{"$skin = 'plain'" then="<nop>System.<nop>PerlDependencyReport in your installation" else="[[$percntSYSTEMWEB$percnt.PerlDependencyReport]]"}% and sure all dependencies are correctly resolved.
* Run the =configure= script and ensure you have resolved all errors and are satisfied that you understand any warnings.
* You can also access the dependency report from the command line: <verbatim>
cd path/to/foswiki
* You can also access the dependency report from the command line: <verbatim class='bash'>
cd /path/to/foswiki
perl tools/dependencies </verbatim>
* Consult the topics at Foswiki:Support.SupplementalDocuments and Foswiki:Support.AskedQuestions.
* Ask for help on [[Foswiki:Community.InternetRelayChat][IRC]] (irc.freenode.net, channel #foswiki). There are often a number of people waiting to help.
Expand Down Expand Up @@ -365,7 +371,7 @@ tools/configure -save -set {Password}='adminpass' </verbatim>
Any configuration keys may be set using this tool.

To run a wizard, for example autoconfiguration of email:
<verbatim>
<verbatim class='bash'>
tools/configure -save -set {WebMasterEmail}='user@email.com'
tools/configure -save -set {SMTP}{MAILHOST}='smtpserver.email.com'
tools/configure -save -set {SMTP}{Username}='userid'
Expand Down

0 comments on commit 005ecdd

Please sign in to comment.