INSTALL.txt

   1 // $Id: INSTALL.txt,v 1.39.2.2 2007/07/26 05:29:58 drumm Exp $
   2
   3 CONTENTS OF THIS FILE
   4 ---------------------
   5
   6  * Changes
   7  * Requirements
   8  * Optional requirements
   9  * Installation
  10  * Drupal administration
  11  * Customizing your theme(s)
  12  * Multisite Configuration
  13  * More Information
  14
  15 CHANGES
  16 -------
  17
  18 As of Drupal 5.0 installation has been automated by an install script. It is no
  19 longer necessary to manually edit the "settings.php" file, and database tables
  20 are created automatically.
  21
  22 REQUIREMENTS
  23 ------------
  24
  25 Drupal requires a web server, PHP4 (4.3.3 or greater) or PHP5
  26 (http://www.php.net/) and either MySQL (http://www.mysql.com/) or PostgreSQL
  27 (http://www.postgresql.org/). The Apache web server and MySQL database are
  28 recommended; other web server and database combinations such as IIS and
  29 PostgreSQL have been tested to a lesser extent. When using MySQL, version 4.1
  30 or greater is recommended to assure you can safely transfer the database.
  31
  32 For more detailed information about Drupal requirements, see "Requirements"
  33 (http://drupal.org/requirements) in the Drupal Handbook.
  34
  35 Guidelines for setting up a server environment with a variety of operating
  36 systems and in special cases are available in the Drupal handbook
  37 (http://drupal.org/node/260)
  38
  39 OPTIONAL REQUIREMENTS
  40 ---------------------
  41
  42 - To use XML-based services such as the Blogger API, Jabber, and RSS
  43 syndication, you will need PHP's XML extension. This extension is enabled by
  44 default.
  45
  46 - If you want support for clean URLs, you'll need mod_rewrite and the ability
  47 to use local .htaccess files.
  48
  49 INSTALLATION
  50 ------------
  51
  52 1. DOWNLOAD DRUPAL
  53
  54    You can obtain the latest Drupal release from http://drupal.org/. The files
  55    are in .tar.gz format and can be extracted using most compression tools. On a
  56    typical Unix command line, use:
  57
  58      wget http://drupal.org/files/projects/drupal-x.x.tar.gz
  59      tar -zxvf drupal-x.x.tar.gz
  60
  61    This will create a new directory drupal-x.x/ containing all Drupal files
  62    and directories. Move the contents of that directory into a directory within
  63    your web server's document root or your public HTML directory:
  64
  65      mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html
  66
  67 2. CREATE THE DRUPAL DATABASE
  68
  69    Drupal requires access to a database in order to be installed. Your database
  70    user will need sufficient privileges to run Drupal. Additional information
  71    about privileges, and instructions to create a database using the command
  72    line are available in INSTALL.mysql.txt (for MySQL) or INSTALL.pgsql.txt
  73    (for PostgreSQL).
  74
  75    To create a database using PHPMyAdmin or a web-based control panel consult
  76    the documentation or ask your webhost service provider.
  77
  78    Take note of the username, password, database name and hostname as you
  79    create the database. You will enter these items in the install script.
  80
  81 3. RUN THE INSTALL SCRIPT
  82
  83    The install script will set the base URL, connect Drupal to the database, and
  84    create tables in the database.
  85
  86    To run the install script point your browser to the base url of your website
  87    (i.e. http://www.example.com). You will be presented with the "Database
  88    Configuration" page.
  89
  90    The install script will attempt to write-protect the settings.php after
  91    updating it with the information you provide in the installation routine.
  92    If you make manual changes to that file later, be sure to protect it again
  93    after making your modifications. Failure to remove write permissions to
  94    that file is a security risk. The default location for the settings.php
  95    file is at sites/default/settings.php, but it may be in another location
  96    if you use the multi-site setup, as explained below.
  97
  98 4. CONFIGURE DRUPAL
  99
 100    When the install script succeeds, you will be directed to the "Welcome" page.
 101    In "step one" click "create the first account" which will become the main
 102    administrator account with total control. Login as the administrator and
 103    complete the initial configuration steps on the "Welcome" page.
 104
 105    Consider creating a "files" subdirectory in your Drupal installation
 106    directory. This subdirectory stores files such as custom logos, user avatars,
 107    and other media associated with your new site. The sub-directory requires
 108    "read and write" permission by the Drupal server process. You can change
 109    the name of this subdirectory at "administer > site configuration > file
 110    system".
 111
 112 5. CRON TASKS
 113
 114    Many Drupal modules (such as the search functionality) have periodic tasks
 115    that must be triggered by a cron job. To activate these tasks, call the cron
 116    page by visiting http://www.example.com/cron.php --this will pass control to
 117    the modules and the modules will decide if and what they must do.
 118
 119    Most systems support the crontab utility for scheduling tasks like this. The
 120    following example crontab line will activate the cron tasks automatically on
 121    the hour:
 122
 123    0   *   *   *   *   wget -O - -q -t 1 http://www.example.com/cron.php
 124
 125    More information about the cron scripts are available in the admin help pages
 126    and in the Drupal handbook at drupal.org. Example scripts can be found in the
 127    scripts/ directory.
 128
 129 DRUPAL ADMINISTRATION
 130 ---------------------
 131
 132 A new installation of Drupal defaults to a very basic configuration with only a
 133 few active modules and minimal user access rights.
 134
 135 Use your administration panel to enable and configure services. For example:
 136
 137 General Settings       Administer > Site configuration > Site information
 138 Enable Modules         Administer > Site building > Modules
 139 Set User Permissions   Administer > User management > Access control
 140 Configure Themes       Administer > Site building > Themes
 141
 142 For more information on configuration options, read the instructions which
 143 accompany the different configuration settings and consult the various help
 144 pages available in the administration panel.
 145
 146 Community-contributed modules and themes are available at http://drupal.org/.
 147
 148 CUSTOMIZING YOUR THEME(S)
 149 -------------------------
 150
 151 Now that your installation is running, you will want to customize the look of
 152 your site. Several sample themes are included and more can be downloaded from
 153 drupal.org.
 154
 155 Simple customization of your theme can be done using only CSS. Further changes
 156 require understanding the phptemplate engine that is now part of Drupal. See
 157 http://drupal.org/handbook/customization to find out more.
 158
 159 MULTISITE CONFIGURATION
 160 -----------------------
 161
 162 A single Drupal installation can host several Drupal-powered sites, each with
 163 its own individual configuration.
 164
 165 Additional site configurations are created in subdirectories within the 'sites'
 166 directory. Each subdirectory must have a 'settings.php' file which specifies the
 167 configuration settings. The easiest way to create additional sites is to copy
 168 the 'default' directory and modify the 'settings.php' file as appropriate. The
 169 new directory name is constructed from the site's URL. The configuration for
 170 www.example.com could be in 'sites/example.com/settings.php' (note that 'www.'
 171 should be omitted if users can access your site at http://example.com/).
 172
 173 Sites do not have to have a different domain. You can also use subdomains and
 174 subdirectories for Drupal sites. For example, example.com, sub.example.com,
 175 and sub.example.com/site3 can all be defined as independent Drupal sites. The
 176 setup for a configuration such as this would look like the following:
 177
 178   sites/default/settings.php
 179   sites/example.com/settings.php
 180   sites/sub.example.com/settings.php
 181   sites/sub.example.com.site3/settings.php
 182
 183 When searching for a site configuration (for example www.sub.example.com/site3),
 184 Drupal will search for configuration files in the following order, using the
 185 first configuration it finds:
 186
 187   sites/www.sub.example.com.site3/settings.php
 188   sites/sub.example.com.site3/settings.php
 189   sites/example.com.site3/settings.php
 190   sites/www.sub.example.com/settings.php
 191   sites/sub.example.com/settings.php
 192   sites/example.com/settings.php
 193   sites/default/settings.php
 194
 195 If you are installing on a non-standard port, the port number is treated as the
 196 deepest subdomain. For example: http://www.example.com:8080/ could be loaded
 197 from sites/8080.www.example.com/. The port number will be removed according to
 198 the pattern above if no port-specific configuration is found, just like a real
 199 subdomain.
 200
 201 Each site configuration can have its own site-specific modules and themes in
 202 addition to those installed in the standard 'modules'and 'themes' directories.
 203 To use site-specific modules or themes, simply create a 'modules' or 'themes'
 204 directory within the site configuration directory. For example, if
 205 sub.example.com has a custom theme and a custom module that should not be
 206 accessible to other sites, the setup would look like this:
 207
 208   sites/sub.example.com/:
 209   settings.php
 210   themes/custom_theme
 211   modules/custom_module
 212
 213 NOTE: for more information about multiple virtual hosts or the configuration
 214 settings, consult the Drupal handbook at drupal.org.
 215
 216 MORE INFORMATION
 217 ----------------
 218
 219 For platform specific configuration issues and other installation and
 220 administration assistance, please consult the Drupal handbook at
 221 http://drupal.org/handbook. You can view the wide range of other support options
 222 available at http://drupal.org/support.