This guide was written to help with the initial installation and configuration of QSF Portal, a MySQL and PHP-based community portal/cms system.

Some noteworthy features include:

* Built-in anti-robot, anti-spam controls;
* Flexible user configuration: Macromedia Flash avatars, blind e-mail correspondence between users, and accessible in 18 languages;
* BBCode and JavaScript post editing tools;
* Powerful administration tools: easy backup and restore system, support for modules, and ability to communicate with users;
* Lightweight CMS module for creation of additional webpages on the site.

=== Who is this guide for? ===

This guide was written for end-users with roughly intermediate knowledge of maintaing a web site.
It is assumed the reader knows the basics of unpacking a compressed archive, using a client for making
FTP or SSH connections, uploading files from your local computer to a remote server via said client,
and possesses a working knowledge of the *NIX command line.

=== Latest Release ===

Up-to-date releases of QSF Portal can be accessed at its [https://github.com/Arthmoor/QSF-Portal official website].
 
=== Copyright and License ===

This document, The QSF Portal Installation Guide, is copyrighted (c) 2006-2025 by
The QSF Portal Development Team. Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published
by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with
no Back-Cover Texts. A copy of the license is available at:

  https://www.gnu.org/copyleft/fdl.html

=== Disclaimer ===

No liability for the contents of this document can be accepted. Use the concepts, examples and information
at your own risk. There may be errors and inaccuracies, that could be damaging to your system.
Proceed with caution, and although this is highly unlikely, the author(s) do not take any responsibility.

All copyrights are held by their by their respective owners, unless specifically noted otherwise.
Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark.
Naming of particular products or brands should not be seen as endorsements.

== Pre-Installation ==

=== Preparing for Migration from Other Forum Package ===

TODO: Probably will require a separate guide.

=== Preparing for Upgrade ===

If you will be upgrading from an earlier version of QSF Portal, please hang onto your settings.php file.

It is recommended when uploading files you do not overwrite this file. This is easiest done by making a copy
temporarily and putting it back after all files are in place. Or deleting the settings.php provided in the new release.

=== Preparing for Installation ===

In order for QSF Portal to function, the following are required prior to installation:

* A functioning web server, like [https://www.apache.org/ Apache], or a web hosting service;
* FTP or SSH access to your webspace;
* [https://www.mysql.com/ MySQL] version 5.7 or higher, or [https://mariadb.org/ MariaDB] version 10.3 or higher; and
* [https://secure.php.net/ PHP] version 7.4.0 or higher.

Also, it is helpful to know the following:

* The URL to your web site; and
* The directory containing your "webspace." It depends upon the host, but by default Apache servers look
  in $HOME/public_html/ for web pages to serve.

If you will be using a third-party web hosting service, speak to an administrator about setting up a
MySQL database for your site, for which there may be additional hosting fees. The administrator will
likely provide you the following important information:

* The hostname of the MySQL server;
* The username and password required to access your database; and
* The ''name'' of your database.
  
== Installation ==

This section will ready the user's webspace for QSF Portal, guide the user through uploading
QSF Portal to the webspace, and setting the proper permissions for installation.
Those comfortable with the uploading process can do so and skip to the "Permissions" subsection.

=== Uploading the Files ===

Unpack the QSF Portal archive into a directory called qsfp on your desktop.

Log into your webspace, via FTP or SSH and create a directory called qsfportal.

NOTE: It does not have to be named qsfportal -- you may name it whatever you wish, though 
qsfportal will be used throughout the remainder of this guide. Adapt to your situation as necessary.

Direct your client to your local qsfportal folder and upload everything to the qsfportal directory within your webspace.

Remotely, navigate to the qsfportal directory. Check the directory listing. Here is what it should look like:

admincp		attachments		avatars			docs		downloads		emojis
func		install			javascript		languages	lib			modlets
packages	skins			updates			.htaccess	alternate_robots.txt	favicon.ico
global.php	index.php		LICENSE			README.md	robots.txt		settings.php

You have successfully uploaded QSF Portal to your webspace!
Now it is time to set permissions for the files, which affects both the security and operability of the installation.

=== Permissions ===

Within your client you may have to modify the permissions of the QSF Portal files uploaded to your webspace.
If you are using a third-party hosting service, ensure you are not violating any terms of service by modifying permissions.
Determine what the host's recommended permissions are for directories and files, particularly PHP files. Some hosts
may not require you to modify permissions because of their server configuration.
Be aware of your host's policies and what portions of this subsection apply to you,
as it deals with security and access control.

It is assumed you have uploaded QSF Portal to a directory called qsfportal within your webspace.
Connect to your webspace via FTP or SSH (if you have not already) and navigate to the qsfportal directory.

==== Permission changing if your server is running a UNIX permission system ====

It is prudent to assign your host's default permissions to all the files you uploaded.
Modify the following values with those advised by your host.
On most servers, it is, in ''chmod'' terms, '''755''' for directories, and '''644''' for files.

If you have shell access, these are some easy commands for expediting permissions for all within
the qsfportal directory. Some hosts may have a script available which will automatically
set proper permissions. Please consult your administrator. Here are some examples:

  $ find . -type d -print0 | xargs -0 chmod 755
  $ find . -type f -print0 | xargs -0 chmod 644

''NOTE: If the find< does not work, try using gfind instead.''

There are specific directories and files that will require write permissions.
On third-party hosts, administrators may provide permission guidelines for such files and folders.
If you have such information available, please see the section ''Permission Errors'' and set permissions accordingly.
If you are unsure, please continue. Permission errors will be dealt with on a case-by-case basis later.

==== Permissions if you are using IIS ====

IIS works differently to any UNIX system because CHMOD does not exist in the same way.
When using IIS you must be browsing your files in a program like windows explorer to make them easy to change.
Some FTP programs have the choice of using CHMOD of IIS permissions.

When you are viewing your folders you now need to right click on the folder that you wish to change the
permission of, in this case it will be the qsforums directory. Now select 'Sharing and Security'
and select the tab saying 'Web Sharing'. If you now select the 'share this folder' radio button you should
have a window with a selection of permission options, you need to make sure the bottom section has
'Execute(include scripts)' is selected and you have full read, write and execute options also enabled.
You need to make sure that the user you are using has the correct permissions to change permissions, contact
your host if you have any concerns on changing permissions or are unsure on what to do.

You have successfully set your permissions. The next section involves accessing your installation of
Quicksilver Forums with a JavaScript and cookies-enabled browser to setup the initial configuration.

== Configuration ==

This section will guide you through the basic web-based configuration of QSF Portal.

=== Post-Installation Configuration ===

Maintain a SSH or FTP connection to your webspace. Launch your favorite graphical browser
(with JavaScript and CSS enabled), and access the qsfportal/install subdirectory.

For example:

  https://example.com/~you/qsforums/install

This takes you to the QSF Portal install page. Select the applicable radio button.
If this is your first install, the default selection will serve you fine.
Note the values in the left column, which report your server, PHP, and MySQL versions and configurations.
Keep this information handy, in case more in-depth troubleshooting is required.

The next page has four sections: New Database Configuration, New Board Settings, Administrator Account Settings,
and Create Initial Data.

* '''New Database Configuration:''' Fill in the necessary details for your database as provided by your administrator.
 "Database Socket" and/or "Database Port" may be left blank if those values are unnecessary for your host.
 As for "Table Prefix", do not modify the default value unless you will be using the same MySQL database for
 multiple instances of QSF Portal.
* '''New Portal Settings:''' Fill in the name of your portal, and verify the install script accurately captured
 the URL to your QSF Portal installation. Correct it if necessary.
* '''Administrator Account Settings:''' When selecting an administrative username, it is recommended it not be
 obvious, like ''admin''. Select an obscure password, preferrably composed of upper and lowercase letters, numbers,
 and symbols. For security reasons, change your administrative password frequently to safeguard your portal.

Click "Continue." If you are directed to a page saying "Congratulations!", you have successfully installed
QSF Portal! In such a case, delete the qsfportal/install directory immediately.
If not removed promptly, it could allow a third-party to reconfigure your site.

If you are receiving error messages, proceed to the next section, which has procedures for dealing with the
most common difficulties.

== Troubleshooting ==

This section contains remedies for common errors, the vast majority of which deal with file and directory
permissions. The first subsection, "Permission-Related Errors," contains those directories and files that
require write permissions, since a considerable majority of errors deal with incorrect permissions.
The remainder subsections deal with individual error messages.

Before continuing, please verify that you are using a web browser with JavaScript, cookies, and CSS enabled
while working with QSF Portal' web-based configuration tools.

=== Permission-Related Errors ===

The following directories and files require read and write permissions.
Please verify their permissions are set properly. The necessary permissions differ from host to host.
Consult your administrator. Otherwise, it is safe to set directory permissions to '''755''' and
file permissions to '''644''' using the chmod command. In some cases these permissions are not
sufficient; world-writeable permissions ('''777''' for directories, '''666''' for files) may need to be set.
World-writeable permissions should be assigned cautiously as such permissions could threaten site security.

All files and directories require world readable permissions.
The following directories and files require world-writeable permissions:

  qsfportal/attachments/
  qsfportal/avatars/uploaded/
  qsfportal/downloads/
  qsfportal/emojis/
  qsfportal/packages/
  qsfportal/updates/

Please attempt to resume installation after setting the proper permissions to these files.
The remaining subsections deal with individual error messages and their respective remedies.

=== Individual Error Messages ===

This following subsections deal with individual error messages you may encounter during the installation process.

==== Couldn't connect to a database using the specified information. ====

  "Couldn't connect to a database using the specified information."

This error message is displayed when QSF Portal is unable to connect to your host's MySQL
database with user-sepcified information at install time.

In your browser, go "back" to the configuration page. Verify that the database information you entered is correct.
This error can only occur if these values are incorrect or incomplete.
Verify you have input the correct values as supplied by your administrator.

==== The database connection was ok, but settings.php could not be updated. ====

  "The database connection was ok, but settings.php could not be updated. CHMOD settings.php to 0666."

Assuming the "Permission-Related Errors" section has been consulted and permissions already set,
you may have to set ''world-writeable'' permissions for the settings.php file.
Consult your administator first before assigning world-writeable permissions:

  $ chmod 666 settings.php

Click your browser's "back" button, verify the necessary information is input, and attempt to "continue" once more.

==== Database connected, settings written, but... ====

  "Database connected, settings written, but no tables could be loaded from file: data_tables.php"

These errors are generated when qsfportal/install/mysqli_data_tables.php is either corrupt or lack the necessary
read permissions. You may wish to re-upload the file before continuing.

These files need world-readable permissions. From the qsfportal/install directory, issue the following command:

  $ chmod 644 mysqli_data_tables.php

Click your browser's "back" button, verify the necessary information is input, and attempt to "continue" once more.

==== You have not specified an admistrator account... ====

  "You have not specified an admistrator account. Please go back and correct this error."

This error message is generated when the ''Administrator Account Settings'' section of the configuration
page was not properly completed. Quicksilver Forums requires the user to set an administrator username,
enter the administrator's password twice, and supply an e-mail address for the administrator
(which will not be published by default).

Click your browser's "back" button, verify the necessary information is input, and attempt to "continue" once more.