INSTALL.txt 17.3 KB
Newer Older
1
// $Id$
Dries's avatar
Dries committed
2

Dries's avatar
Dries committed
3 4 5
CONTENTS OF THIS FILE
---------------------

6 7
 * Requirements and notes
 * Optional server requirements
Dries's avatar
Dries committed
8
 * Installation
9
 * Building and customizing your site
10 11
 * Multisite configuration
 * More information
Dries's avatar
Dries committed
12

13 14 15

REQUIREMENTS AND NOTES
----------------------
16

17 18
Drupal requires:

19
- A web server. Apache (version 2.0 or greater) is recommended.
20
- PHP 5.2.4 (or greater) (http://www.php.net/).
21 22 23 24 25 26
- 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.
  - PostgreSQL 8.3 (or greater) (http://www.postgresql.org/).
  - SQLite 3.4.2 (or greater) (http://www.sqlite.org/).
27

28 29
For more detailed information about Drupal requirements, including a list of
PHP extensions and configurations that are required, see "System requirements"
30
(http://drupal.org/requirements) in the Drupal handbook.
31

32 33
For detailed information on how to configure a test server environment using a
variety of operating systems and web servers, see "Local server setup"
34
(http://drupal.org/node/157602) in the Drupal handbook.
35

36 37 38
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).
39 40


41 42 43 44 45 46
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 "Using Clean URLs with IIS"
47
  (http://drupal.org/node/3854) in the Drupal handbook.
48

49 50 51 52
- 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.

53 54 55
- 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.

56 57 58 59 60 61
- 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.
62 63


64 65 66
INSTALLATION
------------

67
1. Download and extract Drupal.
68

69 70
   You can obtain the latest Drupal release from http://drupal.org -- the files
   are in .tar.gz format and can be extracted using most compression tools.
71

72 73
   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):
74

75 76
     wget http://drupal.org/files/projects/drupal-x.y.tar.gz
     tar -zxvf drupal-x.y.tar.gz
77

78 79 80 81 82 83 84 85
   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.
86

87
   By default, Drupal is installed in English, and further languages may be
88 89
   installed later. If you prefer to install Drupal in another language
   initially:
90

91 92
   - Download a translation file for the correct Drupal version and language
     from the translation server: http://localize.drupal.org/download
93 94

   - Rename the downloaded file to your language's ISO code (e.g., de.po or
95 96 97
     fr.po) and place it into your installation profile's translations
     directory. For instance, if you are using the Standard install profile,
     move the .po file into the directory:
98

99
       profiles/standard/translations/
100

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

103
3. Create the Drupal database.
104

105 106 107 108 109 110
   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.
111

112 113
   Take note of the username, password, database name, and hostname as you
   create the database. You will enter this information during the install.
114

115
4. Make the sites/default directory writable.
116

117 118 119 120 121
   During installation, several files and directories need to be created, which
   the installation script can do automatically if the web server has write
   permission on the sites/default directory. If you are creating a multisite
   installation, substitute the correct sites directory for sites/default (see
   the Multisite Configuration section of this file, below).
122

123 124 125
   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:
126

127
      chmod a+w sites/default
128

129 130
   Be sure to set the permissions back after the installation is finished!
   Sample command:
131

132
      chmod go-w sites/default
133

134
5. Run the install script.
135

136 137
   To run the install script point your browser to the base URL of your website
   (e.g., http://www.example.com).
138

139 140 141
   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.
142

143 144 145
   The install script may also tell you that it cannot proceed until you fix
   certain issues with server requirements and files. The most common file
   system issues are with write permissions on directories and files:
146

147
   a. Missing settings.php file.
148

149 150 151 152 153
      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,
      and you followed step 4 above, you can create this file yourself, using
      the file sites/default/default.settings.php as a template.
154

155 156
      For example, on a Unix/Linux command line, you can make a copy of the
      default.settings.php file with the command:
157

158
        cp sites/default/default.settings.php sites/default/settings.php
159

160 161
      Next, grant write privileges to the file to everyone (including the web
      server) with the command:
162

163
        chmod a+w sites/default/settings.php
164

165 166
      Be sure to set the permissions back after the installation is finished!
      Sample command:
167

168
        chmod go-w sites/default/settings.php
169

170
   b. Files directory.
171

172 173 174 175 176 177
      The install script will attempt to create a files 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, and you followed step 4 above, you can create this directory
      yourself. You will also need to grant the web server write permission on
      this directory. Sample commands from a Unix/Linux command line:
178

179 180
        mkdir sites/default/files
        chmod a+w sites/default/files
181

182
   c. Write permissions after install.
183

184 185 186 187
      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:
188

189 190
        chmod go-w sites/default/settings.php
        chmod go-w sites/default
191

192
6. Verify that the site is working.
193

194 195 196 197 198
   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.
199

200
7. Change file system storage settings (optional).
201

202 203 204 205
   The files directory created in step 5 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.
206

207
   It is not necessary to modify this path, but you may wish to change it if:
208

209 210 211
   - 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).
212

213 214 215
   - 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).
216

217
   - You want to restrict access to uploaded files.
218

219 220 221 222 223 224 225 226 227 228 229 230 231 232 233
   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.
234 235 236 237 238

   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.
239

240 241
8. Revoke documentation file permissions (optional).

242 243 244
   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
245 246
   this optional security measure, from a Unix/Linux command line you can use
   the following command:
247

248
     chmod a-r CHANGELOG.txt
249

250 251 252
   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
253 254
   name of each file for CHANGELOG.txt in the example.

255 256 257 258
   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
   online handbook.
259

260
9. Set up independent "cron" maintenance jobs.
261

262 263 264 265 266 267
   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.
268

269 270 271 272
   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.
273

274 275 276 277
   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.
278

279 280 281 282 283
   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.
284

285 286 287
   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:
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 293
   example with the full URL displayed under "Cron maintenance tasks" on the
   "Status report" page.
294

295 296 297 298
   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.)
299

300 301 302

BUILDING AND CUSTOMIZING YOUR SITE
----------------------------------
303

304 305 306 307 308
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
309

310 311 312 313 314 315
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.
316

317 318 319 320 321
Never edit Drupal's core modules and themes; instead, use the hooks available in
the Drupal API. To modify the behavior of Drupal, develope 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
322 323 324 325 326 327 328 329 330


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'
331 332 333 334 335 336 337
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/).
338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367

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
368
addition to those installed in the standard 'modules' and 'themes' directories.
369 370 371 372 373
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:

374 375 376 377
  sites/sub.example.com/
    settings.php
    themes/custom_theme
    modules/custom_module
378 379

NOTE: for more information about multiple virtual hosts or the configuration
380 381 382 383
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 7 above.
384

385

386 387 388
MORE INFORMATION
----------------

389 390
- For additional documentation, see the online Drupal handbook:
  http://drupal.org/handbook
391

392 393 394
- For a list of security announcements, see the "Security announcements" page
  at http://drupal.org/security (available as an RSS feed). This page also
  describes how to subscribe to these announcements via e-mail.
395

396 397 398
- 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
399

400 401 402
- 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.