INSTALL.txt

   1
   2 CONTENTS OF THIS FILE
   3 ---------------------
   4
   5  * Requirements and notes
   6  * Optional server requirements
   7  * Installation
   8  * Building and customizing your site
   9  * Multisite configuration
  10  * More information
  11
  12 REQUIREMENTS AND NOTES
  13 ----------------------
  14
  15 Drupal requires:
  16
  17 - A web server. Apache (version 2.0 or greater) is recommended.
  18 - PHP 5.2.4 (or greater) (http://www.php.net/).
  19 - One of the following databases:
  20   - MySQL 5.0.15 (or greater) (http://www.mysql.com/).
  21   - MariaDB 5.1.44 (or greater) (http://mariadb.org/). MariaDB is a fully
  22     compatible drop-in replacement for MySQL.
  23   - PostgreSQL 8.3 (or greater) (http://www.postgresql.org/).
  24   - SQLite 3.4.2 (or greater) (http://www.sqlite.org/).
  25
  26 For more detailed information about Drupal requirements, including a list of
  27 PHP extensions and configurations that are required, see "System requirements"
  28 (http://drupal.org/requirements) in the Drupal.org online documentation.
  29
  30 For detailed information on how to configure a test server environment using a
  31 variety of operating systems and web servers, see "Local server setup"
  32 (http://drupal.org/node/157602) in the Drupal.org online documentation.
  33
  34 Note that all directories mentioned in this document are always relative to the
  35 directory of your Drupal installation, and commands are meant to be run from
  36 this directory (except for the initial commands that create that directory).
  37
  38 OPTIONAL SERVER REQUIREMENTS
  39 ----------------------------
  40
  41 - If you want to use Drupal's "Clean URLs" feature on an Apache web server, you
  42   will need the mod_rewrite module and the ability to use local .htaccess
  43   files. For Clean URLs support on IIS, see "Clean URLs with IIS"
  44   (http://drupal.org/node/3854) in the Drupal.org online documentation.
  45
  46 - If you plan to use XML-based services such as RSS aggregation, you will need
  47   PHP's XML extension. This extension is enabled by default on most PHP
  48   installations.
  49
  50 - To serve gzip compressed CSS and JS files on an Apache web server, you will
  51   need the mod_headers module and the ability to use local .htaccess files.
  52
  53 - Some Drupal functionality (e.g., checking whether Drupal and contributed
  54   modules need updates, RSS aggregation, etc.) require that the web server be
  55   able to go out to the web and download information. If you want to use this
  56   functionality, you need to verify that your hosting provider or server
  57   configuration allows the web server to initiate outbound connections. Most web
  58   hosting setups allow this.
  59
  60 INSTALLATION
  61 ------------
  62
  63 1. Download and extract Drupal.
  64
  65    You can obtain the latest Drupal release from http://drupal.org -- the files
  66    are available in .tar.gz and .zip formats and can be extracted using most
  67    compression tools.
  68
  69    To download and extract the files, on a typical Unix/Linux command line, use
  70    the following commands (assuming you want version x.y of Drupal in .tar.gz
  71    format):
  72
  73      wget http://drupal.org/files/projects/drupal-x.y.tar.gz
  74      tar -zxvf drupal-x.y.tar.gz
  75
  76    This will create a new directory drupal-x.y/ containing all Drupal files and
  77    directories. Then, to move the contents of that directory into a directory
  78    within your web server's document root or your public HTML directory,
  79    continue with this command:
  80
  81      mv drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation
  82
  83 2. Optionally, download a translation.
  84
  85    By default, Drupal is installed in English, and further languages may be
  86    installed later. If you prefer to install Drupal in another language
  87    initially:
  88
  89    - Download a translation file for the correct Drupal version and language
  90      from the translation server: http://localize.drupal.org/translate/downloads
  91
  92    - Place the file into your installation profile's translations
  93      directory. For instance, if you are using the Standard install profile,
  94      move the .po file into the directory:
  95
  96        profiles/standard/translations/
  97
  98    For detailed instructions, visit http://drupal.org/localize
  99
 100 3. Create the Drupal database.
 101
 102    Because Drupal stores all site information in a database, you must create
 103    this database in order to install Drupal, and grant Drupal certain database
 104    privileges (such as the ability to create tables). For details, consult
 105    INSTALL.mysql.txt, INSTALL.pgsql.txt, or INSTALL.sqlite.txt. You may also
 106    need to consult your web hosting provider for instructions specific to your
 107    web host.
 108
 109    Take note of the username, password, database name, and hostname as you
 110    create the database. You will enter this information during the install.
 111
 112 4. Run the install script.
 113
 114    To run the install script, point your browser to the base URL of your
 115    website (e.g., http://www.example.com).
 116
 117    You will be guided through several screens to set up the database, add the
 118    site maintenance account (the first user, also known as user/1), and provide
 119    basic web site settings.
 120
 121    During installation, several files and directories need to be created, which
 122    the install script will try to do automatically. However, on some hosting
 123    environments, manual steps are required, and the install script will tell
 124    you that it cannot proceed until you fix certain issues. This is normal and
 125    does not indicate a problem with your server.
 126
 127    The most common steps you may need to perform are:
 128
 129    a. Missing files directory.
 130
 131       The install script will attempt to create a file storage directory in
 132       the default location at sites/default/files (the location of the files
 133       directory may be changed after Drupal is installed).
 134
 135       If auto-creation fails, you can make it work by changing permissions on
 136       the sites/default directory so that the web server can create the files
 137       directory within it for you. (If you are creating a multisite
 138       installation, substitute the correct sites directory for sites/default;
 139       see the Multisite Configuration section of this file, below.)
 140
 141       For example, on a Unix/Linux command line, you can grant everyone
 142       (including the web server) permission to write to the sites/default
 143       directory with this command:
 144
 145         chmod a+w sites/default
 146
 147       Be sure to set the permissions back after the installation is finished!
 148       Sample command:
 149
 150         chmod go-w sites/default
 151
 152       Alternatively, instead of allowing the web server to create the files
 153       directory for you as described above, you can create it yourself. Sample
 154       commands from a Unix/Linux command line:
 155
 156         mkdir sites/default/files
 157         chmod a+w sites/default/files
 158
 159    b. Missing settings file.
 160
 161       Drupal will try to automatically create a settings.php configuration file,
 162       which is normally in the directory sites/default (to avoid problems when
 163       upgrading, Drupal is not packaged with this file). If auto-creation fails,
 164       you will need to create this file yourself, using the file
 165       sites/default/default.settings.php as a template.
 166
 167       For example, on a Unix/Linux command line, you can make a copy of the
 168       default.settings.php file with the command:
 169
 170         cp sites/default/default.settings.php sites/default/settings.php
 171
 172       Next, grant write privileges to the file to everyone (including the web
 173       server) with the command:
 174
 175         chmod a+w sites/default/settings.php
 176
 177       Be sure to set the permissions back after the installation is finished!
 178       Sample command:
 179
 180         chmod go-w sites/default/settings.php
 181
 182    c. Write permissions after install.
 183
 184       The install script will attempt to write-protect the settings.php file and
 185       the sites/default directory after saving your configuration. If this
 186       fails, you will be notified, and you can do it manually. Sample commands
 187       from a Unix/Linux command line:
 188
 189         chmod go-w sites/default/settings.php
 190         chmod go-w sites/default
 191
 192 5. Verify that the site is working.
 193
 194    When the install script finishes, you will be logged in with the site
 195    maintenance account on a "Welcome" page. If the default Drupal theme is not
 196    displaying properly and links on the page result in "Page Not Found" errors,
 197    you may be experiencing problems with clean URLs. Visit
 198    http://drupal.org/getting-started/clean-urls to troubleshoot.
 199
 200 6. Change file system storage settings (optional).
 201
 202    The files directory created in step 4 is the default file system path used to
 203    store all uploaded files, as well as some temporary files created by
 204    Drupal. After installation, you can modify the file system path to store
 205    uploaded files in a different location.
 206
 207    It is not necessary to modify this path, but you may wish to change it if:
 208
 209    - Your site runs multiple Drupal installations from a single codebase (modify
 210      the file system path of each installation to a different directory so that
 211      uploads do not overlap between installations).
 212
 213    - Your site runs on a number of web servers behind a load balancer or reverse
 214      proxy (modify the file system path on each server to point to a shared file
 215      repository).
 216
 217    - You want to restrict access to uploaded files.
 218
 219    To modify the file system path:
 220
 221    a. Ensure that the new location for the path exists and is writable by the
 222       web server. For example, to create a new directory named uploads and grant
 223       write permissions, use the following commands on a Unix/Linux command
 224       line:
 225
 226         mkdir uploads
 227         chmod a+w uploads
 228
 229    b. Navigate to Administration > Configuration > Media > File system, and
 230       enter the desired path. Note that if you want to use private file storage,
 231       you need to first enter the path for private files and save the
 232       configuration, and then change the "Default download method" setting and
 233       save again.
 234
 235    Changing the file system path after files have been uploaded may cause
 236    unexpected problems on an existing site. If you modify the file system path
 237    on an existing site, remember to copy all files from the original location
 238    to the new location.
 239
 240 7. Revoke documentation file permissions (optional).
 241
 242    Some administrators suggest making the documentation files, especially
 243    CHANGELOG.txt, non-readable so that the exact version of Drupal you are
 244    running is slightly more difficult to determine. If you wish to implement
 245    this optional security measure, from a Unix/Linux command line you can use
 246    the following command:
 247
 248      chmod a-r CHANGELOG.txt
 249
 250    Note that the example only affects CHANGELOG.txt. To completely hide all
 251    documentation files from public view, repeat this command for each of the
 252    Drupal documentation files in the installation directory, substituting the
 253    name of each file for CHANGELOG.txt in the example.
 254
 255    For more information on setting file permissions, see "Modifying Linux,
 256    Unix, and Mac file permissions" (http://drupal.org/node/202483) or
 257    "Modifying Windows file permissions" (http://drupal.org/node/202491) in the
 258    Drupal.org online documentation.
 259
 260 8. Set up independent "cron" maintenance jobs.
 261
 262    Many Drupal modules have tasks that must be run periodically, including the
 263    Search module (building and updating the index used for keyword searching),
 264    the Aggregator module (retrieving feeds from other sites), and the System
 265    module (performing routine maintenance and pruning of database tables). These
 266    tasks are known as "cron maintenance tasks", named after the Unix/Linux
 267    "cron" utility.
 268
 269    When you install Drupal, its built-in cron feature is enabled, which
 270    automatically runs the cron tasks periodically, triggered by people visiting
 271    pages of your site. You can configure the built-in cron feature by navigating
 272    to Administration > Configuration > System > Cron.
 273
 274    It is also possible to run the cron tasks independent of site visits; this is
 275    recommended for most sites. To do this, you will need to set up an automated
 276    process to visit the page cron.php on your site, which executes the cron
 277    tasks.
 278
 279    The URL of the cron.php page requires a "cron key" to protect against
 280    unauthorized access. Your site's cron key is automatically generated during
 281    installation and is specific to your site. The full URL of the page, with the
 282    cron key, is available in the "Cron maintenance tasks" section of the Status
 283    report page at Administration > Reports > Status report.
 284
 285    As an example for how to set up this automated process, you can use the
 286    crontab utility on Unix/Linux systems. The following crontab line uses the
 287    wget command to visit the cron.php page, and runs each hour, on the hour:
 288
 289    0 * * * * wget -O - -q -t 1 http://example.com/cron.php?cron_key=YOURKEY
 290
 291    Replace the text "http://example.com/cron.php?cron_key=YOURKEY" in the
 292    example with the full URL displayed under "Cron maintenance tasks" on the
 293    "Status report" page.
 294
 295    More information about cron maintenance tasks is available at
 296    http://drupal.org/cron, and sample cron shell scripts can be found in the
 297    scripts/ directory. (Note that these scripts must be customized like the
 298    above example, to add your site-specific cron key and domain name.)
 299
 300 BUILDING AND CUSTOMIZING YOUR SITE
 301 ----------------------------------
 302
 303 A new installation of Drupal defaults to a very basic configuration. To extend
 304 your site, you use "modules" and "themes". A module is a plugin that adds
 305 functionality to Drupal, while a theme changes the look of your site. The core
 306 of Drupal provides several optional modules and themes, and you can download
 307 more at http://drupal.org/project/modules and http://drupal.org/project/themes
 308
 309 Do not mix downloaded or custom modules and themes with Drupal's core modules
 310 and themes. Drupal's modules and themes are located in the top-level modules and
 311 themes directories, while the modules and themes you add to Drupal are normally
 312 placed in the sites/all/modules and sites/all/themes directories. If you run a
 313 multisite installation, you can also place modules and themes in the
 314 site-specific directories -- see the Multisite Configuration section, below.
 315
 316 Never edit Drupal's core modules and themes; instead, use the hooks available in
 317 the Drupal API. To modify the behavior of Drupal, develop a module as described
 318 at http://drupal.org/developing/modules. To modify the look of Drupal, create a
 319 subtheme as described at http://drupal.org/node/225125, or a completely new
 320 theme as described at http://drupal.org/documentation/theme
 321
 322 MULTISITE CONFIGURATION
 323 -----------------------
 324
 325 A single Drupal installation can host several Drupal-powered sites, each with
 326 its own individual configuration.
 327
 328 Additional site configurations are created in subdirectories within the 'sites'
 329 directory. Each subdirectory must have a 'settings.php' file, which specifies
 330 the configuration settings. The easiest way to create additional sites is to
 331 copy the 'default' directory and modify the 'settings.php' file as appropriate.
 332 The new directory name is constructed from the site's URL. The configuration for
 333 www.example.com could be in 'sites/example.com/settings.php' (note that 'www.'
 334 should be omitted if users can access your site at http://example.com/).
 335
 336 Sites do not have to have a different domain. You can also use subdomains and
 337 subdirectories for Drupal sites. For example, example.com, sub.example.com, and
 338 sub.example.com/site3 can all be defined as independent Drupal sites. The setup
 339 for a configuration such as this would look like the following:
 340
 341   sites/default/settings.php
 342   sites/example.com/settings.php
 343   sites/sub.example.com/settings.php
 344   sites/sub.example.com.site3/settings.php
 345
 346 When searching for a site configuration (for example www.sub.example.com/site3),
 347 Drupal will search for configuration files in the following order, using the
 348 first configuration it finds:
 349
 350   sites/www.sub.example.com.site3/settings.php
 351   sites/sub.example.com.site3/settings.php
 352   sites/example.com.site3/settings.php
 353   sites/www.sub.example.com/settings.php
 354   sites/sub.example.com/settings.php
 355   sites/example.com/settings.php
 356   sites/default/settings.php
 357
 358 If you are installing on a non-standard port, the port number is treated as the
 359 deepest subdomain. For example: http://www.example.com:8080/ could be loaded
 360 from sites/8080.www.example.com/. The port number will be removed according to
 361 the pattern above if no port-specific configuration is found, just like a real
 362 subdomain.
 363
 364 Each site configuration can have its own site-specific modules and themes in
 365 addition to those installed in the standard 'modules' and 'themes' directories.
 366 To use site-specific modules or themes, simply create a 'modules' or 'themes'
 367 directory within the site configuration directory. For example, if
 368 sub.example.com has a custom theme and a custom module that should not be
 369 accessible to other sites, the setup would look like this:
 370
 371   sites/sub.example.com/
 372     settings.php
 373     themes/custom_theme
 374     modules/custom_module
 375
 376 NOTE: for more information about multiple virtual hosts or the configuration
 377 settings, consult http://drupal.org/getting-started/6/install/multi-site
 378
 379 For more information on configuring Drupal's file system path in a multisite
 380 configuration, see step 6 above.
 381
 382 MORE INFORMATION
 383 ----------------
 384
 385 - See the Drupal.org online documentation:
 386   http://drupal.org/documentation
 387
 388 - For a list of security announcements, see the "Security advisories" page at
 389   http://drupal.org/security (available as an RSS feed). This page also
 390   describes how to subscribe to these announcements via e-mail.
 391
 392 - For information about the Drupal security process, or to find out how to
 393   report a potential security issue to the Drupal security team, see the
 394   "Security team" page at http://drupal.org/security-team
 395
 396 - For information about the wide range of available support options, visit
 397   http://drupal.org and click on Community and Support in the top or bottom
 398   navigation.