The first step to using Drupal, of course, is to actually get the software and install it. Drupal comes with an installation script that will walk you through a few screens to gather information and then set up your database and create your site settings file for you. We’ll look at everything you need to make that process run smoothly; you’ll find that installing Drupal is quick and painless once some basic requirements are in place.
Once you have Drupal up and running, it’s important to keep your site up-to-date. New releases of contributed modules and Drupal core come out periodically to address critical security fixes, and it’s important to stay on top of updates as they are released. We’ll take a look at Drupal 7’s built-in Update Status module, which will notify you of updates available for your site, and we’ll talk about the steps required to update both individual modules and the Drupal core itself from one version to another.
Note
You will notice that many people (and even Drupal core’s documentation) use the terms “updating” and “upgrading” interchangeably. They both refer to replacing existing code with newer code.
Prior to installing Drupal, it’s important to make sure that you can actually do so, and understand a bit about how Drupal is structured. This section provides a checklist of Drupal’s requirements, and also highlights important things in the Drupal file structure that are worth knowing before diving into the installation process.
It’s important to have a few things ready prior to installing Drupal. A full list of requirements is available at http://drupal.org/requirements. Use the following as a basic checklist prior to installing Drupal:
Ensure access to a web host or local development environment with the following:
A web server, such as Apache, which handles serving up Drupal’s pages to the browser. Having access to Apache’s mod rewrite extension also allows you to use Drupal’s “Clean URLs” feature, which transforms URLs like http://www.example.com/index.php?q=contact to http://www.example.com/contact.
PHP, the dynamic scripting language that powers Drupal. Drupal 7 requires at least PHP version 5.2 or higher. The requirements page at Drupal.org has more information on required and recommended PHP extensions, most of which are enabled in PHP by default.
A database server, such as MySQL, where Drupal will store all of the content, data, and settings that it needs in order to function.
Note
This book assumes that you are using Apache and MySQL. For additional help and support with other web and database servers, see the Drupal installation guide.
Write down the following information from your web host:
Your (S)FTP or SSH username and password, so you can put Drupal’s files into place.
Your database server’s details, including username, password, and database name, so that Drupal can connect to the database. Some web hosts also require additional information to access the database, such as specifying a remote hostname or a specific database port.
Before you start installing Drupal, you also need a database to which it can be installed; Drupal doesn’t create the database for you, as this normally requires “elevated” permissions on a server. You can install Drupal either in its own separate database, or alongside other applications in a single database using table prefixes, but it’s generally better if it has its own dedicated database. Check with your hosting provider or system administrator if you need information on how to create a new database, and jot down its name for later. Make sure you have the database username and password handy, too.
Note
For development purposes, you may find it easier to have your web environment installed locally to make your changes prior to uploading them to their final locations. There are several free programs that are more or less a “drop in and go” solution, including XAMPP on Windows and Linux, WampServer on Windows, or MAMP on Macintosh.
Once you have checked to make sure you have everything, you’re ready to begin.
The first step before installation is to actually acquire the Drupal code. You can use the Drupal source code provided at http://usingdrupal.com/source_code, or you can download it directly from Drupal.org. Here are the steps to get it from Drupal.org:
Go to http://drupal.org, and you will see two links to download Drupal. They are marked in Figure A-1. Click on the “Download & Extend” link in the upper-right corner of the screen.
The following page lists all of the types of projects you can download: core, modules, themes, translations, and so on. Click the green Download Drupal 7.x button.
This leads to a page that has the release notes for the current version of Drupal core. Click the green Download Drupal 7.x button, and you will begin the download for the latest version.
Drupal files are packaged using either zip, or using the tar program and compressing with gzip. This gives the file an extension of .zip or .tar.gz, respectively. Save one of the files, whichever you prefer, and then extract the files using your favorite extraction application.
Place the extracted files on your web server using an (S)FTP program, or by logging in via shell access and downloading and extracting the files directly on the server.
Now that you have downloaded Drupal, you should take a few moments to open it up and take a look around. Getting familiar with the basic structure and locating important files and directories can take some of the mystery out of how all of this works. When you open up the Drupal folder, you will see the files structured as shown in Figure A-2.
The important pieces that we’ll be covering here are the installation and update files, along with the sites directory. The install.php and update.php files are the two scripts that actually do the work according to their respective names. Because they are located in the top-level folder, also called the Drupal root directory, you can access them directly in your browser’s address bar by typing in something like http://example.com/install.php. In addition to the scripts themselves, there are also two text files, one for each operation: INSTALL.txt and UPGRADE.txt. These files contain instructions on how to use the scripts, which we’ll also be covering in this appendix.
Most first-time Drupal administrators will take a look at the directories in Figure A-2 and place contributed and custom modules and themes into the modules and themes directories, respectively, in the Drupal root. That is where Drupal keeps the core modules and themes, so it only makes sense, right? Placing your files there will work, and Drupal will recognize them; however, this becomes a problem when you first attempt to update to the next security release—overwriting these directories with the new core versions will destroy any modifications that you have made. The best practice is to keep all of a site’s contributed and custom code inside the sites directory. Unless you are running a complex multisite installation (see the sidebar Multiple Sites from One Drupal Installation), this means that you should create new modules and themes directories inside of the sites/all directory, and place your contributed and custom code there, as shown in Figure A-3. This way, all of the files that are particular to your site are in one tidy location rather than all mixed up together with the core files. This makes it much easier to work with when performing upgrades.
Once you have met all of the requirements and gathered the information you need, you can get down to the installation. These instructions assume that you have already created your database, downloaded Drupal, and placed the extracted files on your web server:
Navigate to http://www.example.com to begin the installation process.
The first page of the installation presents you with the choice between a Standard or Minimal installation profile, as shown in Figure A-4. In most circumstances, you will want to leave the default, Standard, selected. The Minimal profile will not install core modules beyond those that are necessary for the site to function, nor will it do any basic configuration for you. Make sure Standard is selected and click the “Save and continue” button.
Once you have selected your installation profile, the next screen allows you to choose a language, as shown in Figure A-5. By default, the only language available is English. However, you may also download other translations and install Drupal in your language of choice. Chapter 8 has more information on installing and configuring multilingual sites. Go ahead and click the “Save and continue” button.
Note
The next screen will initially check for correct permissions before letting you proceed. You may need to change permissions on the parent sites directory, depending on your host configuration. View the help pages referenced in the installer error messages for more details.
Providing all went as expected, you should see a screen asking for your database credentials, as pictured in Figure A-6.
Remember earlier when you wrote down the details of your database connection, including username and password? Now it’s time to use them. At a minimum, you need the name of the database, the database username, and the database password. If your web host requires additional information such as hostname or database port, expand the “Advanced options” fieldset to enter these options. Once you have entered all of the database information, click the “Save and continue” button.
The next page, as shown in Figure A-7, contains a list of initial settings that should be configured on any site.
First, you should fill out the “Site information” fieldset. This deals with important global site settings:
- Site name
This is the name that will be displayed in the title bar on all pages, as well as in the upper-left corner of all pages, by default.
- Site e-mail address
All system emails will be sent from this address—for example, new user registration emails.
The next step is configuring the “Site maintenance” account. The “Site maintenance” account (also referred to as “User 1”) is a “superuser” account that is exempt from all permission checking and has full powers to do everything on the site. You should therefore create a very strong password for this account (fortunately, Drupal will try to help you out by verifying the strength of the password as you type). Use this account sparingly, and only for administrative tasks. For day-to-day usage, create a second user account with fewer privileges.
The “Server settings” section can normally be left at the defaults selected. These options include:
- Default country
You can select the default country for your site. This allows Drupal to define country-specific date and number formats.
- Default time zone
Unless a user otherwise specifies her time zone in her account settings, all posts on the site will show up in the site time zone selected here. By default, Drupal will select the time zone of the browser during installation in an effort to guess what you’d like.
The last section is to configure Update notifications. This feature will check for updates of new modules, themes, and Drupal core automatically, and it can also inform you when updates are available. These options (checked by default) are highly recommended, as it helps ensure that your site is up-to-date on security releases.
Once you have all of your settings entered, click the “Save and continue” button.
The final screen informs you that the installation is complete and you’re ready to proceed with configuring your new website. Click the “your new site” link to begin your Drupal adventure! Figure A-8 shows the initial Drupal screen when it’s first installed.
It’s not enough to just get Drupal installed, however; you also need to make sure to keep it up-to-date. New releases of modules and Drupal core come out periodically, most of which fix problems, some of which add new whiz-bang features, and some of which address critical security problems.
When discussing updates, you’ll find it helps to have some background information about Drupal’s version numbering system. For all the gory details, see http://drupal.org/handbook/version-info, summarized in Figure A-9.
Each “major” release of Drupal core gets a new number: Drupal 5, Drupal 6, Drupal 7, and so on. A new major Drupal version consists of new features, improved usability, and more flexible APIs. Throughout a major version of Drupal’s release cycle, several “minor” versions of Drupal are also released, such as 7.1, 7.2, and 7.3. Minor Drupal versions fix critical security problems and important bugs as well.
Releases of projects like contributed modules, themes, and translations have a version naming scheme such as 7.x-1.3. The “7.x” indicates the major version of Drupal that it is intended to work with; in this case, Drupal 7. The “1” indicates the “major” release of the contributed module. And the “3” indicates that this is the third bug fix release of this major release of the module.
Some releases also have “extra” version information, such as “-beta4” or “-rc2.” These indicate that the modules are still in development, but available for testing.
Updates between minor versions of Drupal core and modules, such as between Drupal 7.3 and 7.4, or Views module 7.x-3.0 and 7.x-3.1, are normally fairly painless, as long as your site is kept up-to-date. Updates between major versions, however, such as Drupal 6.3 to 7.0, or Organic Groups module 6.x-1.0 to 6.x-2.0, and especially to 7.x-1.0, will need special care because the changes are generally quite extensive.
Drupal 7 core includes a module called Update Status, which periodically checks Drupal.org for new releases of modules, themes, and Drupal itself. If one or more of these projects is out of date, or if there is a new security release available, a red warning will be displayed on all pages of the administration panel, telling you to head to the administrative toolbar, and click Reports→“Available updates” (admin/reports/updates) for more information. You can read all of the security announcements on the web and/or follow the Security RSS feed. It is recommended that you subscribe to the Security newsletter, which you can do under your Drupal.org user profile.
Warning
Security updates should be taken very seriously and updated as soon as possible. Read the module’s release notes for more information about bug fixes or features that the update offers.
The “Available updates” screen, as shown in Figure A-10, displays an index of projects installed on your website, colored according to status.
The color codes indicate the following status states:
- Red
A new recommended version of this project is available, and the version on this website is out of date. Pay special attention to projects marked “Security update required!” and download the new recommended versions immediately.
- Yellow
Update Status was not able to find the state of this project. This will happen on projects such as a specific site’s custom, hand-built theme; on projects that were not downloaded from Drupal.org; or if there was a problem reading the status information for this project.
- Green
Project is up-to-date. No further action is required.
Note
The Update Status module can be very noisy if you have many modules installed; over the course of a week, several modules may report that new updates are available if they’re undergoing heavy development. You can adjust the notification threshold at Administer→Reports→“Available updates” on the Settings tab (admin/reports/updates/settings) to email only about security releases, which are mandatory, rather than regular bug fix releases.
There is also a contributed module called the Upgrade Status module, similar to the Update Status module, which will display comparable information about enabled modules and whether they have been ported to the next major Drupal version. This functionality comes in handy when you’re determining the best time to move to a new major version, such as from Drupal 7 to Drupal 8.
If you go to the administrative toolbar, and click the Configuration→“Maintenance mode” (admin/config/development/maintenance) page, pictured in Figure A-11, you can set the site into maintenance mode prior to the upgrade taking place. This mode is useful, as sometimes updates can temporarily cause errors before the entire process is completed. Maintenance mode makes the site inaccessible to regular users while still allowing administrators to work on the site. You don’t want users creating content while you are updating the database, because this could lose some data or display errors to your site visitors. When you put the site into maintenance mode, you can also set a message to display to your users to let them know what is going on.
Note
If you wish to log into the site while it is in offline mode, your user account must be assigned to a role that has the “administer site configuration” permission. Pull up the login form by heading to http://www.example.com/user.
The update.php script, pictured in Figure A-12, automatically runs through any underlying database changes that a module requires in order to move from one version to another. Whether you’re updating between minor or major versions of Drupal and contributed modules, update.php is the piece that ensures your data ends up in the places that it should when all is said and done.
Warning
Because update.php performs updates against the database, it’s very important to create a backup of your database before running this script. The Drupal handbook has instructions at http://drupal.org/node/22281.
The script lists all of the enabled modules on your site, and specifies whether updates are required to be run. A progress bar counts up as each module is updated. And finally, at the end, a report is generated that lists the database changes that were performed, along with any errors that occurred.
Warning
The update.php script is
intended to be run by User 1. If you are not using the User 1
account, you need to edit the settings.php file manually in order to be
able to run the update script. You must change the $update_free_access variable in settings.php so that it is equal to
TRUE rather than FALSE.
But be careful, if you change this value in settings.php, make
sure that you change it back to FALSE as soon as you are done running the
update script! Failure to do so means that anonymous users might be
able to rerun database updates, which could cause all manner of
problems.
Updating your site often sounds much scarier than the actual experience is. In addition to the included UPGRADE.txt file, the online handbook has a great deal of documentation available at http://drupal.org/upgrade and a helpful support forum at http://drupal.org/forum/21. The most important step to remember is creating and testing backups of your site.
Warning
It cannot be stressed enough how important backups are when you are doing upgrades. This holds true for upgrading both Drupal core and contributed modules. You need to make sure you back up both essential parts of a Drupal site: the filesystem and the database. Every system can have a different way to do backups, so that won’t be covered in detail here. You can ask your system administrator or refer to the backup section of the upgrade guide on Drupal.org at http://drupal.org/upgrade/backing-up-the-db. Make sure that you test the backups as well, so that you are sure that you can recreate your site if something goes awry.
Drupal does not automatically download updates. This is to prevent overwriting existing module code before you have a chance to test it. For example, it’s possible that a module may make a change that requires a newer version of PHP than you have installed, which could result in fatal errors on your site if the files were downloaded blindly. Always test updated modules on a test server before deploying them on your “live” site.
This section walks you through the steps to update Drupal within a major version to the next minor release number—for example, if you are using Drupal 7.3 and need to upgrade to Drupal 7.4. When upgrading to a new major version of Drupal, such as Drupal 8, the steps are essentially the same, except that you must also upgrade all of your contributed and custom modules and themes at the same time:
Get the latest release for your version of Drupal by following the same steps as covered in Downloading Drupal.
Before you do anything else, you must make backups of both your database and files. Again, refer to your system administrator or the backup guide at http://drupal.org/upgrade/backing-up-the-db.
Once you have your backups done, log into your site as User 1.
In the administrative toolbar, click Configuration→“Maintenance mode” (admin/config/development/maintenance) and check the “Maintenance mode” checkbox. Feel free to edit the “Maintenance mode message” to whatever you choose. Click the “Save configuration” button to take the site offline.
Note
If you set the site to maintenance mode and log out before changing it back to online mode, you can still log in by going to the user login page manually in the address bar at http://example.com/user.
For major version upgrades, it’s also recommended to go to the administrative toolbar, click Appearance (admin/appearance), and switch the site theme to a core theme such as Bartik or Garland. This step can prevent errors if underlying things have changed that your site’s normal theme depends on.
Extract the Drupal files from the tarball and replace all of the existing files on your server with the new files.
Make sure that all of your site’s files are back in place. Your entire site’s contributed and custom code, along with your files directory, should be in the sites folder in your backup. Grab a copy of the sites folder from the backup you made and add it to your Drupal files. If you have made modifications to other system files, such as .htaccess or robots.txt, restore those from backup as well.
Now that all of the files are in place, it is time to update the database, too. Go to http://example.com/update.php in your browser. You will be presented with a screen that outlines the steps you should take to update the site. Click the Continue button.
You are taken to the update screen. Click the Update button to run the script.
Note
If you expand the “Select versions” fieldset, you can see which modules have registered that they have update code to be run. Modules that have updates to be run will have a schema version number, such as 7001, preselected in their drop-down select list. Drupal keeps track of this for you, so you shouldn’t change this. Modules with no updates will have “No updates available” selected. Even if there are no updates marked, you should still run the update.php script, as it will reset your cache, making sure that Drupal recognizes all of the new files. Failing to run the script may cause some weirdness in the newly updated site until you clear the cache by going to the administrative toolbar, Configuration→Performance (admin/config/development/performance), and clicking the “Clear all caches” button.
After the script runs, you will be returned to a screen indicating that the update is complete. If you changed to a core theme for the upgrade, switch it back to your regular theme by going to the administrative toolbar and clicking Appearance (admin/appearance).
Click around your site and verify that the update was successful. Once you are convinced the site looks OK, return to the administrative toolbar, click Configuration→“Maintenance mode” (admin/config/development/maintenance), uncheck the “Maintenance mode” checkbox, and click “Save configuration” to take the site back online.
Drupal’s contributed projects tend to move more quickly than Drupal core and therefore require more updates within a Drupal version’s life cycle. You can upgrade multiple modules at the same time, although it’s best to do one at a time to reduce the chance of errors, and to allow you to isolate problems that might come up during an upgrade.
In Drupal 7, updating contributed modules has become quite a lot easier than in the past, due to the new update manager. To update contributed modules, follow these steps:
You can see which modules are ready for an update by visiting the Available Updates page: go to the administrative toolbar and click Reports→“Available updates” (admin/reports/updates). You should always read the release notes for each project to be sure you understand what may have changed and whether there are any specific steps you need to take to complete the upgrade beyond running Drupal’s update.php script.
It is still important to make backups of your entire Drupal installation, even though you are only updating a module. If something goes wrong, you want to be able to restore the site to the state it was in before you began. So make your backups before proceeding.
Log into your site as User 1.
Go to the administrative toolbar, click Configuration→“Maintenance mode” (admin/config/development/maintenance) and check the “Maintenance mode” checkbox. Edit the “Maintenance mode message” to whatever you choose. Click “Save configuration” to put the site into maintenance mode.
Now it’s time to start the update. Return to the Available Updates page by going to the administrative toolbar, and clicking Reports→“Available updates” (admin/reports/updates) and click the Update tab. You will be shown a concise list of all of your pending updates, as shown in Figure A-13.
Check the boxes for the modules you wish to update and click the “Download these updates” button.
You will be asked to proceed in maintenance mode. Make sure this box is checked and click Continue.
Once the update is complete, return to the front page of the site and make sure that everything looks OK by navigating around the site. You should especially check the functionality for the particular module or modules provided for your site and make sure that there are no errors.
Repeat steps 5 through 8 for each module that you wish to update.
To finish up, go back to the administrative toolbar, click Configuration→“Maintenance mode” (admin/config/development/maintenance), uncheck the “Maintenance mode” checkbox, and click “Save configuration” to take the site back online.
Here is a list of modules we referenced in this appendix:
Update status: Part of the Drupal core
Here is a list of the external references we used in this appendix:
Here are the Drupal.org resources we referenced: