[Summary view] [Print] [Text view]

   1  // $Id: INSTALL.txt,v 1.61.2.5 2010/12/06 06:50:55 goba Exp $
   2  
   3  CONTENTS OF THIS FILE
   4  ---------------------
   5  
   6   * Requirements
   7   * Optional requirements
   8   * Installation
   9   * Drupal administration
  10   * Customizing your theme(s)
  11   * Multisite Configuration
  12   * More Information
  13  
  14  REQUIREMENTS
  15  ------------
  16  
  17  Drupal requires a web server, PHP 4 (4.3.5 or greater) or PHP 5
  18  (http://www.php.net/) and either MySQL (http://www.mysql.com/) or PostgreSQL
  19  (http://www.postgresql.org/). The Apache web server and MySQL database are
  20  recommended; other web server and database combinations such as IIS and
  21  PostgreSQL have been tested to a lesser extent. When using MySQL, version 4.1.1
  22  or greater is recommended to assure you can safely transfer the database.
  23  
  24  For more detailed information about Drupal requirements, see "Requirements"
  25  (http://drupal.org/requirements) in the Drupal handbook.
  26  
  27  For detailed information on how to configure a test server environment using
  28  a variety of operating systems and web servers, see "Local server setup"
  29  (http://drupal.org/node/157602) in the Drupal handbook.
  30  
  31  OPTIONAL TASKS
  32  --------------
  33  
  34  - To use XML-based services such as the Blogger API and RSS syndication,
  35    you will need PHP's XML extension. This extension is enabled by default.
  36  
  37  - To use Drupal's "Clean URLs" feature on an Apache web server, you will need
  38    the mod_rewrite module and the ability to use local .htaccess files. For
  39    Clean URLs support on IIS, see "Using Clean URLs with IIS"
  40    (http://drupal.org/node/3854) in the Drupal handbook.
  41  
  42  - Various Drupal features require that the web server process (for
  43    example, httpd) be able to initiate outbound connections. This is usually
  44    possible, but some hosting providers or server configurations forbid such
  45    connections. The features that depend on this functionality include the
  46    integrated "Update status" module (which downloads information about
  47    available updates of Drupal core and any installed contributed modules and
  48    themes), the ability to log in via OpenID, fetching aggregator feeds, or
  49    other network-dependent services.
  50  
  51  
  52  INSTALLATION
  53  ------------
  54  
  55  1. DOWNLOAD DRUPAL AND OPTIONALLY A TRANSLATION
  56  
  57     You can obtain the latest Drupal release from http://drupal.org/. The files
  58     are in .tar.gz format and can be extracted using most compression tools. On a
  59     typical Unix command line, use:
  60  
  61       wget http://drupal.org/files/projects/drupal-x.x.tar.gz
  62       tar -zxvf drupal-x.x.tar.gz
  63  
  64     This will create a new directory drupal-x.x/ containing all Drupal files
  65     and directories. Move the contents of that directory into a directory within
  66     your web server's document root or your public HTML directory:
  67  
  68       mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html
  69  
  70     If you would like to have the default English interface translated to a
  71     different language, we have good news. You can install and use Drupal in
  72     other languages from the start. Check whether a released package of the
  73     language desired is available for this Drupal version at
  74     http://localize.drupal.org and download the package. Extract
  75     the contents to the same directory where you extracted Drupal into.
  76  
  77  2. CREATE THE CONFIGURATION FILE AND GRANT WRITE PERMISSIONS
  78  
  79     Drupal comes with a default.settings.php file in the sites/default
  80     directory. The installer uses this file as a template to create your
  81     settings file using the details you provide through the install process.
  82     To avoid problems when upgrading, Drupal is not packaged with an actual
  83     settings file. You must create a file named settings.php. You may do so
  84     by making a copy of default.settings.php (or create an empty file with
  85     this name in the same directory). For example, (from the installation
  86     directory) make a copy of the default.settings.php file with the command:
  87  
  88       cp sites/default/default.settings.php sites/default/settings.php
  89  
  90     Next, give the web server write privileges to the sites/default/settings.php
  91     file with the command (from the installation directory):
  92  
  93       chmod o+w sites/default/settings.php
  94  
  95    So that the files directory can be created automatically, give the web server
  96    write privileges to the sites/default directory with the command (from the
  97    installation directory):
  98  
  99       chmod o+w sites/default
 100  
 101  3. CREATE THE DRUPAL DATABASE
 102  
 103     Drupal requires access to a database in order to be installed. Your database
 104     user will need sufficient privileges to run Drupal. Additional information
 105     about privileges, and instructions to create a database using the command
 106     line are available in INSTALL.mysql.txt (for MySQL) or INSTALL.pgsql.txt
 107     (for PostgreSQL).
 108  
 109     To create a database using PHPMyAdmin or a web-based control panel consult
 110     the documentation or ask your webhost service provider.
 111  
 112     Take note of the username, password, database name and hostname as you
 113     create the database. You will enter these items in the install script.
 114  
 115  4. RUN THE INSTALL SCRIPT
 116  
 117     To run the install script point your browser to the base URL of your website
 118     (e.g., http://www.example.com).
 119  
 120     You will be guided through several screens to set up the database,
 121     create tables, add the first user account and provide basic web
 122     site settings.
 123  
 124     The install script will attempt to create a files storage directory
 125     in the default location at sites/default/files (the location of the
 126     files directory may be changed after Drupal is installed). In some
 127     cases, you may need to create the directory and modify its permissions
 128     manually. Use the following commands (from the installation directory)
 129     to create the files directory and grant the web server write privileges to it:
 130  
 131       mkdir sites/default/files
 132       chmod o+w sites/default/files
 133  
 134     The install script will attempt to write-protect the settings.php file and
 135     the sites/default directory after saving your configuration. However, you
 136     may need to manually write-protect them using the commands (from the
 137     installation directory):
 138  
 139       chmod a-w sites/default/settings.php
 140       chmod a-w sites/default
 141  
 142     If you make manual changes to the file later, be sure to protect it again
 143     after making your modifications. Failure to remove write permissions to that
 144     file is a security risk. Although the default location for the settings.php
 145     file is at sites/default/settings.php, it may be in another location
 146     if you use the multi-site setup, as explained below.
 147  
 148  5. CONFIGURE DRUPAL
 149  
 150     When the install script succeeds, you will be directed to the "Welcome"
 151     page, and you will be logged in as the administrator already. Proceed with
 152     the initial configuration steps suggested on the "Welcome" page.
 153  
 154     If the default Drupal theme is not displaying properly and links on the page
 155     result in "Page Not Found" errors, try manually setting the $base_url variable
 156     in the settings.php file if not already set. It's currently known that servers
 157     running FastCGI can run into problems if the $base_url variable is left
 158     commented out (see http://bugs.php.net/bug.php?id=19656).
 159  
 160  6. REVIEW FILE SYSTEM STORAGE SETTINGS AND FILE PERMISSIONS
 161  
 162     The files directory created in step 4 is the default file system path used
 163     to store all uploaded files, as well as some temporary files created by Drupal.
 164     After installation, the settings for the file system path may be modified
 165     to store uploaded files in a different location.
 166  
 167     It is not necessary to modify this path, but you may wish to change it if:
 168  
 169       * your site runs multiple Drupal installations from a single codebase
 170         (modify the file system path of each installation to a different
 171         directory so that uploads do not overlap between installations); or,
 172  
 173       * your site runs a number of web server front-ends behind a load
 174         balancer or reverse proxy (modify the file system path on each
 175         server to point to a shared file repository).
 176  
 177     To modify the file system path:
 178  
 179       * Ensure that the new location for the path exists or create it if
 180         necessary. To create a new directory named uploads, for example,
 181         use the following command from a shell or system prompt (while in
 182         the installation directory):
 183  
 184             mkdir uploads
 185  
 186       * Ensure that the new location for the path is writable by the web
 187         server process. To grant write permissions for a directory named
 188         uploads, you may need to use the following command from a shell
 189         or system prompt (while in the installation directory):
 190  
 191             chmod o+w uploads
 192  
 193       * Access the file system path settings in Drupal by selecting these
 194         menu items from the Navigation menu:
 195  
 196             Administer > Site configuration > File system
 197  
 198         Enter the path to the new location (e.g.: uploads) at the File
 199         System Path prompt.
 200  
 201     Changing the file system path after files have been uploaded may cause
 202     unexpected problems on an existing site. If you modify the file system path
 203     on an existing site, remember to copy all files from the original location
 204     to the new location.
 205  
 206     Some administrators suggest making the documentation files, especially
 207     CHANGELOG.txt, non-readable so that the exact version of Drupal you are
 208     running is slightly more difficult to determine. If you wish to implement
 209     this optional security measure, use the following command from a shell or
 210     system prompt (while in the installation directory):
 211  
 212            chmod a-r CHANGELOG.txt
 213  
 214     Note that the example only affects CHANGELOG.txt. To completely hide
 215     all documentation files from public view, repeat this command for each of
 216     the Drupal documentation files in the installation directory, substituting the
 217     name of each file for CHANGELOG.txt in the example.
 218  
 219     For more information on setting file permissions, see "Modifying Linux, Unix,
 220     and Mac file permissions" (http://drupal.org/node/202483) or "Modifying
 221     Windows file permissions" (http://drupal.org/node/202491) in the online
 222     handbook.
 223  
 224  7. CRON MAINTENANCE TASKS
 225  
 226     Many Drupal modules have periodic tasks that must be triggered by a cron
 227     maintenance task, including search module (to build and update the index
 228     used for keyword searching), aggregator module (to retrieve feeds from other
 229     sites), ping module (to notify other sites about new or updated content), and
 230     system module (to perform routine maintenance and pruning on system tables).
 231     To activate these tasks, call the cron page by visiting
 232     http://www.example.com/cron.php, which, in turn, executes tasks on behalf
 233     of installed modules.
 234  
 235     Most systems support the crontab utility for scheduling tasks like this. The
 236     following example crontab line will activate the cron tasks automatically on
 237     the hour:
 238  
 239     0   *   *   *   *   wget -O - -q -t 1 http://www.example.com/cron.php
 240  
 241     More information about cron maintenance tasks are available in the help pages
 242     and in Drupal's online handbook at http://drupal.org/cron. Example scripts can
 243     be found in the scripts/ directory.
 244  
 245  DRUPAL ADMINISTRATION
 246  ---------------------
 247  
 248  A new installation of Drupal defaults to a very basic configuration with only a
 249  few active modules and minimal user access rights.
 250  
 251  Use your administration panel to enable and configure services. For example:
 252  
 253  General Settings       Administer > Site configuration > Site information
 254  Enable Modules         Administer > Site building > Modules
 255  Configure Themes       Administer > Site building > Themes
 256  Set User Permissions   Administer > User management > Permissions
 257  
 258  For more information on configuration options, read the instructions which
 259  accompany the different configuration settings and consult the various help
 260  pages available in the administration panel.
 261  
 262  Community-contributed modules and themes are available at http://drupal.org/.
 263  
 264  CUSTOMIZING YOUR THEME(S)
 265  -------------------------
 266  
 267  Now that your installation is running, you will want to customize the look of
 268  your site. Several sample themes are included and more can be downloaded from
 269  drupal.org.
 270  
 271  Simple customization of your theme can be done using only CSS. Further changes
 272  require understanding the phptemplate engine that is part of Drupal. See
 273  http://drupal.org/handbook/customization to find out more.
 274  
 275  MULTISITE CONFIGURATION
 276  -----------------------
 277  
 278  A single Drupal installation can host several Drupal-powered sites, each with
 279  its own individual configuration.
 280  
 281  Additional site configurations are created in subdirectories within the 'sites'
 282  directory. Each subdirectory must have a 'settings.php' file which specifies the
 283  configuration settings. The easiest way to create additional sites is to copy
 284  the 'default' directory and modify the 'settings.php' file as appropriate. The
 285  new directory name is constructed from the site's URL. The configuration for
 286  www.example.com could be in 'sites/example.com/settings.php' (note that 'www.'
 287  should be omitted if users can access your site at http://example.com/).
 288  
 289  Sites do not have to have a different domain. You can also use subdomains and
 290  subdirectories for Drupal sites. For example, example.com, sub.example.com,
 291  and sub.example.com/site3 can all be defined as independent Drupal sites. The
 292  setup for a configuration such as this would look like the following:
 293  
 294    sites/default/settings.php
 295    sites/example.com/settings.php
 296    sites/sub.example.com/settings.php
 297    sites/sub.example.com.site3/settings.php
 298  
 299  When searching for a site configuration (for example www.sub.example.com/site3),
 300  Drupal will search for configuration files in the following order, using the
 301  first configuration it finds:
 302  
 303    sites/www.sub.example.com.site3/settings.php
 304    sites/sub.example.com.site3/settings.php
 305    sites/example.com.site3/settings.php
 306    sites/www.sub.example.com/settings.php
 307    sites/sub.example.com/settings.php
 308    sites/example.com/settings.php
 309    sites/default/settings.php
 310  
 311  If you are installing on a non-standard port, the port number is treated as the
 312  deepest subdomain. For example: http://www.example.com:8080/ could be loaded
 313  from sites/8080.www.example.com/. The port number will be removed according to
 314  the pattern above if no port-specific configuration is found, just like a real
 315  subdomain.
 316  
 317  Each site configuration can have its own site-specific modules and themes in
 318  addition to those installed in the standard 'modules' and 'themes' directories.
 319  To use site-specific modules or themes, simply create a 'modules' or 'themes'
 320  directory within the site configuration directory. For example, if
 321  sub.example.com has a custom theme and a custom module that should not be
 322  accessible to other sites, the setup would look like this:
 323  
 324    sites/sub.example.com/:
 325    settings.php
 326    themes/custom_theme
 327    modules/custom_module
 328  
 329  NOTE: for more information about multiple virtual hosts or the configuration
 330  settings, consult the Drupal handbook at drupal.org.
 331  
 332  For more information on configuring Drupal's file system path in a multi-site
 333  configuration, see step 6 above.
 334  
 335  MORE INFORMATION
 336  ----------------
 337  
 338  - For additional documentation, see the online Drupal handbook at
 339    http://drupal.org/handbook.
 340  
 341  - For a list of security announcements, see the "Security announcements" page
 342    at http://drupal.org/security (available as an RSS feed). This page also
 343    describes how to subscribe to these announcements via e-mail.
 344  
 345  - For information about the Drupal security process, or to find out how to report
 346    a potential security issue to the Drupal security team, see the "Security team"
 347    page at http://drupal.org/security-team.
 348  
 349  - For information about the wide range of available support options, see the
 350    "Support" page at http://drupal.org/support.