InstallationGuidePart1 < System

You are here: BACCHUS Wiki>System Web>ReferenceManual>AdminDocumentationCategory>InstallationGuidePart1 (revision 1) (raw view)
---++ Installation Guide Part 1
*This guide describes the steps for manually installing Foswiki, with specific steps for installations on Linux with the Apache web server.* If you are using a different web server or operating system, in addition to reviewing this document, check any additional information specific to your platform at Foswiki:Support.SupplementalDocuments. Foswiki:Support.SupplementalDocuments also has information for other scenarios, such as shared web hosting environments.

These installation instructions are also available online at Foswiki:System.InstallationGuide, and are available within your Foswiki installation at =%SYSTEMWEB%.InstallationGuide= (the <nop>InstallationGuide topic in the %SYSTEMWEB% web).

*For information on upgrades*, please also refer to Foswiki:System.UpgradeGuide. A static HTML version of this document, =UpgradeGuide.html=, is included in the root of your Foswiki distribution.

%TOC%
%STARTINCLUDE%
---++ Initial Installation
---+++ System Requirements

Please see the section "[[#SystemRequirements][Foswiki system requirements]]" for the server and client requirements to run Foswiki, including the Perl modules required on the server. If you need to install any Perl libraries from CPAN for use by Foswiki, see Foswiki:Support.HowToInstallCpanModules for more information.

---+++ Preparing to install

Before attempting to install Foswiki, you are encouraged to review the Foswiki:System.AdminSkillsAssumptions. This guide assumes the person installing Foswiki has a basic knowledge of server administration on the system on which Foswiki is to be installed. While it is possible to install Foswiki with FTP access alone (for example, on a hosted site), it is tricky and may require additional support from your hosting service (for example, in setting file ownership and installing missing perl CPAN libraries).

*If you are upgrading from a previous Foswiki version or from a TWiki installation*, please refer to Foswiki:System.UpgradeGuide. A static HTML version of this document, =UpgradeGuide.html=, is included in the root of your Foswiki distribution.

<!-- to be included once the supplemental document is available
*If you are upgrading from an old TWiki version such as Cairo (TWiki 3)*, refer to Foswiki:Support.UpgradingFromOlderTWikiReleases to ensure a safe upgrade without accidentally overwriting your site customizations and data.
-->

Verify that your server meets the [[#SystemRequirements][Foswiki system requirements]], including having the minimum required Perl version and all required Perl modules installed. If you need to install any Perl libraries from CPAN for use by Foswiki, see Foswiki:Support.HowToInstallCpanModules for more information.

<div class="foswikiHelp">You should also take this opportunity to consider the automated installers, virtual machine images and (currently) Debian and !CentOS packages at Foswiki:Download.OtherFoswikiInstallers.  These automate much of the install process and may help some users get started more easily.

Note that the installers are optimized for the target system, and typically do not follow the normal Foswiki directory structure documented below.  Files are installed into system locations that are appropriate to the target OS.  Review the steps below, but recognize that file locations may be different, and some installation steps such as customization of the Web Server and Foswiki,setting file ownership and permissions will have been done automatically during the package installation.</div>

If you need help, feel free to ask a question in the Foswiki:Support web or on Foswiki:Community.InternetRelayChat (irc.freenode.net, channel #foswiki).

#StandardInstallation
---+++ Basic installation: getting Foswiki up and running

To install Foswiki, complete the following steps:

   1 *Download* and *unpack* the Foswiki distribution.
   1 *Set the file and directory permissions* for the installation.
   1 *Configure* the *locations of the Perl executable* and the *Foswiki modules*.
   1 *Configure the web server*.
   1 *Configure Foswiki*.
   1 *Enable authentication of users* (if desired).
   1 *Define the administrator users*.

---++++ Download and unpack the Foswiki distribution

*Download* the Foswiki distribution from http://foswiki.org/Download

*Unpack the distribution file:* Change to the directory where you want to place the Foswiki directory. Unzip or untar and gunzip the distribution; 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).

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]]".

