397 lines
16 KiB
Markdown
397 lines
16 KiB
Markdown
INSTALLATION GUIDE
|
|
==================
|
|
|
|
Contents of this file:
|
|
|
|
* Requirements
|
|
* Installation
|
|
* Drupal administration
|
|
* Customizing your theme(s)
|
|
* Multisite Configuration
|
|
|
|
|
|
REQUIREMENTS
|
|
------------
|
|
|
|
**SuiteDesk** began long time ago as a Drupal 6 project, and now continues as a
|
|
standalone opensource product. It requires:
|
|
|
|
* A web server (Apache web server with mode_rewrite module and the ability to
|
|
use local `.htaccess` files is recommended),
|
|
* PHP 5 (better with version 5.4.45), and
|
|
* MySQL (4.1.1 or greater).
|
|
|
|
See http://www.php.net and http://www.mysql.com for more information.
|
|
|
|
|
|
INSTALLATION
|
|
------------
|
|
|
|
### 1. DOWNLOAD SUITEDESK
|
|
|
|
You can obtain the latest **SuiteDesk** release from:
|
|
|
|
https://gitlab.cillero.es/manuelcillero/suitedesk ( = REPOSITORY )
|
|
|
|
If you select files in `.tar.gz` or `.zip` format, they can be extracted using
|
|
most compression tools. Example, on a typical Unix command line, use:
|
|
|
|
wget REPOSITORY/archive.tar.gz?ref=version
|
|
tar -zxvf archive.tar.gz
|
|
|
|
This will create a new directory called `suitedesk-version/` containing all
|
|
**SuiteDesk** files and directories. Move the contents of that directory into
|
|
your web server's document root or your public HTML directory:
|
|
|
|
mv suitedesk-version/* suitedesk-version/.htaccess /var/www/html
|
|
|
|
### 2. DOWNLOAD AND INSTALL LIBRARIES
|
|
|
|
Just follow the instructions provided in the `README.md` file available in the
|
|
`libraries` directory to install the required libraries.
|
|
|
|
### 3. CREATE THE CONFIGURATION FILE AND GRANT WRITE PERMISSIONS
|
|
|
|
**SuiteDesk** comes with a `default.settings.php` file in the `config/default`
|
|
directory. Use this file as a template to create your settings file. To avoid
|
|
problems when upgrading, **SuiteDesk** is not packaged with an actual settings
|
|
file. You must create a file named `settings.php`. You may do so by making a
|
|
copy of `default.settings.php`. For example (from the `config` directory):
|
|
|
|
cp config/default/default.settings.php config/default/settings.php
|
|
|
|
Next, give the web server write privileges to the `config/default/settings.php`
|
|
file with the command (from the `config` directory):
|
|
|
|
chmod o+w config/default/settings.php
|
|
|
|
So that the files directory can be created automatically, give the web server
|
|
write privileges to the `config/default` directory with the command (from the
|
|
`config` directory):
|
|
|
|
chmod o+w config/default
|
|
|
|
### 4. CREATE THE SUITEDESK DATABASE
|
|
|
|
**SuiteDesk** requires access to a database in order to be installed. Your
|
|
database user will need sufficient privileges to run **SuiteDesk**.
|
|
|
|
To create a database using PHPMyAdmin or a web-based control panel consult the
|
|
documentation or ask your webhost service provider.
|
|
|
|
Take note of the *username*, *password*, *database name* and *hostname* as you
|
|
create the database. You will enter these items in the next commands.
|
|
|
|
This step is only necessary if you don't already have a database setup (e.g. by
|
|
your host). In the following examples, *useradmin* is an example MySQL user
|
|
which has the CREATE and GRANT privileges. Use the appropriate user name for
|
|
your system.
|
|
|
|
First, you must create a new database for your site (here, *databasename* is the
|
|
name of the new database):
|
|
|
|
mysqladmin -u useradmin -p create databasename
|
|
|
|
MySQL will prompt for the *useradmin* database password and then create the
|
|
initial database files. Next you must login and set the access database rights:
|
|
|
|
mysql -u useradmin -p
|
|
|
|
Again, you will be asked for the *useradmin* database password. At the MySQL
|
|
prompt, enter following command:
|
|
|
|
```sql
|
|
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER,
|
|
CREATE TEMPORARY TABLES ON databasename.*
|
|
TO 'username'@'localhost' IDENTIFIED BY 'password';
|
|
```
|
|
|
|
where
|
|
|
|
- *databasename* is the name of your database,
|
|
- *username@localhost* is the username of your MySQL account, and
|
|
- *password* is the password required for that username.
|
|
|
|
Note: Unless your database user has all of the privileges listed above, you will
|
|
not be able to run **SuiteDesk**.
|
|
|
|
If successful, MySQL will reply with:
|
|
|
|
Query OK, 0 rows affected
|
|
|
|
In the configuration file you will fill out the `$db_url` value to configure the
|
|
database connection using the format:
|
|
|
|
$db_url['default'] = 'mysql://username:password@localhost/databasename';
|
|
|
|
If your *username*, *password* or *database name* contain characters used to
|
|
delineate `$db_url` parts, you can escape them via URI hex encodings:
|
|
|
|
: = %3a / = %2f @ = %40
|
|
+ = %2b ( = %28 ) = %29
|
|
? = %3f = = %3d & = %26
|
|
|
|
If you prefix some or all database table names, you can use the `$db_prefix`
|
|
setting and each table name will be prepended with its value. Be sure to use
|
|
valid database characters only, usually alphanumeric and underscore. If no
|
|
prefixes are desired, leave it as an empty string ''.
|
|
|
|
To have all database names prefixed, set `$db_prefix` as a string:
|
|
|
|
$db_prefix = 'main_';
|
|
|
|
To provide prefixes for specific tables set `$db_prefix` as an array where keys
|
|
are the table names and the values are the prefixes. The `default` element holds
|
|
the prefix for any tables not specified elsewhere in the array:
|
|
|
|
$db_prefix = array(
|
|
'default' => 'main_',
|
|
'users' => 'shared_',
|
|
'sessions' => 'shared_',
|
|
'role' => 'shared_',
|
|
'authmap' => 'shared_',
|
|
);
|
|
|
|
All data stored in database is in UTF-8. MySQL support different algorithms for
|
|
comparing, indexing, and sorting characters; a so called "collation". The
|
|
default collation of a database normally works for many use-cases, but depending
|
|
on the language(s) of the stored data, it may be necessary to use a different
|
|
collation in the `$db_collation` setting. Important:
|
|
|
|
- Only set or change this value before installing **SuiteDesk**, unless you
|
|
know what you are doing.
|
|
- All database tables and columns should be in the same collation. Otherwise,
|
|
string comparisons performed for table JOINs will be significantly slower.
|
|
- Especially when storing data in German or Russian on MySQL 5.1+, you want
|
|
to use the 'utf8_unicode_ci' collation instead.
|
|
- More information at http://drupal.org/node/772678
|
|
|
|
### 5. POPULATE THE DATABASE
|
|
|
|
Run the next command to setup the database, create tables, populate them, set
|
|
the first users accounts and provide basic web site settings. Remember, you will
|
|
be asked for the *username* database password defined in previous step:
|
|
|
|
mysql -u username -p databasename < config/populatedb.sql
|
|
|
|
Also you will need to create a files storage directory in the default location
|
|
at config/default/files (the location of the files directory may be changed
|
|
after Drupal is installed). In some cases, you may need to create the directory
|
|
and modify its permissions manually. Use the following commands (from the
|
|
installation directory) to create the files directory and grant the web server
|
|
write privileges to it:
|
|
|
|
mkdir config/default/files
|
|
chmod o+w config/default/files
|
|
|
|
The install script will attempt to write-protect the settings.php file and the
|
|
config/default directory after saving your configuration. However, you may need
|
|
to manually write-protect them using the commands (from the installation
|
|
directory):
|
|
|
|
chmod a-w config/default/settings.php
|
|
chmod a-w config/default
|
|
|
|
If you make manual changes to the file later, be sure to protect it again after
|
|
making your modifications. Failure to remove write permissions to that file is a
|
|
security risk. Although the default location for the settings.php file is at
|
|
config/default/settings.php, it may be in another location if you use the
|
|
multi-site setup, as explained below.
|
|
|
|
### 6. REVIEW FILE SYSTEM STORAGE SETTINGS AND FILE PERMISSIONS
|
|
|
|
The files directory created in previous step is the default file system path
|
|
used to store all uploaded files, as well as some temporary files created by
|
|
Drupal. After installation, the settings for the file system path may be
|
|
modified to store uploaded files in a different location.
|
|
|
|
It is not necessary to modify this path, but you may wish to change it if:
|
|
|
|
* your site runs multiple Drupal installations from a single codebase (modify
|
|
the file system path of each installation to a different directory so that
|
|
uploads do not overlap between installations); or,
|
|
|
|
* your site runs a number of web server front-ends behind a load balancer or
|
|
reverse proxy (modify the file system path on each server to point to a
|
|
shared file repository).
|
|
|
|
To modify the file system path:
|
|
|
|
* Ensure that the new location for the path exists or create it if necessary.
|
|
To create a new directory named uploads, for example, use the following
|
|
command from a shell or system prompt (while in the installation directory):
|
|
|
|
mkdir uploads
|
|
|
|
* Ensure that the new location for the path is writable by the web server
|
|
process. To grant write permissions for a directory named uploads, you may
|
|
need to use the following command from a shell or system prompt (while in
|
|
the installation directory):
|
|
|
|
chmod o+w uploads
|
|
|
|
* Access the file system path settings in Drupal by selecting these menu items
|
|
from the Navigation menu:
|
|
|
|
Administer > Site configuration > File system
|
|
|
|
Enter the path to the new location (e.g.: uploads) at the File System Path
|
|
prompt.
|
|
|
|
Changing the file system path after files have been uploaded may cause
|
|
unexpected problems on an existing site. If you modify the file system path
|
|
on an existing site, remember to copy all files from the original location
|
|
to the new location.
|
|
|
|
Some administrators suggest making the documentation files non-readable so that
|
|
the exact version of **SuiteDesk** you are running is slightly more difficult to
|
|
determine. If you wish to implement this optional security measure, use the
|
|
following command from a shell or system prompt (while in the `config`
|
|
directory):
|
|
|
|
chmod a-r CHANGELOG.md
|
|
|
|
Note that the example only affects CHANGELOG.md. To completely hide all
|
|
documentation files from public view, repeat this command for each of the Drupal
|
|
documentation files in the `config` directory, substituting the name of each
|
|
file for CHANGELOG.md in the example.
|
|
|
|
### 7. INITIAL CONFIGURATION AND FIRST ACCESS
|
|
|
|
When the install script succeeds, you will be directed to the "Welcome" page,
|
|
and you will be logged in as the administrator already. Proceed with the initial
|
|
configuration steps suggested on the "Welcome" page.
|
|
|
|
If the default **SuiteDesk** theme is not displaying properly and links on the
|
|
page result in "Page Not Found" errors, try manually setting the `$base_url`
|
|
variable in the `settings.php` file if not already set. It's currently known
|
|
that servers running FastCGI can run into problems if the `$base_url` variable
|
|
is left commented out (see http://bugs.php.net/bug.php?id=19656). Examples:
|
|
|
|
$base_url = 'http://www.example.com';
|
|
$base_url = 'http://www.example.com:8888';
|
|
$base_url = 'http://www.example.com/drupal';
|
|
$base_url = 'https://www.example.com:8888/drupal';
|
|
|
|
You might also want to force users to use a given domain. See the `.htaccess`
|
|
file for more information. Drupal automatically generates a unique session
|
|
cookie name for each site based on its full domain name. If you have multiple
|
|
domains pointing at the same site, you can either redirect them all to a single
|
|
domain (see comment in `.htaccess`), or uncomment the `$cookie_domain` and
|
|
specify their shared base domain. Doing so assures that users remain logged in
|
|
as they cross between your various domains.
|
|
|
|
Also you can see in the `settings.php` file what PHP settings are possible,
|
|
including whether they can be set at runtime (i.e., when ini_set() occurs), read
|
|
the PHP documentation at http://www.php.net/manual/en/ini.php#ini.list and take
|
|
a look at the `.htaccess` file to see which non-runtime settings are used there.
|
|
Settings defined in the configuration file should not be duplicated there so as
|
|
to avoid conflict issues.
|
|
|
|
If you encounter a situation where users post a large amount of text, and the
|
|
result is stripped out upon viewing but can still be edited, Drupal's output
|
|
filter may not have sufficient memory to process it. If you have this, you may
|
|
wish to uncomment the lines with PHP settings `pcre.*_limit` and increase their
|
|
limit values. See http://php.net/manual/en/pcre.configuration.php.
|
|
|
|
Finally, to override specific global settings for your site, set them in the
|
|
configuration file, including the reverse proxy if needed.
|
|
|
|
And that's all, you are ready to access to your site writting its URL in your
|
|
preferred and use one of the next pre-configured Drupal/**SuiteDesk** users:
|
|
|
|
* root, Drupal user to administer site (see Drupal Administration below),
|
|
* pmdemo, SuiteDesk user to use Project management features,
|
|
* clidemo, SuiteDesk user to use Customer features.
|
|
|
|
It's highly recommended to change the password of all these users before
|
|
delivery the site in production.
|
|
|
|
### 8. CRON MAINTENANCE TASKS
|
|
|
|
Many **SuiteDesk** modules have periodic tasks that must be triggered by a cron
|
|
maintenance task, including search module (to build and update the index used
|
|
for keyword searching) and system module (to perform routine maintenance and
|
|
pruning on system tables). To activate these tasks, call the cron page by
|
|
visiting http://www.example.com/cron.php, which, in turn, executes tasks on
|
|
behalf of installed modules.
|
|
|
|
Most systems support the crontab utility for scheduling tasks like this. The
|
|
following example crontab line will activate the cron tasks automatically on the
|
|
hour:
|
|
|
|
0 * * * * wget -O - -q -t 1 http://www.example.com/cron.php
|
|
|
|
|
|
DRUPAL ADMINISTRATION
|
|
---------------------
|
|
|
|
A new installation of Drupal defaults to a very basic configuration with only a
|
|
few active modules and minimal user access rights.
|
|
|
|
Use your administration panel to enable and configure services. For example:
|
|
|
|
General Settings Administer > Site configuration > Site information
|
|
Enable Modules Administer > Site building > Modules
|
|
Configure Themes Administer > Site building > Themes
|
|
Set User Permissions Administer > User management > Permissions
|
|
|
|
For more information on configuration options, read the instructions which
|
|
accompany the different configuration settings and consult the various help
|
|
pages available in the administration panel.
|
|
|
|
Community-contributed modules and themes are available at http://drupal.org/.
|
|
|
|
|
|
CUSTOMIZING YOUR THEME(S)
|
|
-------------------------
|
|
|
|
Now that your installation is running, you will want to customize the look of
|
|
your site. Several sample themes are included and more can be downloaded from
|
|
drupal.org.
|
|
|
|
Simple customization of your theme can be done using only CSS. Further changes
|
|
require understanding the phptemplate engine that is part of Drupal. See
|
|
http://drupal.org/handbook/customization to find out more.
|
|
|
|
|
|
MULTISITE CONFIGURATION
|
|
-----------------------
|
|
|
|
A single **SuiteDesk** installation can host several Drupal-powered sites, each
|
|
with its own individual configuration.
|
|
|
|
Additional site configurations are created in subdirectories within the `config`
|
|
directory. Each subdirectory must have a `settings.php` file which specifies the
|
|
configuration settings. The easiest way to create additional sites is to copy
|
|
the `default` directory and modify the `settings.php` file as appropriate. The
|
|
configuration file to be loaded is based upon the rules below.
|
|
|
|
The configuration directory will be discovered by stripping the website's
|
|
hostname from left to right and pathname from right to left. The first
|
|
configuration file found will be used and any others will be ignored. If no
|
|
other configuration file is found then the default configuration file at
|
|
`config/default` will be used. For example, for a fictitious site installed at
|
|
http://www.example.org/mysite/test the `settings.php` is searched in the
|
|
following directories:
|
|
|
|
1. config/www.example.org.mysite.test
|
|
2. config/example.org.mysite.test
|
|
3. config/org.mysite.test
|
|
|
|
4. config/www.example.org.mysite
|
|
5. config/example.org.mysite
|
|
6. config/org.mysite
|
|
|
|
7. config/www.example.org
|
|
8. config/example.org
|
|
9. config/org
|
|
|
|
10. config/default
|
|
|
|
If you are installing on a non-standard port number, prefix the hostname with
|
|
that number. For example, http://www.example.org:8080/mysite/test could be
|
|
loaded from `config/8080.www.example.org.mysite.test` directory.
|
|
|
|
For more information on configuring the file system path in a multi-site
|
|
configuration, see step 7 above.
|