INSTALL.txt

   1 // $Id: INSTALL.txt 144 2007-03-28 07:52:20Z thierry $
   2
   3 CONTENTS OF THIS FILE
   4 ---------------------
   5
   6  * Requirements
   7  * Optional requirements
   8  * Installation
   9     - Drupal administration
  10     - Customizing your theme(s)
  11  * More Information
  12
  13 REQUIREMENTS
  14 ------------
  15
  16 Drupal requires a web server, PHP4 (4.3.3 or greater) or PHP5
  17 (http://www.php.net/) and either MySQL (http://www.mysql.com/)
  18 or PostgreSQL (http://www.postgresql.org/). Your database user
  19 will also need sufficient privileges to run Drupal. Please
  20 check the INSTALL.mysql.txt and INSTALL.pgsql.txt for more
  21 detailed information.
  22
  23 NOTE: the Apache web server and MySQL database are recommended;
  24 other web server and database combinations such as IIS and PostgreSQL
  25 are possible but tested to a lesser extent.
  26
  27 OPTIONAL REQUIREMENTS
  28 ---------------------
  29
  30 - To use XML-based services such as the Blogger API, Jabber, and RSS
  31   syndication, you will need PHP's XML extension. This extension is
  32   enabled by default.
  33
  34 - If you want support for clean URLs, you'll need mod_rewrite and
  35   the ability to use local .htaccess files. (More information can
  36   be found in the Drupal handbook on drupal.org.)
  37
  38 INSTALLATION
  39 ------------
  40
  41 1. DOWNLOAD DRUPAL
  42
  43    You can obtain the latest Drupal release from http://drupal.org/.
  44    The files are in .tar.gz format and can be extracted using most
  45    compression tools. On a typical Unix command line, use:
  46
  47      wget http://drupal.org/files/projects/drupal-x.x.x.tar.gz
  48      tar -zxvf drupal-x.x.x.tar.gz
  49
  50    This will create a new directory drupal-x.x.x/ containing all
  51    Drupal files and directories. Move the contents of that directory
  52    into a directory within your web server's document root or your
  53    public HTML directory:
  54
  55      mv drupal-x.x.x/* drupal-x.x.x/.htaccess /var/www/html
  56
  57 2. CREATE AND PREPARE THE DRUPAL DATABASE
  58
  59    Before you proceed to the next step you should know:
  60     - "username"      - the username for connecting to the database
  61     - "password"      - the password for that username
  62     - "databasename"  - the name of the database
  63
  64    Depending on the database of your choice, please read either
  65    INSTALL.mysql.txt (for MySQL) or INSTALL.pgsql.txt (for PostgreSQL).
  66
  67 3. CONNECTING DRUPAL
  68
  69    The default configuration can be found in the
  70    'sites/default/settings.php' file within your Drupal installation.
  71    Before you can run Drupal, you must set the database URL. Open the
  72    configuration file and edit the $db_url line to match the database
  73    defined in the previous step:
  74
  75      $db_url = "mysql://username:password@localhost/databasename";
  76
  77    If you use PostgreSQL, change "mysql" to "pgsql" in the above line.
  78
  79    In addition, a single Drupal installation can host several
  80    Drupal-powered sites, each with its own individual configuration.
  81    If you don't need multiple Drupal sites, skip to the next section.
  82
  83    Additional site configurations are created in subdirectories within
  84    the 'sites' directory. Each subdirectory must have a 'settings.php'
  85    file which specifies the configuration settings. The easiest way to
  86    create additional sites is to copy the 'default' directory and modify
  87    the 'settings.php' file as appropriate. The new directory name is
  88    constructed from the site's URL. The configuration for www.example.com
  89    could be in 'sites/example.com/settings.php' (note that 'www.' should
  90    be omitted if users can access your site at http://example.com/).
  91
  92    Sites do not each have to have a different domain. You can use
  93    subdomains and subdirectories for Drupal sites also. For example,
  94    example.com, sub.example.com, and sub.example.com/site3 can all be
  95    defined as independent Drupal sites. The setup for a configuration
  96    such as this would look like the following:
  97
  98      sites/default/settings.php
  99      sites/example.com/settings.php
 100      sites/sub.example.com/settings.php
 101      sites/sub.example.com.site3/settings.php
 102
 103    When searching for a site configuration (for example
 104    www.sub.example.com/site3), Drupal will search for configuration
 105    files in the following order, using the first configuration it finds:
 106
 107      sites/www.sub.example.com.site3/settings.php
 108      sites/sub.example.com.site3/settings.php
 109      sites/example.com.site3/settings.php
 110      sites/www.sub.example.com/settings.php
 111      sites/sub.example.com/settings.php
 112      sites/example.com/settings.php
 113      sites/default/settings.php
 114
 115    If you are installing on a non-standard port, the port number is
 116    treated as the deepest subdomain. For example: http://www.example.com:8080/
 117    could be loaded from sites/8080.www.example.com/. The port number
 118    will be removed according to the pattern above if no port-specific
 119    configuration is found, just like a real subdomain.
 120
 121    Each site configuration can have its own site-specific modules and
 122    themes that will be made available in addition to those installed
 123    in the standard 'modules' and 'themes' directories. To use
 124    site-specific modules or themes, simply create a 'modules' or
 125    'themes' directory within the site configuration directory. For
 126    example, if sub.example.com has a custom theme and a custom module
 127    that should not be accessible to other sites, the setup would look
 128    like this:
 129
 130      sites/sub.example.com/:
 131        settings.php
 132        themes/custom_theme
 133        modules/custom_module
 134
 135    NOTE: for more information about multiple virtual hosts or the
 136    configuration settings, consult the Drupal handbook at drupal.org.
 137
 138 4. CONFIGURE DRUPAL
 139
 140    You should consider creating a "files" subdirectory in your Drupal
 141    installation directory. This subdirectory stores files such as
 142    custom logos, user avatars, and other media associated with your
 143    new site. The sub-directory requires "read and write" permission
 144    by the Drupal server process. You can change the name of this
 145    subdirectory at "Administer > Settings > File system settings".
 146
 147    SECURITY NOTICE: Certain Apache configurations can be vulnerable
 148    to a security exploit allowing arbitrary code execution. Drupal
 149    will attempt to automatically create a .htaccess file in your
 150    "files" directory to protect you. If you already have a .htaccess
 151    file in that location, please add the following lines:
 152
 153      SetHandler Drupal_Security_Do_Not_Remove_See_SA_2006_006
 154      Options None
 155      <IfModule mod_rewrite.c>
 156        RewriteEngine off
 157      </IfModule>
 158
 159    You can now launch your browser and point it to your Drupal site.
 160
 161    Create an account and login. The first account will automatically
 162    become the main administrator account with total control.
 163
 164 5. CRON TASKS
 165
 166    Many Drupal modules (such as the search functionality) have periodic
 167    tasks that must be triggered by a cron job. To activate these tasks,
 168    call the cron page by visiting http://www.example.com/cron.php --
 169    this will pass control to the modules and the modules will decide if
 170    and what they must do.
 171
 172    Most systems support the crontab utility for scheduling tasks like
 173    this. The following example crontab line will activate the cron
 174    tasks automatically on the hour:
 175
 176    0   *   *   *   *   wget -O - -q http://www.example.com/cron.php
 177
 178    More information about the cron scripts are available in the admin
 179    help pages and in the Drupal handbook at drupal.org. Example
 180    scripts can be found in the scripts/ directory.
 181
 182 DRUPAL ADMINISTRATION
 183 ---------------------
 184
 185 Upon a new installation, your Drupal website defaults to a very basic
 186 configuration with only a few active modules, one theme, and minimal
 187 user access rights.
 188
 189 Use your administration panel to enable and configure services. For
 190 example, set some general settings for your site with "Administer >
 191 Settings". Enable modules via "Administer > Modules". User permissions
 192 can be set with "Administer > Users > Configure > Permissions".
 193
 194 For more information on configuration options, read the
 195 instructions which accompany the different configuration settings and
 196 consult the various help pages available in the administration panel.
 197
 198 Community-contributed modules and themes are available at http://drupal.org/.
 199
 200 CUSTOMIZING YOUR THEME(S)
 201 -------------------------
 202
 203 Now that your server is running, you will want to customize the look
 204 of your site. Several sample themes are included in the Drupal
 205 installation and more can be downloaded from drupal.org.
 206
 207 Simple customization of your theme can be done using only CSS. Further
 208 changes require understanding the phptemplate engine that is now part
 209 of Drupal. See http://drupal.org/handbook/customization to find out more.
 210
 211
 212 MORE INFORMATION
 213 ----------------
 214
 215 For platform specific configuration issues and other installation and
 216 administration assistance, please consult the Drupal handbook at
 217 http://drupal.org/handbook. You can view the wide range of other
 218 support options available at http://drupal.org/support.