Club Drupal

CONTENTS OF THIS FILE

---------------------

 * Requirements and notes

 * Optional server requirements

 * Installation

 * Building and customizing your site

 * Multisite configuration

 * More information

REQUIREMENTS AND NOTES

----------------------

Drupal requires:

- A web server. Apache (version 2.0 or greater) is recommended.

- PHP 5.2.4 (or greater) (http://www.php.net/).

- One of the following databases:

  - MySQL 5.0.15 (or greater) (http://www.mysql.com/).

  - MariaDB 5.1.44 (or greater) (http://mariadb.org/). MariaDB is a fully

    compatible drop-in replacement for MySQL.

  - Percona Server 5.1.70 (or greater) (http://www.percona.com/). Percona

    Server is a backwards-compatible replacement for MySQL.

  - PostgreSQL 8.3 (or greater) (http://www.postgresql.org/).

  - SQLite 3.3.7 (or greater) (http://www.sqlite.org/).

For more detailed information about Drupal requirements, including a list of

PHP extensions and configurations that are required, see "System requirements"

(http://drupal.org/requirements) in the Drupal.org online documentation.

For detailed information on how to configure a test server environment using a

variety of operating systems and web servers, see "Local server setup"

(http://drupal.org/node/157602) in the Drupal.org online documentation.

Note that all directories mentioned in this document are always relative to the

directory of your Drupal installation, and commands are meant to be run from

this directory (except for the initial commands that create that directory).

OPTIONAL SERVER REQUIREMENTS

----------------------------

- If you want to use Drupal's "Clean URLs" feature on an Apache web server, you

  will need the mod_rewrite module and the ability to use local .htaccess

  files. For Clean URLs support on IIS, see "Clean URLs with IIS"

  (http://drupal.org/node/3854) in the Drupal.org online documentation.

- If you plan to use XML-based services such as RSS aggregation, you will need

  PHP's XML extension. This extension is enabled by default on most PHP

  installations.

- To serve gzip compressed CSS and JS files on an Apache web server, you will

  need the mod_headers module and the ability to use local .htaccess files.

- Some Drupal functionality (e.g., checking whether Drupal and contributed

  modules need updates, RSS aggregation, etc.) require that the web server be

  able to go out to the web and download information. If you want to use this

  functionality, you need to verify that your hosting provider or server

  configuration allows the web server to initiate outbound connections. Most web

  hosting setups allow this.

INSTALLATION

------------

1. Download and extract Drupal.

   You can obtain the latest Drupal release from http://drupal.org -- the files

   are available in .tar.gz and .zip formats and can be extracted using most

   compression tools.

   To download and extract the files, on a typical Unix/Linux command line, use

   the following commands (assuming you want version x.y of Drupal in .tar.gz

   format):

     wget http://drupal.org/files/projects/drupal-x.y.tar.gz

     tar -zxvf drupal-x.y.tar.gz

   This will create a new directory drupal-x.y/ containing all Drupal files and

   directories. Then, to move the contents of that directory into a directory

   within your web server's document root or your public HTML directory,

   continue with this command:

     mv drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation

2. Optionally, download a translation.

   By default, Drupal is installed in English, and further languages may be

   installed later. If you prefer to install Drupal in another language

   initially:

   - Download a translation file for the correct Drupal version and language

     from the translation server: http://localize.drupal.org/translate/downloads

   - Place the file into your installation profile's translations directory.

     For instance, if you are using the Standard installation profile,

     move the .po file into the directory:

       profiles/standard/translations/

   For detailed instructions, visit http://drupal.org/localize

3. Create the Drupal database.

   Because Drupal stores all site information in a database, you must create

   this database in order to install Drupal, and grant Drupal certain database

   privileges (such as the ability to create tables). For details, consult

   INSTALL.mysql.txt, INSTALL.pgsql.txt, or INSTALL.sqlite.txt. You may also

   need to consult your web hosting provider for instructions specific to your

   web host.

   Take note of the username, password, database name, and hostname as you

   create the database. You will enter this information during the install.

4. Run the install script.

   To run the install script, point your browser to the base URL of your

   website (e.g., http://www.example.com).

   You will be guided through several screens to set up the database, add the

   site maintenance account (the first user, also known as user/1), and provide

   basic web site settings.

   During installation, several files and directories need to be created, which

   the install script will try to do automatically. However, on some hosting

   environments, manual steps are required, and the install script will tell

   you that it cannot proceed until you fix certain issues. This is normal and

   does not indicate a problem with your server.

   The most common steps you may need to perform are:

   a. Missing files directory.

      The install script will attempt to create a file storage directory in

      the default location at sites/default/files (the location of the files

      directory may be changed after Drupal is installed).

      If auto-creation fails, you can make it work by changing permissions on

      the sites/default directory so that the web server can create the files

      directory within it for you. (If you are creating a multisite

      installation, substitute the correct sites directory for sites/default;

      see the Multisite Configuration section of this file, below.)

      For example, on a Unix/Linux command line, you can grant everyone

      (including the web server) permission to write to the sites/default

      directory with this command:

        chmod a+w sites/default

      Be sure to set the permissions back after the installation is finished!

      Sample command:

        chmod go-w sites/default

      Alternatively, instead of allowing the web server to create the files

      directory for you as described above, you can create it yourself. Sample

      commands from a Unix/Linux command line:

        mkdir sites/default/files

        chmod a+w sites/default/files

   b. Missing settings file.

      Drupal will try to automatically create a settings.php configuration file,

      which is normally in the directory sites/default (to avoid problems when

      upgrading, Drupal is not packaged with this file). If auto-creation fails,

      you will need to create this file yourself, using the file

      sites/default/default.settings.php as a template.

      For example, on a Unix/Linux command line, you can make a copy of the

      default.settings.php file with the command:

        cp sites/default/default.settings.php sites/default/settings.php

      Next, grant write privileges to the file to everyone (including the web

      server) with the command:

        chmod a+w sites/default/settings.php

      Be sure to set the permissions back after the installation is finished!

      Sample command:

        chmod go-w sites/default/settings.php

   c. Write permissions after install.

      The install script will attempt to write-protect the settings.php file and

      the sites/default directory after saving your configuration. If this

      fails, you will be notified, and you can do it manually. Sample commands

      from a Unix/Linux command line:

        chmod go-w sites/default/settings.php

        chmod go-w sites/default

5. Verify that the site is working.

   When the install script finishes, you will be logged in with the site

   maintenance account on a "Welcome" page. If the default Drupal theme is not

   displaying properly and links on the page result in "Page Not Found" errors,

   you may be experiencing problems with clean URLs. Visit

   http://drupal.org/getting-started/clean-urls to troubleshoot.

6. Change file system storage settings (optional).

   The files directory created in step 4 is the default file system path used to

   store all uploaded files, as well as some temporary files created by

   Drupal. After installation, you can modify the file system path 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).

   - Your site runs on a number of web servers behind a load balancer or reverse

     proxy (modify the file system path on each server to point to a shared file

     repository).

   - You want to restrict access to uploaded files.

   To modify the file system path:

   a. Ensure that the new location for the path exists and is writable by the

      web server. For example, to create a new directory named uploads and grant

      write permissions, use the following commands on a Unix/Linux command

      line:

        mkdir uploads

        chmod a+w uploads

   b. Navigate to Administration > Configuration > Media > File system, and

      enter the desired path. Note that if you want to use private file storage,

      you need to first enter the path for private files and save the

      configuration, and then change the "Default download method" setting and

      save again.

   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.

7. Revoke documentation file permissions (optional).

   Some administrators suggest making the documentation files, especially

   CHANGELOG.txt, non-readable so that the exact version of Drupal you are

   running is slightly more difficult to determine. If you wish to implement

   this optional security measure, from a Unix/Linux command line you can use

   the following command:

     chmod a-r CHANGELOG.txt

   Note that the example only affects CHANGELOG.txt. To completely hide all

   documentation files from public view, repeat this command for each of the

   Drupal documentation files in the installation directory, substituting the

   name of each file for CHANGELOG.txt in the example.

   For more information on setting file permissions, see "Modifying Linux,

   Unix, and Mac file permissions" (http://drupal.org/node/202483) or

   "Modifying Windows file permissions" (http://drupal.org/node/202491) in the

   Drupal.org online documentation.

8. Set up independent "cron" maintenance jobs.

   Many Drupal modules have tasks that must be run periodically, including the

   Search module (building and updating the index used for keyword searching),

   the Aggregator module (retrieving feeds from other sites), and the System

   module (performing routine maintenance and pruning of database tables). These

   tasks are known as "cron maintenance tasks", named after the Unix/Linux

   "cron" utility.

   When you install Drupal, its built-in cron feature is enabled, which

   automatically runs the cron tasks periodically, triggered by people visiting

   pages of your site. You can configure the built-in cron feature by navigating

   to Administration > Configuration > System > Cron.

   It is also possible to run the cron tasks independent of site visits; this is

   recommended for most sites. To do this, you will need to set up an automated

   process to visit the page cron.php on your site, which executes the cron

   tasks.

   The URL of the cron.php page requires a "cron key" to protect against

   unauthorized access. Your site's cron key is automatically generated during

   installation and is specific to your site. The full URL of the page, with the

   cron key, is available in the "Cron maintenance tasks" section of the Status

   report page at Administration > Reports > Status report.

   As an example for how to set up this automated process, you can use the

   crontab utility on Unix/Linux systems. The following crontab line uses the

   wget command to visit the cron.php page, and runs each hour, on the hour:

   0 * * * * wget -O - -q -t 1 http://example.com/cron.php?cron_key=YOURKEY

   Replace the text "http://example.com/cron.php?cron_key=YOURKEY" in the

   example with the full URL displayed under "Cron maintenance tasks" on the

   "Status report" page.

   More information about cron maintenance tasks is available at

   http://drupal.org/cron, and sample cron shell scripts can be found in the

   scripts/ directory. (Note that these scripts must be customized like the

   above example, to add your site-specific cron key and domain name.)

BUILDING AND CUSTOMIZING YOUR SITE

----------------------------------

A new installation of Drupal defaults to a very basic configuration. To extend

your site, you use "modules" and "themes". A module is a plugin that adds

functionality to Drupal, while a theme changes the look of your site. The core

of Drupal provides several optional modules and themes, and you can download

more at http://drupal.org/project/modules and http://drupal.org/project/themes

Do not mix downloaded or custom modules and themes with Drupal's core modules

and themes. Drupal's modules and themes are located in the top-level modules and

themes directories, while the modules and themes you add to Drupal are normally

placed in the sites/all/modules and sites/all/themes directories. If you run a

multisite installation, you can also place modules and themes in the

site-specific directories -- see the Multisite Configuration section, below.

Never edit Drupal's core modules and themes; instead, use the hooks available in

the Drupal API. To modify the behavior of Drupal, develop a module as described

at http://drupal.org/developing/modules. To modify the look of Drupal, create a

subtheme as described at http://drupal.org/node/225125, or a completely new

theme as described at http://drupal.org/documentation/theme

MULTISITE CONFIGURATION

-----------------------

A single Drupal installation can host several Drupal-powered sites, each with

its own individual configuration.

Additional site configurations are created in subdirectories within the 'sites'

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 new directory name is constructed from the site's URL. The configuration for

www.example.com could be in 'sites/example.com/settings.php' (note that 'www.'

should be omitted if users can access your site at http://example.com/).

Sites do not have to have a different domain. You can also use subdomains and

subdirectories for Drupal sites. For example, example.com, sub.example.com, and

sub.example.com/site3 can all be defined as independent Drupal sites. The setup

for a configuration such as this would look like the following:

  sites/default/settings.php

  sites/example.com/settings.php

  sites/sub.example.com/settings.php

  sites/sub.example.com.site3/settings.php

When searching for a site configuration (for example www.sub.example.com/site3),

Drupal will search for configuration files in the following order, using the

first configuration it finds:

  sites/www.sub.example.com.site3/settings.php

  sites/sub.example.com.site3/settings.php

  sites/example.com.site3/settings.php

  sites/www.sub.example.com/settings.php

  sites/sub.example.com/settings.php

  sites/example.com/settings.php

  sites/default/settings.php

If you are installing on a non-standard port, the port number is treated as the

deepest subdomain. For example: http://www.example.com:8080/ could be loaded

from sites/8080.www.example.com/. The port number will be removed according to

the pattern above if no port-specific configuration is found, just like a real

subdomain.

Each site configuration can have its own site-specific modules and themes in

addition to those installed in the standard 'modules' and 'themes' directories.

To use site-specific modules or themes, simply create a 'modules' or 'themes'

directory within the site configuration directory. For example, if

sub.example.com has a custom theme and a custom module that should not be

accessible to other sites, the setup would look like this:

  sites/sub.example.com/

    settings.php

    themes/custom_theme

    modules/custom_module

NOTE: for more information about multiple virtual hosts or the configuration

settings, consult http://drupal.org/getting-started/6/install/multi-site

For more information on configuring Drupal's file system path in a multisite

configuration, see step 6 above.

MORE INFORMATION

----------------

- See the Drupal.org online documentation:

  http://drupal.org/documentation

- For a list of security announcements, see the "Security advisories" page at

  http://drupal.org/security (available as an RSS feed). This page also

  describes how to subscribe to these announcements via e-mail.

- For information about the Drupal security process, or to find out how to

  report a potential security issue to the Drupal security team, see the

  "Security team" page at http://drupal.org/security-team

- For information about the wide range of available support options, visit

  http://drupal.org and click on Community and Support in the top or bottom

  navigation.