5 * Requirements and notes
6 * Optional server requirements
9 * Building and customizing your site
10 * Multisite configuration
11 * Multilingual configuration
13 REQUIREMENTS AND NOTES
14 ----------------------
18 - A web server with PHP support, for example:
19 - Apache 2.0 (or greater) (http://httpd.apache.org/).
20 - Nginx 1.1 (or greater) (http://nginx.com/).
21 - PHP 5.5.9 (or greater) (http://php.net/). For better security support it is
22 recommended to update to at least 5.5.21 or 5.6.5.
23 - One of the following databases:
24 - MySQL 5.5.3 (or greater) (http://www.mysql.com/).
25 - MariaDB 5.5.20 (or greater) (https://mariadb.org/). MariaDB is a fully
26 compatible drop-in replacement for MySQL.
27 - Percona Server 5.5.8 (or greater) (http://www.percona.com/). Percona
28 Server is a backwards-compatible replacement for MySQL.
29 - PostgreSQL 9.1.2 (or greater) (http://www.postgresql.org/).
30 - SQLite 3.7.11 (or greater) (http://www.sqlite.org/).
32 For more detailed information about Drupal requirements, including a list of
33 PHP extensions and configurations that are required, see "System requirements"
34 (https://www.drupal.org/requirements) in the Drupal.org online documentation.
36 For detailed information on how to configure a test server environment using a
37 variety of operating systems and web servers, see "Local server setup"
38 (https://www.drupal.org/node/157602) in the Drupal.org online documentation.
40 Note that all directories mentioned in this document are always relative to the
41 directory of your Drupal installation, and commands are meant to be run from
42 this directory (except for the initial commands that create that directory).
44 OPTIONAL SERVER REQUIREMENTS
45 ----------------------------
47 - If you want to use Drupal's "Clean URLs" feature on an Apache web server, you
48 will need the mod_rewrite module and the ability to use local .htaccess
49 files. For Clean URLs support on IIS, see "Clean URLs with IIS"
50 (https://www.drupal.org/node/3854) in the Drupal.org online documentation.
52 - If you plan to use XML-based services such as RSS aggregation, you will need
53 PHP's XML extension. This extension is enabled by default on most PHP
56 - To serve gzip compressed CSS and JS files on an Apache web server, you will
57 need the mod_headers module and the ability to use local .htaccess files.
59 - Some Drupal functionality (e.g., checking whether Drupal and contributed
60 modules need updates, RSS aggregation, etc.) require that the web server be
61 able to go out to the web and download information. If you want to use this
62 functionality, you need to verify that your hosting provider or server
63 configuration allows the web server to initiate outbound connections. Most web
64 hosting setups allow this.
66 - PHP 5.5.21 provides features for improved security when used with MySQL. While
67 this is not required, it is highly encouraged to use PHP 5.5.21 or 5.6.5 and
73 1. Download and extract Drupal.
75 You can obtain the latest Drupal release from https://www.drupal.org -- the
76 files are available in .tar.gz and .zip formats and can be extracted using
77 most compression tools.
79 To download and extract the files, on a typical Unix/Linux command line, use
80 the following commands (assuming you want version x.y.z of Drupal in .tar.gz
83 wget https://www.drupal.org/files/projects/drupal-x.y.z.tar.gz
84 tar -zxvf drupal-x.y.z.tar.gz
86 This will create a new directory drupal-x.y.z/ containing all Drupal files
87 and directories. Then, to move the contents of that directory into a
88 directory within your web server's document root or your public HTML
89 directory, continue with this command:
91 mv drupal-x.y.z/* drupal-x.y.z/.htaccess drupal-x.y.z/.csslintrc drupal-x.y.z/.editorconfig drupal-x.y.z/.eslintignore drupal-x.y.z/.eslintrc drupal-x.y.z/.gitattributes /path/to/your/installation
93 You can also download the latest version of Drupal using Git on the command
94 line and set up a repository by following the instructions at
95 https://www.drupal.org/project/drupal/git-instructions for "Setting up
96 repository for the first time".
98 Once you have downloaded Drupal successfully, you may install Composer
99 globally using the instructions at
100 https://getcomposer.org/doc/00-intro.md#globally
102 With Composer installed, run the following command from the Drupal web root:
106 2. Create the Drupal database.
108 Because Drupal stores all site information in a database, the Drupal
109 installer will attempt to create this database for you. If you create the
110 database manually, you must grant Drupal certain database privileges (such as
111 the ability to create tables). For details, consult INSTALL.mysql.txt,
112 INSTALL.pgsql.txt, or INSTALL.sqlite.txt. You may also need to consult your
113 web hosting provider for instructions specific to your web host.
115 Take note of the username, password, database name, and hostname as you
116 create the database. You will enter this information during the install.
118 3. Run the install script.
120 To run the install script, point your browser to the base URL of your
121 website (e.g., http://www.example.com).
123 You will be guided through several screens to set up the database, add the
124 site maintenance account (the first user, also known as user/1), and provide
125 basic web site settings.
127 During installation, several files and directories need to be created, which
128 the install script will try to do automatically. However, on some hosting
129 environments, manual steps are required, and the install script will tell
130 you that it cannot proceed until you fix certain issues. This is normal and
131 does not indicate a problem with your server.
133 The most common steps you may need to perform are:
135 a. Missing files directory.
137 The install script will attempt to create a public file storage directory
138 in the default location at sites/default/files (the location of the files
139 directory may be changed after Drupal is installed).
141 If auto-creation fails, you can create the directory yourself. (If you are
142 creating a multisite installation, substitute the correct sites directory
143 for sites/default; see the Multisite Configuration section of this file,
144 below.) Sample commands from a Unix/Linux command line:
146 mkdir sites/default/files
147 chmod a+w sites/default/files
149 Alternatively, you can make the install script work by changing
150 permissions on the sites/default directory. The web server can then
151 create the files directory within it for you.
153 For example, on a Unix/Linux command line, you can you can grant everyone
154 (including the web server) permission to write to the sites/default
155 directory with this command:
157 chmod a+w sites/default
159 Then re-run install.php (e.g. by clicking "try again" at the bottom of
160 the Requirements problem page. Once the files directory is created, you
161 will need to grant everyone (including the web server) permission to
162 write to it with this command:
164 chmod a+w sites/default/files
166 Be sure to set the permissions for the default directory back after the
167 installation is finished! (Leave the files directory writeable.)
170 chmod go-w sites/default
172 b. Missing settings file.
174 Drupal will try to automatically create a settings.php configuration file,
175 which is normally in the directory sites/default (to avoid problems when
176 upgrading, Drupal is not packaged with this file). If auto-creation fails,
177 you will need to create this file yourself, using the file
178 sites/default/default.settings.php as a template.
180 For example, on a Unix/Linux command line, you can make a copy of the
181 default.settings.php file with the command:
183 cp sites/default/default.settings.php sites/default/settings.php
185 Next, grant write privileges to the file to everyone (including the web
186 server) with the command:
188 chmod a+w sites/default/settings.php
190 Be sure to set the permissions back after the installation is finished!
193 chmod go-w sites/default/settings.php
195 c. Write permissions after install.
197 The install script will attempt to write-protect the settings.php file and
198 the sites/default directory after saving your configuration. If this
199 fails, you will be notified, and you can do it manually. Sample commands
200 from a Unix/Linux command line:
202 chmod go-w sites/default/settings.php
203 chmod go-w sites/default
205 4. Verify that the site is working.
207 When the install script finishes, you will be logged in with the site
208 maintenance account on a "Welcome" page. If the default Drupal theme is not
209 displaying properly and links on the page result in "Page Not Found" errors,
210 you may be experiencing problems with clean URLs. Visit
211 https://www.drupal.org/getting-started/clean-urls to troubleshoot.
213 5. Change file system storage settings (optional).
215 The files directory created in step 3 is the default file system path used to
216 store all uploaded files, as well as some temporary files created by
217 Drupal. After installation, you can modify the file system path to store
218 uploaded files in a different location.
220 It is not necessary to modify this path, but you may wish to change it if:
222 - Your site runs multiple Drupal installations from a single codebase (modify
223 the file system path of each installation to a different directory so that
224 uploads do not overlap between installations).
226 - Your site runs on a number of web servers behind a load balancer or reverse
227 proxy (modify the file system path on each server to point to a shared file
230 - You want to restrict access to uploaded files.
232 To modify the file system path:
234 a. Ensure that the new location for the path exists and is writable by the
235 web server. For example, to create a new directory named uploads and grant
236 write permissions, use the following commands on a Unix/Linux command
242 b. Open your settings.php in a plain-text editor, and uncomment (remove the #
243 at the start of line) this line:
245 # $settings['file_public_path'] = 'sites/default/files';
247 Enter the desired path and save the file.
249 If you want to use private file storage, you need to uncomment (remove
250 the # at the start of line) the following line in settings.php:
252 # $settings['file_private_path'] = '';
254 Enter the path for private files and save the file.
256 Changing the file system path after files have been uploaded may cause
257 unexpected problems on an existing site. If you modify the file system path
258 on an existing site, remember to copy all files from the original location
261 6. Revoke documentation file permissions (optional).
263 Some administrators suggest making the documentation files, especially
264 CHANGELOG.txt, non-readable so that the exact version of Drupal you are
265 running is slightly more difficult to determine. If you wish to implement
266 this optional security measure, from a Unix/Linux command line you can use
267 the following command:
269 chmod a-r CHANGELOG.txt
271 Note that the example only affects CHANGELOG.txt. To completely hide all
272 documentation files from public view, repeat this command for each of the
273 Drupal documentation files in the installation directory, substituting the
274 name of each file for CHANGELOG.txt in the example.
276 For more information on setting file permissions, see "Modifying Linux,
277 Unix, and Mac file permissions" (https://www.drupal.org/node/202483) or
278 "Modifying Windows file permissions" (https://www.drupal.org/node/202491) in
279 the Drupal.org online documentation.
281 7. Set up independent "cron" maintenance jobs.
283 Many Drupal modules have tasks that must be run periodically, including the
284 Search module (building and updating the index used for keyword searching),
285 the Aggregator module (retrieving feeds from other sites), and the System
286 module (performing routine maintenance and pruning of database tables). These
287 tasks are known as "cron maintenance tasks", named after the Unix/Linux
290 When you install Drupal, its built-in cron feature is enabled, which
291 automatically runs the cron tasks periodically, triggered by people visiting
292 pages of your site. You can configure the built-in cron feature by navigating
293 to Administration > Configuration > System > Cron.
295 It is also possible to run the cron tasks independent of site visits; this is
296 recommended for most sites. To do this, you will need to set up an automated
297 process to visit the page /cron on your site, which executes the cron
300 The URL of the cron page requires a "cron key" to protect against
301 unauthorized access. Your site's cron key is automatically generated during
302 installation and is specific to your site. The full URL of the page, with the
303 cron key, is available in the "Cron maintenance tasks" section of the Status
304 report page at Administration > Reports > Status report.
306 As an example for how to set up this automated process, you can use the
307 crontab utility on Unix/Linux systems. The following crontab line uses the
308 wget command to visit the cron page, and runs each hour, on the hour:
310 0 * * * * wget -O - -q -t 1 http://example.com/cron/YOURKEY
312 Replace the text "http://example.com/cron/YOURKEY" in the example with the
313 full URL displayed under "Cron maintenance tasks" on the "Status report"
316 More information about cron maintenance tasks is available at
317 https://www.drupal.org/cron, and sample cron shell scripts can be found in
318 the core/scripts/ directory. (Note that these scripts must be customized like
319 the above example, to add your site-specific cron key and domain name.)
324 Drupal can be reinstalled without downloading and extracting the Drupal release.
326 1. Drop all the tables in your database.
328 2. Remove everything in sites/default/files.
330 3. Remove sites/default/settings.php.
332 4. Follow the Installation Instructions above starting from Step 3 (Run the
335 BUILDING AND CUSTOMIZING YOUR SITE
336 ----------------------------------
338 A new installation of Drupal defaults to a very basic configuration. To extend
339 your site, you use "modules" and "themes". A module is a plugin that adds
340 functionality to Drupal, while a theme changes the look of your site. The core
341 of Drupal provides several optional modules and themes, and you can download
342 more at https://www.drupal.org/project/project_module and
343 https://www.drupal.org/project/project_theme
345 Do not mix downloaded or custom modules and themes with Drupal's core modules
346 and themes. Drupal's modules and themes are located in the /core/modules and
347 /core/themes directories, while the modules and themes you add to Drupal are
348 normally placed in the /modules and /themes directories. If you run a multisite
349 installation, you can also place modules and themes in the site-specific
350 directories -- see the Multisite Configuration section, below.
352 Never edit Drupal's core modules and themes; instead, use the hooks available in
353 the Drupal API. To modify the behavior of Drupal, develop a module as described
354 at https://www.drupal.org/developing/modules. To modify the look of Drupal,
355 create a subtheme as described at https://www.drupal.org/node/2165673, or a
356 completely new theme as described at https://www.drupal.org/docs/8/theming
358 MULTISITE CONFIGURATION
359 -----------------------
361 A single Drupal installation can host several Drupal-powered sites, each with
362 its own individual configuration.
364 For this to work you need the file sites/sites.php to exist. Make a copy of
365 the example.sites.php file:
367 $ cp sites/example.sites.php sites/sites.php
369 Additional site configurations are created in subdirectories within the 'sites'
370 directory. Each subdirectory must have a 'settings.php' file, which specifies
371 the configuration settings. The easiest way to create additional sites is to
372 copy file 'default.settings.php' from the 'sites/default' directory into the
373 new site directory with file name 'settings.php' and modify as appropriate.
374 The new directory name is constructed from the site's URL. The configuration
375 for www.example.com could be in 'sites/example.com/settings.php' (note that
376 'www.' should be omitted if users can access your site at http://example.com/).
378 $ cp sites/default/defaults.settings.php sites/example.com/settings.php
380 Sites do not have to have a different domain. You can also use subdomains and
381 subdirectories for Drupal sites. For example, example.com, sub.example.com, and
382 sub.example.com/site3 can all be defined as independent Drupal sites. The setup
383 for a configuration such as this would look like the following:
385 sites/default/settings.php
386 sites/example.com/settings.php
387 sites/sub.example.com/settings.php
388 sites/sub.example.com.site3/settings.php
390 When searching for a site configuration (for example www.sub.example.com/site3),
391 Drupal will search for configuration files in the following order, using the
392 first configuration it finds:
394 sites/www.sub.example.com.site3/settings.php
395 sites/sub.example.com.site3/settings.php
396 sites/example.com.site3/settings.php
397 sites/www.sub.example.com/settings.php
398 sites/sub.example.com/settings.php
399 sites/example.com/settings.php
400 sites/default/settings.php
402 If you are installing on a non-standard port, the port number is treated as the
403 deepest subdomain. For example: http://www.example.com:8080/ could be loaded
404 from sites/8080.www.example.com/. The port number will be removed according to
405 the pattern above if no port-specific configuration is found, just like a real
408 Each site configuration can have its own site-specific modules and themes in
409 addition to those installed in the standard 'modules' and 'themes' directories.
410 To use site-specific modules or themes, simply create a 'modules' or 'themes'
411 directory within the site configuration directory. For example, if
412 sub.example.com has a custom theme and a custom module that should not be
413 accessible to other sites, the setup would look like this:
415 sites/sub.example.com/
418 modules/custom_module
420 For more information about multiple virtual hosts or the configuration
421 settings, consult https://www.drupal.org/documentation/install/multi-site
423 For more information on configuring Drupal's file system path in a multisite
424 configuration, see step 6 above.
426 MULTILINGUAL CONFIGURATION
427 --------------------------
429 By default, Drupal is installed in one language, and further languages may be
432 For detailed instructions, visit
433 https://www.drupal.org/documentation/multilingual