<chapter id="installation.main">
  <title>Installation instructions</title>

  <section>
    <title>Requirements</title>
    <para>
      Requirement for running Phorum are:
      <itemizedlist>
        <listitem>A webserver (like Apache or Microsoft IIS);</listitem>
        <listitem>PHP, version 5.2 or above;</listitem>
        <listitem>A MySQL server, version 5.0 or above.</listitem>
      </itemizedlist>
      If you do not run your own website, but have hosted your website
      with a hosting provider, then please ask your hosting provider if
      your account meets these requirements.
    </para>
  </section>

  <section>
    <title>Quickstart guide</title>
    <para>
      This is the quickstart guide for installing Phorum, aimed at people
      that are used to working with websites, PHP and databases. If you
      are having problems following this guide, then please read
      <xref linkend="installation.detailed"/> instead.
      <itemizedlist>
        <listitem>Unpack Phorum into a directory below your website's document root;</listitem>
        <listitem>Create a database and a full access database user for that database;</listitem>
        <listitem>Edit <filename>include/db/config.php.sample</filename>, save it as <filename>include/db/config.php</filename>;</listitem>
        <listitem>Open <filename>{phorum url}/admin.php</filename> in your web browser and finish the install.</listitem>
      </itemizedlist>
    </para>
  </section>

  <section id="installation.detailed">
    <title>Detailed installation instructions</title>

    <section>
      <title>Download Phorum</title>
      <para>
        If you haven't already done so, download the latest stable
        Phorum distribution from &www.phorum.org;.
      </para>
    </section>

    <section>
      <title>Unpack the downloaded archive</title>
      <para>
        <emphasis role="bold">From Windows:</emphasis>
      </para>
      <para>
        If you have downloaded the .zip file, you can extract the
        files from that archive directly using Windows XP's zipfile support.
        If you downloaded the .tar.gz file or if you are using a Windows
        version that does not have built-in zipfile support, then you will
        have to download an appropriate tool for unpacking, e.g. WinZip
        (<ulink url="http://www.winzip.com/">http://www.winzip.com/</ulink>).
      </para>
      <para>
        <emphasis role="bold">From UNIX:</emphasis>
      </para>
      <para>
        If you have access to a UNIX shell, you can unpack the .tar.gz
        archive using the following command:
        <screen>
shell&gt; <literal>tar xvzf phorum-x.y.z.tar.gz</literal></screen>
        Or if the tar program on your system does not supprt the "z" flag:
        <screen>
shell&gt; <literal>gunzip phorum-x-y-z.tar.gz</literal>
shell&gt; <literal>tar xvf phorum-x.y.z.tar</literal></screen>
      </para>
    </section>

    <section>
      <title>Place the Phorum files in your website's document root</title>
      <para>
        <remark>TODO: this section should be in a document conventions
        section</remark>
        The document root for a website is the directory in which your
        site's web pages are stored. If your website's URL is
        <filename>http://www.example.com</filename> and you place the Phorum
        files in a directory called <filename>forum</filename> inside
        your document root, your Phorum installation will be available
        at the URL <filename>http://www.example.com/forum</filename>.
        From now on, we will name this URL simply
        <filename>{phorum url}</filename>. So if you
        see <filename>{phorum url}/admin.php</filename>, using the example
        we actually mean
        <filename>http://www.example.com/forum/admin.php</filename>.
      </para>
      <para>
        If the webserver is running on the same system as where you have
        unpacked the downloaded archive, you can move the unpacked files
        to your website's document root.
      </para>
      <para>
        If the webserver is running on another system, you will have
        to upload the files to your website's document root. In most
        cases, you will use FTP for this. You will need an FTP client
        (a good free one is FileZilla). Connect to ftp.yourdomain.com
        (or the FTP server that was assigned to you by your provider)
        and proceed to upload the files to the document root. The
        procedure for doing this differs depending on the client; if
        in doubt, refer to the client's documentation. However, some
        hosting providers require SCP (secure copy, which is more
        secure than FTP). If you do not know how or where to upload
        the Phorum files, please contact your hosting provider.
      </para>
      <para>
        <note>
          <emphasis>
            (simply ignore this if it does not make sense to you)
          </emphasis><sbr/>
          There are software packages that require you to make files
          writable for the webserver (using the infamous "chmod 777").
          <emphasis>
            DO NOT DO THIS FOR ANY OF THE PHORUM FILES.
          </emphasis>
          The webserver only needs read access on the distribution files,
          because all dynamic data is stored in the database. If you run
          into problems running Phorum, it will never be because you
          "forgot to do chmod 777" on any of the Phorum files.<sbr/>
          <sbr/>
          The only directory that might have to be made writable for the
          webserver is <filename>./cache</filename>
          (see <xref linkend="install.additionalissues"/>).
          But this directory is not used in a default installation.
        </note>
      </para>
    </section>

    <section id="installation.createdb">
      <title>Create a database and a database user</title>
      <para>
        Phorum stores all its data in a database. So if you do not already
        have a database which you will be using for Phorum, you now need to
        create one. Officially, only the
        <ulink url="http://www.mysql.com/">MySQL</ulink>
        database server is supported
        by Phorum, so we recommend to use MySQL whenever possible.
      </para>
      <para>
        If you have hosted your site with a hosting provider,
        you should have access to a control panel (usually cPanel or similar).
        There should be a MySQL database link on the main page of the control
        panel, and from there you can create a database. Alternatively, you
        could have access to phpMyAdmin. Log into phpMyAdmin using the
        username and password that your host has provided, and use the
        "create new database" function on the main page. If none of these
        options are available to you, contact your host and they will be
        able to do it for you.
      </para>
      <para>
        If you run your own database server, then you will have to
        create the database and the user yourself. If you are using
        a control panel, like phpmyadmin, then use that control panel
        to create them. You can use the mysql SQL prompt to create
        the database by issuing the appropriate commands. For example:
        <screen>
mysql&gt; <literal>CREATE DATABASE phorum;</literal>
mysql&gt; <literal>GRANT ALL ON phorum.* TO 'myuser'@'localhost' IDENTIFIED BY 'mypassword';</literal></screen>
        Of course, for security reasons you would not use "myuser" and
        "mypassword" but a username and password that you made up
        yourself. Also "localhost" should match the hostname of the MySQL
        server to which Phorum will connect.
      </para>
      <para>
        If you are unsure on how to create a database and a database user,
        then please refer to your system's documentation.
      </para>
    </section>

    <section>
      <title>Configure the database access for Phorum</title>
      <para>
        After setting up the database, you will have to tell Phorum how
        to access that database. The configuration for this is put in
        the file <filename>include/db/config.php</filename> inside your
        Phorum directory. This file is not included in the distribution.
        Only a differently named sample file is included (this is to
        prevent overwriting your configuration when upgrading Phorum).
        Copy or rename the sample configuration file
        <filename>include/db/config.php.sample</filename> to
        <filename>include/db/config.php</filename>. Then edit the
        <filename>config.php</filename> file to match the access
        settings for the database that was created in
        <xref linkend="installation.createdb"/>.
      </para>
      <para>
        If you run your website on a remote server, then either edit
        the configuration file directly on that server (e.g. through a
        UNIX prompt or an FTP client that supports this) or upload the
        file to the correct location after editing it locally.
      </para>
      <para>
        In the configuration file, you will find the following settings:
        <variablelist>
          <varlistentry>
            <term>type</term>
            <listitem>
              <para>
                This setting determines what database backend is used
                by Phorum. Phorum is distributed with the a MySQL backend.
                If you are using MySQL for the database server, then you
                can keep the default value <literal>mysql</literal> here.
              </para>
              <para>
                If you use a third party database backend (e.g. PostgreSQL),
                then you can configure it here. The backend PHP script must
                be installed at the location
                <filename>{phorum dir}/include/db/mybackend.php</filename>.
                With this example, the setting of the type has to be
                <literal>mybackend</literal>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>server</term>
            <listitem>
              <para>
                This is the hostname or IP-address of your database server.
                On a lot of systems, the database server will run on the
                same system as the web server. In those cases, the default
                value <literal>localhost</literal> will often be correct.
                Change this value if the database server is running on
                a different system than the web server.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>name</term>
            <listitem>
              <para>
                MySQL (and a lot of other database servers) can handle
                multiple databases in one database server. Each database
                is referenced by its own unique name. This setting is
                used for configuring the name of the database that Phorum
                has to use.
              </para>
              <para>
                If you have created the database using the example command
                from above (<literal>CREATE DATABASE phorum</literal>),
                then you can use the default value <literal>phorum</literal>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>user</term>
            <listitem>
              <para>
                The username of the user which is used for accessing the
                database server. The user must have full access rights to
                the database, for creating and maintaining the needed
                tables.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>password</term>
            <listitem>
              <para>
                The password for the database user.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>table_prefix</term>
            <listitem>
              <para>
                This table prefix will be prepended to all table names
                that Phorum uses. If other applications are using the
                same database or if you have multiple Phorum installations
                that use the same database name, this prefix can be used to
                prevent table name collisions. E.g. if you set the
                prefix to <literal>myprefix</literal>, then the full name
                of the users table will be <literal>myprefix_users</literal>.
                For most installations, you can keep the default value
                <literal>phorum</literal>.
              </para>
              <para>
                <important>
                  Never change the table prefix on a running system!
                </important>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>port</term>
            <listitem>
              <para>
                This port is used to connect to the database server.
                For most installations, you can keep the default value
                <literal>3306</literal> which is the regular port for mysql.
              </para>
            </listitem>
          </varlistentry>  
          <varlistentry>
            <term>socket</term>
            <listitem>
              <para>
                The socket which is used by the database server to connect to.
                Overrides the port if the hostname is localhost for mysql.
              </para>
            </listitem>
          </varlistentry> 
          <varlistentry>
            <term>down_page</term>
            <listitem>
              <para>
                Phorum uses a built-in error message to inform visitors
                when no database connection can be made. If you want to
                provide a custom error message page for this, you can
                set this setting to the URL of the page that you want
                to display.
              </para>
            </listitem>
            <term>upgrade_page</term>
            <listitem>
              <para>
                Phorum uses a simple built-in page to inform visitors and
                the site admin that the database has to be upgraded.
                If you want to provide a custom upgrade message page for
                this, you can set this setting to the URL of the page that
                you want to display.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>upgrade_page</term>
            <listitem>
              <para>
                An optional URL for redirecting the user when the database
                has to be upgraded. If you want to use this field, remove
                the "//" in front of it.
              </para>
            </listitem>
          </varlistentry>
          </variablelist>
          <emphasis>
            The following options apply only to the mysql-layer:
          </emphasis>
          <variablelist>
          <varlistentry>
            <term>mysql_use_ft</term>
            <listitem>
              <para>
                This setting determines whether Phorum will use MySQL's
                full text algorithm for searching through postings.
                If enabled, searching will be much faster.
              </para>
              <para>
                To be able to use this feature, the MySQL server that
                you are using must be version 4.0.18 or higher (should always
                be the case as MySQL 5 is a requirement) and the
                database user must be allowed to create temporary tables.
                If these requirements are not met, then you will have to
                disable this setting by assigning the value
                <literal>0</literal>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>mysql_php_extension</term>
            <listitem>
              <para>
                This option defines which MySQL PHP extension should be used.
                Either NULL, "mysql", "mysqli" or "mysqli_replication" for
                master/slave setups. If NULL, Phorum will autodetect the
                extension to use.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>empty_search_table</term>
            <listitem>
              <para>
                This option defines if Phorum should populate the search
                table with data for mysql fulltext search (useful if you
                use a alternate search backend which doesn't use the
                search table): 0 will put the messages into the search table,
                1 will keep it empty.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>charset</term>
            <listitem>
              <para>
              This option specifies the charset used for the create table
              statements and the connection(s) later on.
              <important>
                  Never change the charset on a running system!
              </important>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>slaves</term>
            <listitem>
              <para>
                This array can hold a number of slave servers to use in
                master/slave mode. All write queries will go to the default
                server above, which is the master server in this setup and
                read load will be split randomly over the slave servers
                specified in this array. If you want your master server to
                get read load as well you need to specify it here too.
                Some read queries will go to the master server anyway in
                case they are vulnerable to replication lag.
                <example>
                  <title>Configuring slaves with the MySQL layer</title>
                  <programlisting><![CDATA[
<?php
    'slaves'=>array(
        array(    // Database connection 1.
        'name'          =>  'phorum5',
        'server'        =>  '192.168.1.5',
        'user'          =>  'phorum5',
        'password'      =>  'phorum5',
        'port'          =>  '3306',
        'socket'        =>  NULL),
        array(    // Database connection 2.
        'name'          =>  'phorum5',
        'server'        =>  '192.168.1.6',
        'user'          =>  'phorum5',
        'password'      =>  'phorum5',
        'port'          =>  '3306',
        'socket'        =>  NULL),
        array(    // Database connection 3.
        'name'          =>  'phorum5',
        'server'        =>  '192.168.1.7',
        'user'          =>  'phorum5',
        'password'      =>  'phorum5',
        'port'          =>  '3306',
        'socket'        =>  NULL)
    )
?> ]]>
                  </programlisting>
                </example>
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
    </section>

    <section>
      <title>Run the web based installer</title>
      <para>
        Now that you have uploaded the files, created the database and
        configured the database access for Phorum, you are ready to
        run the web based installation script. Open
        <filename>{phorum url}/admin.php</filename> using your
        web browser. This is the administration interface, which will
        automatically detect that a fresh install has to be
        performed.
      </para>
      <para>
        Follow the instructions on screen to finish the Phorum
        installation.
      </para>
    </section>

    <section>
      <title>Things to do after installing Phorum</title>
      <para>
        <remark>TODO Once the FAQ is documented, this needs a pointer</remark>
        Now the installation is complete, you could continue with
        the following actions to get started:
        <itemizedlist>
          <listitem>
            test if the forum is working
            correctly by opening <filename>{forum url}</filename> in your
            web browser. If you run into problems, please go to
            <filename>{forum url}/admin.php</filename> and click on the
            option "System Sanity Checks" in the menu. This will
            perform a couple of system checks to rule out some basic
            problems. If problems are found, please follow the instructions
            on the sanity checks page to solve them.
            <sbr/><sbr/>
          </listitem>
          <listitem>
            Login into the admin interface at
            <filename>{forum url}/admin.php</filename>
            and check out what settings can be done to customize Phorum
            to your likings. This is also the place where you can
            create new forums.
            <sbr/><sbr/>
          </listitem>
          <listitem>
            Customize the looks of Phorum to your needs by creating a
            custom template. Instructions for this can be found in
            the templates section of the developer manual.
            <sbr/><sbr/>
          </listitem>
          <listitem>
            Read the <xref linkend="install.additionalissues"/> for your
            system, the FAQ and any other parts of the documentation that
            may help you understand Phorum.
          </listitem>
        </itemizedlist>
      </para>
    </section>
  </section>

  <section id="install.additionalissues" xreflabel="additional issues">
    <title>Additional issues</title>
    <section>
      <title>Additional issues for UNIX (Linux, BSD, Solaris, etc.)</title>
      <section>
        <title>Cache directory</title>
        <para>
          In the Phorum settings, there is an entry called "Cache Directory".
          On UNIX systems, the installer will have set that to the default
          location <filename>/tmp</filename>.
          The cache directory is used
          for storing cached data and compiled templates. You can change
          the location of your cache directory if you do not want the
          Phorum files to be in <filename>/tmp</filename> or if you see
          the following kind of error message:
          <screen>
Warning:
fopen(/tmp/tpl-default-header-a72fb9dd20915e5953aa9b07d3eb3871.php):
failed to open stream: permission denied in
/path/to/phorum/include/templates.php on line 184</screen>
          If you want to change the cache directory settings, we advise
          you to change it to <filename>./cache</filename> (this directory
          is already in the Phorum directory).
        </para>
        <para>
          You will have to make sure
          that this directory is writable by the webserver. Most likely
          this means that you have to make it world writable. On a
          UNIX shell prompt, you can do this using the following
          commands:
          <screen>
shell&gt; <literal>cd /path/to/phorum</literal>
shell&gt; <literal>chmod 777 cache</literal></screen>
          If you do not have access to the shell prompt of the server and
          are using FTP to access the server, please check your FTP
          client's help on how to set the permissions for a directory.
        </para>
      </section>
    </section>

    <section>
      <title>Additional issues for Windows</title>
      <section>
        <title>Cache directory</title>
        <para>
          In the Phorum settings, there is an entry called "Cache Directory".
          On Windows systems, the installer will have set that to the default
          location <filename>C:\Windows\Temp</filename>. The cache directory
          is used for storing cached data and compiled templates. You can
          change the location of your cache directory if you do not want the
          Phorum files to be in <filename>C:\Windows\Temp</filename>
          or if you see the following kind of error message:
          <screen>
Warning:
fopen(c:\windows\temp\tpl-default-header-a72fb9dd20915e5953aa9b07d3eb3871.php):
failed to open stream: permission denied in
c:\path\to\phorum\include\templates.php on line 184</screen>
          In that case, you will have to change the cache directory
          setting to point to a valid location. We advise you to change
          it to <filename>./cache</filename> (this directory is already
          in the Phorum directory). Make sure that the webserver can
          write files to this directory.
        </para>
      </section>
      <section>
        <title>Problems sending mail to end users</title>
        <para>
          PHP has to be configured correctly on Windows systems to be able to
          send out mail. If this is not done, you might get errors and mail
          will not arrive. What you need to do is edit the file "php.ini"
          (this file holds the configuration for PHP). Find the section that
          is called "[mail function]". In this section, set the parameter
          "SMTP" to the hostname or IP address of the your SMTP server. If
          you do not know your SMTP server, please ask your internet access
          provider. After this, PHP will know what mailserver to use for
          sending out mail messages.
        </para>
        <para>
          <remark>TODO: module is bundled with 5.2</remark>
          If you have no access to the php.ini file and the system
          administrator is not willing to update it for you, you will have to
          install the SMTP module for Phorum. You can download this module
          from the Phorum &listofmodules;.
          In the settings for this module, you can specify the SMTP to use
          for sending mail. When using this module, you will completely
          bypass PHP's built-in mail system.
        </para>
      </section>
      <section>
        <title>Date formatting</title>
        <para>
          Windows does not fully support the date formatting function
          strftime(). So if you want to change the date formatting
          (which is configured using <literal>$PHORUM['long_date']</literal>
          and <literal>$PHORUM['short_date']</literal> in the
          language file
          <filename>{phorum dir}/include/lang/yourlanguage.php</filename>),
          please read the PHP documentation for strftime() and its
          limitations on the Windows platform at
          <ulink url="http://www.php.net/strftime"/>
        </para>
      </section>
    </section>

  </section>

  <section>
    <title>Support</title>
    <para>
      <remark>TODO: Link to FAQ</remark>
      If you have questions about installing Phorum which
      are not answered by this manual, then please visit the website
      &www.phorum.org; and ask the development team for help in the support
      forum.
    </para>
  </section>

</chapter>