---++++ (Not applicable on Windows) Set the file and directory permissions for the installation

*Set up access file and directory rights*, as well as file ownership, as required by your web server configuration so that the web server user (the user used by the web server to run CGI programs) can read and write within the =foswiki= directory tree.

Note: for more information on the appropriate permissions to ensure security for your Foswiki data, see Foswiki:Support.SecuringYourSite.

The default file and directory access permissions as set by the distribution define a reasonable security level that will work for many types of installations, including shared hosting. Nonetheless, you should verify that the web server user has read access to all files and directories beneath the =foswiki= directory, and execute access for all directories. Also verify that the =data= and =pub= directories and all the subdirectories and files beneath them allow write access for the web server user.
   * *Warning:* Do not just run a =chmod -R 770 foswiki=. Providing execute access to all files is potentially dangerous. This is a common mistake made by Foswiki installers. See Foswiki:Support.SettingFileAccessRightsLinuxUnix for a sample set of Unix commands to set the file and directory permissions.

It is possible to define tighter access permissions than the default ones; how tight they should be depends on your web server environment and local needs. Typically you should limit all access from others if the web server machine has login access for users other than root and the web server administrator. For a dedicated web server that just runs Foswiki and has limited login access, the default access permissions have a good safety level.

_If you have root user permissions_, then for additional security, you can change the ownership of the =foswiki= directory tree to the web server user, using the command =chown -R user:group /path/to/foswiki=. The web server username varies in different installations; here are some sample commands for various Linux distributions:
   * !RedHat, Fedora, !CentOS, Gentoo, Mandriva : =chown -R apache:apache /path/to/foswiki=
   * debian/Ubuntu/Kubuntu : =chown -R www-data:www-data /path/to/foswiki=
   * Suse : =chown -R wwwrun:www /path/to/foswiki=

If Foswiki stops working after you applied a change in access permissions and you wish to restore the original permissions, run the Unix commands located at Foswiki:Support.SettingFileAccessRightsLinuxUnix.

---++++ (optional - *required on Windows* ) Configure the locations of the Perl executable and the Foswiki modules

If you are running on a Linux system with Perl found in =/usr/bin/perl= then this step is not required.  This step is *required* on Windows installations.

The easiest way to fix up the bin scripts is to run the =tools/rewriteshebang.pl= script.  If the Perl interpreter is in the default execution path, follow these steps:

<verbatim class="bash">
cd /path/to/foswiki/tools
perl -I ../lib rewriteshebang.pl
</verbatim>

or for Windows users:

<verbatim class="bash">
cd C:\path\to\foswiki\tools
perl -I ..\lib  rewriteshebang.pl
</verbatim>

The script will determine the location of the Perl interpreter and will prompt to update both the bin and tools scripts in a single step.   The changed files will be reported, and it is safe to rerun the script.

If the =perl= command does not work from the command line,  then you need to find the location of your system's Perl interpreter.   Insert the path to Perl in the first line of the =rewriteshebang= script. For example:

<verbatim class="bash">
cd C:\path\to\foswiki\tools
C:\path\to\perl -I ..\lib  rewriteshebang.pl
</verbatim>


---++++ (optional) Configuration of a script suffix for the perl scripts

Some web servers require a special extension on perl script files (e.g. =.cgi= or =.pl=). This is not normally required with the Apache web server, though some hosted web servers are configured to require it. If the documentation for your web server indicates that a special extension is necessary, rename all the executable scripts in =bin=; that is, rename =bin/view= to =bin/view.pl=, and so on. When configuring Foswiki (see the section "[[#ConfigureFoswiki][Configure Foswiki]]"), set the =ScriptSuffix= option to the special extension.

---++++ (optional) Configuration for non-standard library locations

A standard Foswiki install has the directories =bin/= and =lib/= located under the  Foswiki installation directory.  If you have moved these directories, or if your system requires changes to the default Perl libraries, then this step is required.

