Project

General

Profile

Paste
Download (17.6 KB) Statistics
| Branch: | Revision:

root / drupal7 / INSTALL.txt @ f581c0a8

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
  - Percona Server 5.1.70 (or greater) (http://www.percona.com/). Percona
24
    Server is a backwards-compatible replacement for MySQL.
25
  - PostgreSQL 8.3 (or greater) (http://www.postgresql.org/).
26
  - SQLite 3.3.7 (or greater) (http://www.sqlite.org/).
27

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

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

    
36
Note that all directories mentioned in this document are always relative to the
37
directory of your Drupal installation, and commands are meant to be run from
38
this directory (except for the initial commands that create that directory).
39

    
40
OPTIONAL SERVER REQUIREMENTS
41
----------------------------
42

    
43
- If you want to use Drupal's "Clean URLs" feature on an Apache web server, you
44
  will need the mod_rewrite module and the ability to use local .htaccess
45
  files. For Clean URLs support on IIS, see "Clean URLs with IIS"
46
  (http://drupal.org/node/3854) in the Drupal.org online documentation.
47

    
48
- If you plan to use XML-based services such as RSS aggregation, you will need
49
  PHP's XML extension. This extension is enabled by default on most PHP
50
  installations.
51

    
52
- To serve gzip compressed CSS and JS files on an Apache web server, you will
53
  need the mod_headers module and the ability to use local .htaccess files.
54

    
55
- Some Drupal functionality (e.g., checking whether Drupal and contributed
56
  modules need updates, RSS aggregation, etc.) require that the web server be
57
  able to go out to the web and download information. If you want to use this
58
  functionality, you need to verify that your hosting provider or server
59
  configuration allows the web server to initiate outbound connections. Most web
60
  hosting setups allow this.
61

    
62
INSTALLATION
63
------------
64

    
65
1. Download and extract Drupal.
66

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

    
71
   To download and extract the files, on a typical Unix/Linux command line, use
72
   the following commands (assuming you want version x.y of Drupal in .tar.gz
73
   format):
74

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

    
78
   This will create a new directory drupal-x.y/ containing all Drupal files and
79
   directories. Then, to move the contents of that directory into a directory
80
   within your web server's document root or your public HTML directory,
81
   continue with this command:
82

    
83
     mv drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation
84

    
85
2. Optionally, download a translation.
86

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

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

    
94
   - Place the file into your installation profile's translations directory.
95
     For instance, if you are using the Standard installation profile,
96
     move the .po file into the directory:
97

    
98
       profiles/standard/translations/
99

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

    
102
3. Create the Drupal database.
103

    
104
   Because Drupal stores all site information in a database, you must create
105
   this database in order to install Drupal, and grant Drupal certain database
106
   privileges (such as the ability to create tables). For details, consult
107
   INSTALL.mysql.txt, INSTALL.pgsql.txt, or INSTALL.sqlite.txt. You may also
108
   need to consult your web hosting provider for instructions specific to your
109
   web host.
110

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

    
114
4. Run the install script.
115

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

    
119
   You will be guided through several screens to set up the database, add the
120
   site maintenance account (the first user, also known as user/1), and provide
121
   basic web site settings.
122

    
123
   During installation, several files and directories need to be created, which
124
   the install script will try to do automatically. However, on some hosting
125
   environments, manual steps are required, and the install script will tell
126
   you that it cannot proceed until you fix certain issues. This is normal and
127
   does not indicate a problem with your server.
128

    
129
   The most common steps you may need to perform are:
130

    
131
   a. Missing files directory.
132

    
133
      The install script will attempt to create a file storage directory in
134
      the default location at sites/default/files (the location of the files
135
      directory may be changed after Drupal is installed).
136

    
137
      If auto-creation fails, you can make it work by changing permissions on
138
      the sites/default directory so that the web server can create the files
139
      directory within it for you. (If you are creating a multisite
140
      installation, substitute the correct sites directory for sites/default;
141
      see the Multisite Configuration section of this file, below.)
142

    
143
      For example, on a Unix/Linux command line, you can grant everyone
144
      (including the web server) permission to write to the sites/default
145
      directory with this command:
146

    
147
        chmod a+w sites/default
148

    
149
      Be sure to set the permissions back after the installation is finished!
150
      Sample command:
151

    
152
        chmod go-w sites/default
153

    
154
      Alternatively, instead of allowing the web server to create the files
155
      directory for you as described above, you can create it yourself. Sample
156
      commands from a Unix/Linux command line:
157

    
158
        mkdir sites/default/files
159
        chmod a+w sites/default/files
160

    
161
   b. Missing settings file.
162

    
163
      Drupal will try to automatically create a settings.php configuration file,
164
      which is normally in the directory sites/default (to avoid problems when
165
      upgrading, Drupal is not packaged with this file). If auto-creation fails,
166
      you will need to create this file yourself, using the file
167
      sites/default/default.settings.php as a template.
168

    
169
      For example, on a Unix/Linux command line, you can make a copy of the
170
      default.settings.php file with the command:
171

    
172
        cp sites/default/default.settings.php sites/default/settings.php
173

    
174
      Next, grant write privileges to the file to everyone (including the web
175
      server) with the command:
176

    
177
        chmod a+w sites/default/settings.php
178

    
179
      Be sure to set the permissions back after the installation is finished!
180
      Sample command:
181

    
182
        chmod go-w sites/default/settings.php
183

    
184
   c. Write permissions after install.
185

    
186
      The install script will attempt to write-protect the settings.php file and
187
      the sites/default directory after saving your configuration. If this
188
      fails, you will be notified, and you can do it manually. Sample commands
189
      from a Unix/Linux command line:
190

    
191
        chmod go-w sites/default/settings.php
192
        chmod go-w sites/default
193

    
194
5. Verify that the site is working.
195

    
196
   When the install script finishes, you will be logged in with the site
197
   maintenance account on a "Welcome" page. If the default Drupal theme is not
198
   displaying properly and links on the page result in "Page Not Found" errors,
199
   you may be experiencing problems with clean URLs. Visit
200
   http://drupal.org/getting-started/clean-urls to troubleshoot.
201

    
202
6. Change file system storage settings (optional).
203

    
204
   The files directory created in step 4 is the default file system path used to
205
   store all uploaded files, as well as some temporary files created by
206
   Drupal. After installation, you can modify the file system path to store
207
   uploaded files in a different location.
208

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

    
211
   - Your site runs multiple Drupal installations from a single codebase (modify
212
     the file system path of each installation to a different directory so that
213
     uploads do not overlap between installations).
214

    
215
   - Your site runs on a number of web servers behind a load balancer or reverse
216
     proxy (modify the file system path on each server to point to a shared file
217
     repository).
218

    
219
   - You want to restrict access to uploaded files.
220

    
221
   To modify the file system path:
222

    
223
   a. Ensure that the new location for the path exists and is writable by the
224
      web server. For example, to create a new directory named uploads and grant
225
      write permissions, use the following commands on a Unix/Linux command
226
      line:
227

    
228
        mkdir uploads
229
        chmod a+w uploads
230

    
231
   b. Navigate to Administration > Configuration > Media > File system, and
232
      enter the desired path. Note that if you want to use private file storage,
233
      you need to first enter the path for private files and save the
234
      configuration, and then change the "Default download method" setting and
235
      save again.
236

    
237
   Changing the file system path after files have been uploaded may cause
238
   unexpected problems on an existing site. If you modify the file system path
239
   on an existing site, remember to copy all files from the original location
240
   to the new location.
241

    
242
7. Revoke documentation file permissions (optional).
243

    
244
   Some administrators suggest making the documentation files, especially
245
   CHANGELOG.txt, non-readable so that the exact version of Drupal you are
246
   running is slightly more difficult to determine. If you wish to implement
247
   this optional security measure, from a Unix/Linux command line you can use
248
   the following command:
249

    
250
     chmod a-r CHANGELOG.txt
251

    
252
   Note that the example only affects CHANGELOG.txt. To completely hide all
253
   documentation files from public view, repeat this command for each of the
254
   Drupal documentation files in the installation directory, substituting the
255
   name of each file for CHANGELOG.txt in the example.
256

    
257
   For more information on setting file permissions, see "Modifying Linux,
258
   Unix, and Mac file permissions" (http://drupal.org/node/202483) or
259
   "Modifying Windows file permissions" (http://drupal.org/node/202491) in the
260
   Drupal.org online documentation.
261

    
262
8. Set up independent "cron" maintenance jobs.
263

    
264
   Many Drupal modules have tasks that must be run periodically, including the
265
   Search module (building and updating the index used for keyword searching),
266
   the Aggregator module (retrieving feeds from other sites), and the System
267
   module (performing routine maintenance and pruning of database tables). These
268
   tasks are known as "cron maintenance tasks", named after the Unix/Linux
269
   "cron" utility.
270

    
271
   When you install Drupal, its built-in cron feature is enabled, which
272
   automatically runs the cron tasks periodically, triggered by people visiting
273
   pages of your site. You can configure the built-in cron feature by navigating
274
   to Administration > Configuration > System > Cron.
275

    
276
   It is also possible to run the cron tasks independent of site visits; this is
277
   recommended for most sites. To do this, you will need to set up an automated
278
   process to visit the page cron.php on your site, which executes the cron
279
   tasks.
280

    
281
   The URL of the cron.php page requires a "cron key" to protect against
282
   unauthorized access. Your site's cron key is automatically generated during
283
   installation and is specific to your site. The full URL of the page, with the
284
   cron key, is available in the "Cron maintenance tasks" section of the Status
285
   report page at Administration > Reports > Status report.
286

    
287
   As an example for how to set up this automated process, you can use the
288
   crontab utility on Unix/Linux systems. The following crontab line uses the
289
   wget command to visit the cron.php page, and runs each hour, on the hour:
290

    
291
   0 * * * * wget -O - -q -t 1 http://example.com/cron.php?cron_key=YOURKEY
292

    
293
   Replace the text "http://example.com/cron.php?cron_key=YOURKEY" in the
294
   example with the full URL displayed under "Cron maintenance tasks" on the
295
   "Status report" page.
296

    
297
   More information about cron maintenance tasks is available at
298
   http://drupal.org/cron, and sample cron shell scripts can be found in the
299
   scripts/ directory. (Note that these scripts must be customized like the
300
   above example, to add your site-specific cron key and domain name.)
301

    
302
BUILDING AND CUSTOMIZING YOUR SITE
303
----------------------------------
304

    
305
A new installation of Drupal defaults to a very basic configuration. To extend
306
your site, you use "modules" and "themes". A module is a plugin that adds
307
functionality to Drupal, while a theme changes the look of your site. The core
308
of Drupal provides several optional modules and themes, and you can download
309
more at http://drupal.org/project/modules and http://drupal.org/project/themes
310

    
311
Do not mix downloaded or custom modules and themes with Drupal's core modules
312
and themes. Drupal's modules and themes are located in the top-level modules and
313
themes directories, while the modules and themes you add to Drupal are normally
314
placed in the sites/all/modules and sites/all/themes directories. If you run a
315
multisite installation, you can also place modules and themes in the
316
site-specific directories -- see the Multisite Configuration section, below.
317

    
318
Never edit Drupal's core modules and themes; instead, use the hooks available in
319
the Drupal API. To modify the behavior of Drupal, develop a module as described
320
at http://drupal.org/developing/modules. To modify the look of Drupal, create a
321
subtheme as described at http://drupal.org/node/225125, or a completely new
322
theme as described at http://drupal.org/documentation/theme
323

    
324
MULTISITE CONFIGURATION
325
-----------------------
326

    
327
A single Drupal installation can host several Drupal-powered sites, each with
328
its own individual configuration.
329

    
330
Additional site configurations are created in subdirectories within the 'sites'
331
directory. Each subdirectory must have a 'settings.php' file, which specifies
332
the configuration settings. The easiest way to create additional sites is to
333
copy the 'default' directory and modify the 'settings.php' file as appropriate.
334
The new directory name is constructed from the site's URL. The configuration for
335
www.example.com could be in 'sites/example.com/settings.php' (note that 'www.'
336
should be omitted if users can access your site at http://example.com/).
337

    
338
Sites do not have to have a different domain. You can also use subdomains and
339
subdirectories for Drupal sites. For example, example.com, sub.example.com, and
340
sub.example.com/site3 can all be defined as independent Drupal sites. The setup
341
for a configuration such as this would look like the following:
342

    
343
  sites/default/settings.php
344
  sites/example.com/settings.php
345
  sites/sub.example.com/settings.php
346
  sites/sub.example.com.site3/settings.php
347

    
348
When searching for a site configuration (for example www.sub.example.com/site3),
349
Drupal will search for configuration files in the following order, using the
350
first configuration it finds:
351

    
352
  sites/www.sub.example.com.site3/settings.php
353
  sites/sub.example.com.site3/settings.php
354
  sites/example.com.site3/settings.php
355
  sites/www.sub.example.com/settings.php
356
  sites/sub.example.com/settings.php
357
  sites/example.com/settings.php
358
  sites/default/settings.php
359

    
360
If you are installing on a non-standard port, the port number is treated as the
361
deepest subdomain. For example: http://www.example.com:8080/ could be loaded
362
from sites/8080.www.example.com/. The port number will be removed according to
363
the pattern above if no port-specific configuration is found, just like a real
364
subdomain.
365

    
366
Each site configuration can have its own site-specific modules and themes in
367
addition to those installed in the standard 'modules' and 'themes' directories.
368
To use site-specific modules or themes, simply create a 'modules' or 'themes'
369
directory within the site configuration directory. For example, if
370
sub.example.com has a custom theme and a custom module that should not be
371
accessible to other sites, the setup would look like this:
372

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

    
378
NOTE: for more information about multiple virtual hosts or the configuration
379
settings, consult http://drupal.org/getting-started/6/install/multi-site
380

    
381
For more information on configuring Drupal's file system path in a multisite
382
configuration, see step 6 above.
383

    
384
MORE INFORMATION
385
----------------
386

    
387
- See the Drupal.org online documentation:
388
  http://drupal.org/documentation
389

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

    
394
- For information about the Drupal security process, or to find out how to
395
  report a potential security issue to the Drupal security team, see the
396
  "Security team" page at http://drupal.org/security-team
397

    
398
- For information about the wide range of available support options, visit
399
  http://drupal.org and click on Community and Support in the top or bottom
400
  navigation.