|
1 // $Id: INSTALL.txt,v 1.61.2.4 2008/07/09 19:15:59 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://drupal.org/project/translations 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. |