*Create the file Local<nop>Lib.cfg* located at =bin/LocalLib.cfg=
   * In the =bin= directory, copy the template file =LocalLib.cfg.txt= to =LocalLib.cfg=. Make sure the ownership and access rights of the copy are the same as <nop>Local<nop>Lib.cfg.txt.
   * Edit =bin/LocalLib.cfg= so that =$foswikiLibPath= is set to the absolute file path of your =lib= directory. For example: =/path/to/foswiki/lib=.
   * If you need to install additional [[http://cpan.perl.org/][CPAN]] modules, but can't update the main Perl installation files on the server, you can set =$CPANBASE= to point to your personal [[http://cpan.perl.org/][CPAN]] install. Don't forget that the web server user has to be able to read those files as well.

---++++ Configure the web server

First choose the best configuration method for your web server. With Apache, there are two ways to configure it: a config file included from httpd.conf or .htaccess files.
   * *Apache config file:* The recommended method is using a config file. With a config file you can put the entire Foswiki configuration in ONE file (typically named =foswiki.conf=). Performance is much better with a config file, and one file gives the best overview and ensures that you get a safe installation . However to use a config file you need root or sudo access to stop and start Apache. The Foswiki apache config file can be included from the main Apache config file. (Typically =httpd.conf= or =apache.conf= depending on your distribution). However most distributions have a directory from which any file that ends with =.conf= gets included when you restart Apache (Example !RedHat/Fedora/Centos: =/etc/httpd/conf.d=, Gentoo: =/etc/apache2/vhost.d= ). If you use a virtual host setup in Apache you should include the =foswiki.conf= file from inside the desired virtual host config in your Apache configuration.
   * *.htaccess files:* This method should only be used when you cannot use a config file. Performance is slower as Apache must search through _all_ applicable directories for any =.htaccess= files on each page access. Normally this is the only way to control Apache in a shared host environment where you have no root or sudo privileges.

*If you are using a config file*:
   * The easiest and best way is to use the Foswiki:Support.ApacheConfigGenerator tool to generate a safe, working config file for your Foswiki installation, based on the options you choose in the tool.
   * If you can't use the online configuration generator, a sample config file called =foswiki_httpd_conf.txt= can be found in the root of the foswiki installation.
   * Ensure that web access is denied to all Foswiki subdirectories other than =bin= and =pub=.
      * The Foswiki:Support.ApacheConfigGenerator tool will generate the appropriate settings;
      * the =foswiki_httpd_conf.txt= file also has examples of configuring Apache appropriately.
   * Ensure there is either a =<noautolink>ScriptAlias<noautolink>= directive for the =bin= subdirectory, or an =Alias= directive with =SetHandler cgi-script= and =Options Exec<nop>CGI= directives for the =bin= subdirectory, so that the =bin= scripts will be executed by Apache.
   * *Note:* you must restart Apache after making changes to your config files for the changes to take effect.

*If you are using a .htaccess file:*
   * In the root of the foswiki installation, there are sample =.htaccess= files for various subdirectories in your installation. Each file has help text explaining how to modify it for your configuration. For more information, see Foswiki:Support.SupplementalDocuments.<sticky>
   | *location and name of sample .htaccess file* | *copy sample file to the following location* |
   | =foswiki/root-htaccess.txt= | =foswiki/.htaccess= |
   | =foswiki/bin-htaccess.txt= | =foswiki/bin/.htaccess= |
   | =foswiki/pub-htaccess.txt= | =foswiki/pub/.htaccess= |
   | =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. |</sticky>
   * Ensure that web access is denied to all Foswiki subdirectories other than =bin= and =pub=. The sample =.htaccess= files show how to configure Apache appropriately.  It is important to verify that none of these directories can be directly accessed.
   * Ensure that the =foswiki/bin/.htaccess= files contains the line =SetHandler cgi-script= so that all scripts in the =bin= directory will be executed by Apache.
   * *Note:* On Linux systems, files named with the leading "." like =.htaccess= are hidden files and will not be listed unless using the -a option, ex. =ls -la=

*Turn off any kind of PHP, Perl, Python, Server Side Includes, or other software execution mechanisms supported by your web server in the =pub= directory.* For example, most Linux distributions have a default Apache installation with PHP and server side include (SSI) enabled. This would allow PHP scripts uploaded as attachments to be executed, which is a security risk, so it should be disabled in the Apache configuration with =php_admin_flag engine off=.

Different script execution mechanisms are disabled in different ways; see your web server configuration and documentation for more details.

#ProtectConfigure
---+++++ Protect the configure script!
*You should never leave the =configure= script open to the public.* Limit access to the =bin/configure= script to either localhost, an IP address or a specific user using basic Apache authentication. The Foswiki:Support.ApacheConfigGenerator lets you setup who has access to the =configure= script. Also see the =foswiki-httpd-conf.txt= or =bin/.htaccess.txt= file for an example of the setting required to protect the =configure= script.

To limit access to a particular user, set up a =.htpasswd= file that contains the user name and password that Apache will use to authenticate the user:
   * *Caution! Do not follow these steps on an existing Foswiki =.htpasswd= file.*  It will destroy the email addresses stored in that file!  If the file already exists, you can choose an existing user for access to configure.
   * Change to the =foswiki/data= directory.
   * Issue the command =htpasswd -c .htpasswd &lt;username&gt;=, where &lt;username&gt; is the name of the user you will use to access the =configure= script. _Choose the username with care:_ the username cannot be an existing login name for your Foswiki installation, nor can it be used later on to register in Foswiki. Enter a password when prompted.

All of the above methods - Sample configuration files, Foswiki:Support.ApacheConfigGenerator and sample =.htaccess= files, all include example settings to protect the configure script with a password.  The critical section looks something like:
<verbatim>
<FilesMatch "configure.*">
    SetHandler cgi-script
    Order Deny,Allow
    Deny from all
    # List of IP addresses allowed to access configure
    Allow from 127.0.0.1 192.168.1.10
    # specify username used on the "htpasswd" command above
    Require user someuserid
    # Set to "Any" to allow IP -or- userid,  set to "All" to require both match
    Satisfy Any
    ErrorDocument 401 default
</FilesMatch>
</verbatim>

*Note:* In addition to any web server security protection that you have set up, when saving any configuration settings for the first time on the =configure= web page, you will be prompted to set a configuration password. This password must be entered on all subsequent configuration changes, and is also used to log in via the internal admin link (see the section "[[#DefineAdminUser][Define the administrator user(s)]]"). Even after a =configure= password has been set, access to the =configure= page should still be restricted by the web server, in order to avoid revealing internal information to potential attackers.


<blockquote>
<b>Tip:</b> You do not have to use the same password file for both Configure and for Foswiki user registration.  If you use a separate file, you can create it using the =htpasswd= commmand and complete segregate configure access from Foswiki access.  This is probably safer, but does not allow users to change their configure password using Foswiki services.  The password file has to be manually maintained..
   1 Generate an alternate password file to protect configure. =htpasswd -c -s /path/to/data/.htpasswd-admin configuserid=
   1 Add / modify and delete this alternate file using the =htpasswd= command.  __Don't mix them up and use =htpasswd= on the Foswiki .htpasswd file!__
   1 Edit the foswiki apache configuration and modify the block (shown above) that protects the configuration command. *Add* or modify the following statements in the block. _Don't remove the other statements!_
<verbatim>
<FilesMatch "configure.*">
        AuthType Basic
        AuthName "admins only"
        AuthUserFile /path/to/data/.htpasswd-admin
        # Changing the Require user to Require valid-user allows any ID in the
        # file access to configure!
        Require valid-user
</FilesMatch>
</verbatim>
</blockquote>
For more information, refer to Foswiki:Support.ProtectingYourConfiguration.

#ConfigureFoswiki
---++++ Configure Foswiki

*Run the [[%SCRIPTURLPATH{"configure"}%][configure]] script* from your browser: enter =http://yourdomain/url/to/foswiki/bin/configure= into your browser address bar.
   * When you access the =configure= web page for the first time, you can only edit the section =General Path Settings=. Make any required changes, and save the settings, whether or not you needed to make any changes. You will be prompted to set a password for the =configure= page: this password must be entered for all subsequent configuration changes, and is also used to log in via the internal admin link (see the section "[[#DefineAdminUser][Define the administrator user(s)]]").
   <blockquote class="foswikiHelp"> %I% *Note:* The =configure= password is remembered by =configure=, separate to web server access controls mentioned in "[[#ProtectConfigure][Protect the configure script]]".</blockquote>
   * After saving the =General Path Settings=, continue configuring Foswiki. Configuration items which may require further attention will be highlighted.
   * If the Foswiki installation can be accessed by more than one !protocol://domain, ensure the additional alternative URLs are set in ={PermittedRedirectHostUrls}=.
   <blockquote class="foswikiHelp"> %T% *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></blockquote>
   * Setup the =Mail and Proxies= section.  Email must be available so Foswiki can send registration emails.
      * Under the "Email General" tab, If you do not want to enable sending registration emails or want to enable it later you can uncheck ={EnableEmail}=. Otherwise the ={WebMasterEmail}= parameter must be configured.
      * Under the "Email Server" tab, you can choose 3 methods of sending email.  This is explained in detail under the help text for this tab.
         * =MailProgram= is typically suitable on most Linux systems, and no further configuration is required.
         * If you chose either of the =Net::SMPT= methods, you must also configure ={SMTP}{MAILHOST}=. Many ISPs have introduced authentication when sending emails to fight spam so you may also have to set ={SMTP}{Username}= and ={SMTP}{Password}=.
         * =Net::SMTP::SSL= will encrypt the connection to the e-mail server and is required for some email services like Google's GMail.
      * Under the "Proxy" tab, if your server is behind a firewall with a proxy, and you wish to install extensions via =configure=, you may have to set ={PROXY}{HOST}= and ={PROXY}{PORT}=.
     <blockquote class="foswikiHelp">%X% %INCLUDE{"UserAuthentication" section="SMTPNOTE"}%</blockquote>
     <blockquote class="foswikiHelp"}%X% SMTP authentication requires additional perl modules including =Authen::SASL= and =MIME::Base64=, </blockquote>

If there is a problem with your setup that prevents you from accessing the =configure= page, you can [[#ConfiguringFoswikiManually][configure Foswiki manually]].

#AuthenticationOfUsers
---++++ Authentication

Authentication of users means their activity can be tracked, and access to your site can be controlled. *This is particularly important for sites that are publicly accessible on the web.*  You are strongly encouraged to read [[%SYSTEMWEB%.UserAuthentication]] and Foswiki:Support.UserAuthenticationSupplement for further information about managing users and access controls for your Foswiki site.

The most common authentication methods used for public Foswiki installations are Template Login and Apache Login. They have the following relative advantages:
   * Template Login can be set up without any web server configuration, and users can log off without restarting the browser. As the login page is just a Wiki page, you can customize it to suit your needs.
   * Apache Login allows you to use any Apache-module based authentication scheme, such as =mod_auth_ldap= or =mod_auth_mysql=. However, as your browser is caching your login, you must restart the browser to log out.

Note that the password databases for both of these authentication mechanisms are compatible, so you can switch between them at a later date.

To make it easier to follow the instructions in this section, you can view this installation guide using your Foswiki site by entering =%SYSTEMWEB%.InstallationGuide= into the "Jump" text box. By doing this instead of using the =INSTALL.html= file from the distribution, you will be able to use the embedded hyperlinks to jump directly to the referenced pages.

---+++++ Template Login authentication
%INCLUDE{"UserAuthentication" section="TemplateLogin" INSTALLGUIDE="1"}%

---+++++ Apache Login authentication
%INCLUDE{"UserAuthentication" section="ApacheLogin" INSTALLGUIDE="1"}%

#SearchAlgorithm
---++++ Choose an appropriate search algorithm for your Operating System

On the =Store= pane in =configure= you will find the setting ={RCS}{SearchAlgorithm}=.

By default it is set to =Foswiki::Store::SearchAlgorithms::Forking= which is what you should keep if you install Foswiki in Linux or any other Unix type operating system.

If you install Foswiki on a Windows server, using an external grep program can create problems because of limitations in the length of command lines. You may be able to run with Forking in Windows if your directory path to Foswiki is kept short (short directory names and few levels), however the recommended (safe) setting for Windows is =Foswiki::Store::SearchAlgorithms::PurePerl=. 

#DefineAdminUser
---++++ Define the administrator user(s)

---+++++ About Administrators

Administrators have read and write access to any topic, regardless of any access controls that have been applied to the topic or its web. The _special user_ [[%USERSWEB%.AdminUser]] ships with Foswiki and is accessed using by logging in with user =admin= and the password established when initially saving the configuration. *Don't log in with the wikiname* ==AdminUser==.

After installing Foswiki, you can also register other users that you will use to administer Foswiki. To make a user an administrator, add the WikiName for the user to the =AdminGroup=, defined in the =[[%USERSWEB%.AdminGroup]]= topic in your Foswiki installation.

Note that with the _sudo_ or internal admin login, it is not necessary to add other users to the AdminGroup.  However if you have more than one administrator, you may still want to do this to ensure that topic changes are attributed to a specific user instead of the default %USERSWEB%.AdminUser.

By adding users to %USERSWEB%.AdminGroup:
   * Users with Admin rights will have routine access to topics that might normally be denied.
   * These users will be unable to test or demonstrate access controls.
   * Changes made are always attributed to a unique logged in user.
   * Password sharing of the =bin/configure= password is not required

By using the _internal admin login_:
   * You don't need to grant admin rights to individual users
   * All users will be subject to access controls.
   * Changes made while using the _internal admin login_ are attributed to %USERSWEB%.AdminUser
   * The "save" password for =bin/configure= will need to be shared among administrators

---+++++ Adding users to the %USERSWEB%.AdminGroup
To make it easier to follow the instructions in this section, you can view this installation guide using your Foswiki site by entering =%SYSTEMWEB%.InstallationGuide= into the "Jump" text box. By doing this instead of using the =INSTALL.html= file from the distribution, you will be able to use the embedded hyperlinks to jump directly to the referenced pages.

To add an initial administrator to the =AdminGroup=, perform the following steps:

   * If you are not already logged in with your WikiName, then login.
   * Go to the =[[%USERSWEB%.AdminGroup]]= topic and select the "internal admin login" link. Login using the password you set on the =configure= page.
   * After logging as the internal admin, view the =%USERSWEB%.AdminGroup= topic. Follow the instructions on the page to add users to the AdminGroup. You do _not_ need to edit the topic.

Any member of the %USERSWEB%.AdminGroup can add subsequent members &mdash; you do not have to use the internal admin login.

To more easily debug access control issues, you may want to have a regular Foswiki user account for daily use, and a special one that belongs to the =AdminGroup= that you use only for administering your Foswiki site. See [[%SYSTEMWEB%.AccessControls]] for more information on access controls and user groups.

---++++ Congratulations!

You now have a basic installation running. At this point you can just point your Web browser at =http://yourdomain.com/url/to/foswiki/bin/view/System/InstallationGuidePart2= to proceed with further tailoring your site..

In order to keep your user, group, and site configuration information separate from the actual content of your site, it is recommended that you create a new web in which your site's pages will reside. See [[%SYSTEMWEB%.ManagingWebs]] for more information on Wiki webs and how to create one.

---+++ Troubleshooting

   * Re-run the =configure= script and make sure you have resolved all errors and are satisfied that you understand any warnings.
   * Follow the steps detailed in [[FAQTroubleshootingExtensions]]
   * Failing that, consult the topics at Foswiki:Support.SupplementalDocuments and Foswiki:Support.AskedQuestions.
   * If you need help, ask a question in the Foswiki:Support web or on Foswiki:Community.InternetRelayChat (irc.freenode.net, channel #foswiki).

#SystemRequirements
---++ Foswiki system requirements
%INCLUDE{"SystemRequirements"}%

#UploadingFoswikiDistribution
---+++ Uploading the Foswiki distribution to your web server host

If you cannot unpack the Foswiki distribution directly in your installation directory, you can unpack the distribution on your local computer, manually create the directory structure on your host server and upload the files as follows: 
   * Using the table below, create a directory structure on your host server
   * Upload the Foswiki files by FTP (transfer as text except for the image files in =pub= directory.)
   * *Note:* Don't worry if you are not able to put the =lib= directory at the same level as the =bin= directory. You can create this directory elsewhere and configure the =bin/setlib.cfg= file.<sticky>
   | *Foswiki dir:* | *What it is:* | *Where to copy:* | *Example:* |
   | =foswiki= | start-up pages | root Foswiki dir | =/home/smith/public_html/foswiki/= |
   | =foswiki/bin= | CGI bin | CGI-enabled dir | =/home/smith/public_html/foswiki/bin= |
   | =foswiki/lib= | library files | same level as =bin= | =/home/smith/public_html/foswiki/lib= |
   | =foswiki/locale= | language files | dir secure from public access | =/home/smith/public_html/foswiki/locale= |
   | =foswiki/pub= | public files | htdoc enabled dir | =/home/smith/public_html/foswiki/pub= |
   | =foswiki/data= | topic data | dir secure from public access | =/home/smith/public_html/foswiki/data= |
   | =foswiki/templates= | web templates | dir secure from public access | =/home/smith/public_html/foswiki/templates= |
   | =foswiki/tools= | Foswiki utlilities | dir secure from public access | =/home/smith/public_html/foswiki/tools= |
   | =foswiki/working= | Temporary and internal files | dir secure from public access | =/home/smith/public_html/foswiki/working= |</sticky>

#ConfiguringFoswikiManually
---+++ Configuring Foswiki manually (without using the =configure= page)

It is highly recommended that you configure Foswiki by using your browser to access the =configure= page. However, if you are unable to get the =configure= page to display (for example, if a dependency is missing), or for some reason you do not wish to use the =configure= page, then you can configure Foswiki manually

Perform the following steps to manually configure Foswiki:
   * Copy the file =lib/Foswiki.spec= to =lib/LocalSite.cfg=
   * Remove the # in front of the following settings, and ensure that they are set to the correct values: Note: The settings must not reference other $Foswiki::cfg variables.<sticky><verbatim class="perl">
   $Foswiki::cfg{DefaultUrlHost}
   $Foswiki::cfg{ScriptUrlPath}
   $Foswiki::cfg{ScriptDir}
   $Foswiki::cfg{PubUrlPath}
   $Foswiki::cfg{PubDir}
   $Foswiki::cfg{DataDir}
   $Foswiki::cfg{ToolsDir}
   $Foswiki::cfg{TemplateDir}
   $Foswiki::cfg{LocalesDir}
   $Foswiki::cfg{WorkingDir}
   $Foswiki::cfg{OS}</verbatim></sticky>

   * Make sure the following settings are defined:<sticky><verbatim class="perl">
   $Foswiki::cfg{LoginManager}
   $Foswiki::cfg{WebMasterEmail}
   $Foswiki::cfg{SMTP}{MAILHOST}
   $Foswiki::cfg{SMTP}{SENDERHOST}</verbatim></sticky>

   * Remove the line containing ==__END__== and everything following it.
%STOPINCLUDE%

---
 *Related Topics:* [[InstallationGuidePart2]], [[AdminDocumentationCategory]], Foswiki:Support.SupplementalDocuments

TWiki is a registered trademark of Peter Thoeny.
<!-- %JQREQUIRE{"chili"}% -->
Topic revision: r1 - 01 Oct 2011, ProjectContributor
System
Copyright &© by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding BACCHUS Wiki? Send feedback