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

Dries's avatar
Dries committed
3 4 5 6 7 8 9 10 11 12
CONTENTS OF THIS FILE
---------------------

 * Requirements
 * Optional requirements
 * Installation
    - Drupal administration
    - Customizing your theme(s)
 * More Information

Dries's avatar
 
Dries committed
13 14 15
REQUIREMENTS
------------

16
Drupal requires a web server, PHP4 (4.3.3 or greater) or PHP5
Dries's avatar
Dries committed
17
(http://www.php.net/) and either MySQL (http://www.mysql.com/)
18
or PostgreSQL (http://www.postgresql.org/). Your database user
Dries's avatar
Dries committed
19
will also need sufficient privileges to run Drupal. Please
20 21
check the INSTALL.mysql.txt and INSTALL.pgsql.txt for more
detailed information.
Dries's avatar
 
Dries committed
22

23
NOTE: the Apache web server and MySQL database are recommended;
Dries's avatar
 
Dries committed
24
other web server and database combinations such as IIS and PostgreSQL
Kjartan's avatar
Kjartan committed
25
are possible but tested to a lesser extent.
Dries's avatar
 
Dries committed
26

Dries's avatar
Dries committed
27 28
OPTIONAL REQUIREMENTS
---------------------
Dries's avatar
 
Dries committed
29

30
- To use XML-based services such as the Blogger API, Jabber, and RSS
31
  syndication, you will need PHP's XML extension. This extension is
32
  enabled by default.
Dries's avatar
 
Dries committed
33 34 35 36 37 38 39 40 41 42

- If you want support for clean URLs, you'll need mod_rewrite and
  the ability to use local .htaccess files. (More information can
  be found in the Drupal handbook on drupal.org.)

INSTALLATION
------------

1. DOWNLOAD DRUPAL

Dries's avatar
 
Dries committed
43
   You can obtain the latest Drupal release from http://drupal.org/.
44 45
   The files are in .tar.gz format and can be extracted using most
   compression tools. On a typical Unix command line, use:
Dries's avatar
 
Dries committed
46

47
     wget http://drupal.org/files/projects/drupal-x.x.x.tar.gz
48
     tar -zxvf drupal-x.x.x.tar.gz
Dries's avatar
 
Dries committed
49 50

   This will create a new directory drupal-x.x.x/ containing all
51
   Drupal files and directories. Move the contents of that directory
Dries's avatar
 
Dries committed
52
   into a directory within your web server's document root or your
Dries's avatar
 
Dries committed
53 54
   public HTML directory:

55
     mv drupal-x.x.x/* drupal-x.x.x/.htaccess /var/www/html
Dries's avatar
 
Dries committed
56

57
2. CREATE AND PREPARE THE DRUPAL DATABASE
Dries's avatar
 
Dries committed
58

59 60 61 62
   Before you proceed to the next step you should know:
    - "username"      - the username for connecting to the database
    - "password"      - the password for that username
    - "databasename"  - the name of the database
63

64 65
   Depending on the database of your choice, please read either
   INSTALL.mysql.txt (for MySQL) or INSTALL.pgsql.txt (for PostgreSQL).
66

67
3. CONNECTING DRUPAL
Dries's avatar
 
Dries committed
68

Dries's avatar
Dries committed
69 70
   The default configuration can be found in the
   'sites/default/settings.php' file within your Drupal installation.
71 72
   Before you can run Drupal, you must set the database URL. Open the
   configuration file and edit the $db_url line to match the database
73
   defined in the previous step:
Dries's avatar
Dries committed
74

75
     $db_url = "mysql://username:password@localhost/databasename";
Dries's avatar
 
Dries committed
76

77
   If you use PostgreSQL, change "mysql" to "pgsql" in the above line.
78

Dries's avatar
Dries committed
79 80
   In addition, a single Drupal installation can host several
   Drupal-powered sites, each with its own individual configuration.
Dries's avatar
Dries committed
81
   If you don't need multiple Drupal sites, skip to the next section.
Dries's avatar
Dries committed
82 83

   Additional site configurations are created in subdirectories within
Dries's avatar
Dries committed
84 85 86 87 88 89 90
   the 'sites' 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/).
Dries's avatar
Dries committed
91

92 93
   Sites do not each have to have a different domain. You can use
   subdomains and subdirectories for Drupal sites also. For example,
Dries's avatar
Dries committed
94
   example.com, sub.example.com, and sub.example.com/site3 can all be
95
   defined as independent Drupal sites. The setup for a configuration
Dries's avatar
Dries committed
96 97 98 99 100 101 102 103 104
   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
Dries's avatar
Dries committed
105
   files in the following order, using the first configuration it finds:
Dries's avatar
Dries committed
106 107 108 109 110 111 112 113 114

     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

115 116 117 118 119
   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.
120

Dries's avatar
Dries committed
121 122
   Each site configuration can have its own site-specific modules and
   themes that will be made available in addition to those installed
123
   in the standard 'modules' and 'themes' directories. To use
Dries's avatar
Dries committed
124
   site-specific modules or themes, simply create a 'modules' or
125
   'themes' directory within the site configuration directory. For
126
   example, if sub.example.com has a custom theme and a custom module
Dries's avatar
Dries committed
127 128 129 130 131
   that should not be accessible to other sites, the setup would look
   like this:

     sites/sub.example.com/:
       settings.php
Dries's avatar
Dries committed
132 133
       themes/custom_theme
       modules/custom_module
Dries's avatar
Dries committed
134

Dries's avatar
 
Dries committed
135 136 137
   NOTE: for more information about multiple virtual hosts or the
   configuration settings, consult the Drupal handbook at drupal.org.

138
4. CONFIGURE DRUPAL
Dries's avatar
 
Dries committed
139

140 141 142 143 144 145 146
   You should consider creating a "files" subdirectory in your Drupal
   installation directory. This subdirectory stores files such as
   custom logos, user avatars, and other media associated with your
   new site. The sub-directory requires "read and write" permission
   by the Drupal server process. You can change the name of this
   subdirectory at "Administer > Settings > File system settings".

147 148 149
   SECURITY NOTICE: Certain Apache configurations can be vulnerable
   to a security exploit allowing arbitrary code execution. Drupal
   will attempt to automatically create a .htaccess file in your
150
   "files" directory to protect you. If you already have a .htaccess
Gerhard Killesreiter's avatar
Gerhard Killesreiter committed
151 152 153 154 155 156 157
   file in that location, please add the following lines:

     SetHandler Drupal_Security_Do_Not_Remove_See_SA_2006_006
     Options None
     <IfModule mod_rewrite.c>
       RewriteEngine off
     </IfModule>
158

Dries's avatar
 
Dries committed
159 160
   You can now launch your browser and point it to your Drupal site.

161
   Create an account and login. The first account will automatically
162
   become the main administrator account with total control.
Dries's avatar
 
Dries committed
163

164
5. CRON TASKS
Dries's avatar
 
Dries committed
165

166 167 168 169 170
   Many Drupal modules (such as the search functionality) have periodic
   tasks that must be triggered by a cron job. To activate these tasks,
   call the cron page by visiting http://www.example.com/cron.php --
   this will pass control to the modules and the modules will decide if
   and what they must do.
Dries's avatar
 
Dries committed
171

172 173 174
   Most systems support the crontab utility for scheduling tasks like
   this. The following example crontab line will activate the cron
   tasks automatically on the hour:
Dries's avatar
 
Dries committed
175

176
   0   *   *   *   *   wget -O - -q http://www.example.com/cron.php
Dries's avatar
 
Dries committed
177 178

   More information about the cron scripts are available in the admin
179
   help pages and in the Drupal handbook at drupal.org. Example
Dries's avatar
 
Dries committed
180 181 182 183 184
   scripts can be found in the scripts/ directory.

DRUPAL ADMINISTRATION
---------------------

Dries's avatar
 
Dries committed
185
Upon a new installation, your Drupal website defaults to a very basic
186 187
configuration with only a few active modules, one theme, and minimal
user access rights.
Dries's avatar
 
Dries committed
188 189

Use your administration panel to enable and configure services. For
Dries's avatar
Dries committed
190 191 192
example, set some general settings for your site with "Administer >
Settings". Enable modules via "Administer > Modules". User permissions
can be set with "Administer > Users > Configure > Permissions".
Dries's avatar
 
Dries committed
193

194
For more information on configuration options, read the
Dries's avatar
 
Dries committed
195 196 197
instructions which accompany the different configuration settings and
consult the various help pages available in the administration panel.

Dries's avatar
Dries committed
198
Community-contributed modules and themes are available at http://drupal.org/.
Dries's avatar
 
Dries committed
199 200 201 202 203

CUSTOMIZING YOUR THEME(S)
-------------------------

Now that your server is running, you will want to customize the look
204
of your site. Several sample themes are included in the Drupal
Dries's avatar
 
Dries committed
205 206
installation and more can be downloaded from drupal.org.

207 208 209
Simple customization of your theme can be done using only CSS. Further
changes require understanding the phptemplate engine that is now part
of Drupal. See http://drupal.org/handbook/customization to find out more.
Dries's avatar
 
Dries committed
210 211 212 213 214 215 216


MORE INFORMATION
----------------

For platform specific configuration issues and other installation and
administration assistance, please consult the Drupal handbook at
217 218
http://drupal.org/handbook. You can view the wide range of other
support options available at http://drupal.org/support.