Installing Drupal multiple sites, multiple Drupal Install Texts

As requested by Kieran, via the documentation list, here's a revision of the installation instructions.

The original doc, written by Dries, details installation on Linux using the shell. This is an update, with a separate version for installing using phpmyadmin (based off this text) to follow.

As discussed on the list, the doc is wiki-formatted. The original (formatted, easy-to-read version) is temporarily available for viewing at:

http://www.amstercad.com/drupal_installation

I am still massaging the section on .htaccess for multi-site installs, and have tried to make this clear within the text. While I work on clarifying the text, others might find this version useful. Hope so.

Please note, this doc is 100% ascii on my system. I'm waiting for the complete ajax spell-check, which means I haven't spell-checked this document.

This doc is so long, maybe it could also be split into a single-site, multi-site set of docs. I will present an idea to the doc list, for conditional text, that might address such circumstance.

----

!CONTENTS OF THIS FILE
*Requirements
*Optional requirements
*Installation
**Drupal administration
**Customizing your theme(s)
*Upgrading
*More Information

!Conventions Used in This Guide
Single parentheses 'such as this example' are used within paragraphs to indicate passages of code that may appear on the screen, or what the user is instructed to enter.

!REQUIREMENTS
Drupal requires a web server, PHP4 (4.3.3 or greater) or PHP5 (www.php.net) and either MySQL (www.mysql.com) or PostgreSQL (www.postgresql.org).

NOTE: the Apache web server and MySQL database are strongly recommended; other web server and database combinations such as IIS and PostgreSQL are possible, but are tested to a lesser extent.

!OPTIONAL REQUIREMENTS
To use XML-based services such as the Blogger API, Jabber, RSS syndication, you need PHP's XML extension. This extension is enabled by default in standard PHP4 installations.

Clean URLs simiplify the address of web pages for both humans and search engines. Clean URLs are optional, although implementation as part of the Drupal installation process is suggested as a best practice, for various technical and functional reasons. For example, search engines will not follow an addressable path that appears dynamically generated from a database. Clean URLs are also easier for people to enter by hand.

For Drupal to generate clean URLs, mod_rewrite support is required in your web server configuration, as well as the ability to use .htaccess files placed within your Drupal directoy. (More information can be found in the Drupal handbook on drupal.org.)

!!DETERMINE YOUR PREFERRED METHOD OF INSTALLATION
Drupal can be installed using several different tools and techniques. Still, there are only two general methods people tend to use.

Most Drupal installations are hosted on Linux, running Apache web and MySQL database servers, so both of the methods documented here involve Drupal sites being hosted using this software. You may choose to use other web or database servers, but they are not as well tested or documented by the Drupal community as Apache and MySQL have been.

The first set of installation instructions is for people who prefer to use a command-line interface to complete the task.

The second set of instructions, has been written for people using the Windows operating system, and who are uploading files from their local workstation to a hosted Linux server.

The installation process should recocognizeable by anyone familiar with similar tools, on similar platforms.

The logic and presentation instructions for your site are comprised of a series of folders and ascii files on the host server. Images and files available for downloading are also stored in the file system. All data describing your website content is stored inside a database. Website content is stored independantly of the website presentation and logic, to the fullest extent possible.

----
!!DOWNLOADING DRUPAL

The latest Drupal release is always available at http://drupal.org/.

The files are in .tar.gz format and can be extracted using most compression tools available on all platforms.

1. Download Drupal onto your server. From the Unix command line, enter:

wget http://drupal.org/files/projects/drupal-x.x.x.tar.gz

tar -zxvf drupal-x.x.x.tar.gz

A new directory is created, named ‘drupal-x.x.x/’ containing all Drupal files and directories.

2. Move the contents within ‘drupal-x.x.x/’ to a new location. Place all of these files and folders inside of your web server's document root directory.

From the command line, enter:

mv drupal-x.x.x/* drupal-x.x.x/.htaccess /var/www/html

!!CREATE A DATABASE FOR DRUPAL

In the examples that follow, 'dba_user' is an MySQL username which has both CREATE and GRANT privileges. Substitute 'dba_user', with an appropriate database user name for your installation.

3. Create a new database called ‘drupal’.

mysqladmin -u dba_user -p create drupal

MySQL will prompt for the 'dba_user' database password, and then create the initial database files.

4. Login to the database and set permissions

mysql -u dba_user -p

Again, you will be prompted to enter the 'dba_user' database password.

5. Once you are allowed access to the database, receiving a prompt fromMySQL, enter following command:

GRANT ALL PRIVILEGES ON drupal.*
TO nobody@localhost IDENTIFIED BY 'password';

Substitute the quoted examples, using the details of your own site.

'drupal' is the name of your database
'nobody@localhost' is the username of your MySQL account
'password' is that belonging to this MySQL username

Query OK, 0 rows affected

6. To assign correct permissions to the database, enter the command:

flush privileges;

7. To exit MySQL and return to the command line, enter:

\q

LOAD THE DRUPAL DATABASE TABLES

8. Once you have a new database, you must install tables into it.

From a command line, enter:

mysql -u nobody -p drupal < database/database.mysql

Take care to substitute the examples 'nobody' and 'drupal' with your MySQL username and database name.

!!CONNECTING DRUPAL

The glue that connects the logic and presentation stored in the file system, to your unique database content, is a text file that is always named settings.php. Edit this file with specifics to your installation, in order to connect the directory of files to the database.

By default the configuration file is located in:

/drupal/sites/default/settings.php'.

Before Drupal is fully powered, you must accurately insert into settings.php both the database address and the base address of the website, which are both read as HTTP URLs.

9. Open the settings.php configuration file and edit the line containing ‘$db_url’ to correspond to your database username, password, www address, and the name of the database itself, all as defined in prior steps. It is not allowed to have a trailing slash in URLs; Drupal will add them for you.

$db_url = "mysql://username:password@localhost/database";

Set $base_url to match the address to your Drupal site:

$base_url = "http://www.example.com";

If you are not concerned with running multiple websites from a single base installation of Drupal, skip to step 11, 'Configuring Drupal'.

!!MULTIPLE SITES FROM A SINGLE CODEBASE
If your server has a fixed, numerical IP address, you can take advantage of [Apache’s Name-based Virtual Host Support|http://httpd.apache.org/docs/1.3/vhosts/name-based.html] to serve multiple domains from a single server. If you don’t have a fixed IP address, you can still serve multiple websites within your single internet domain. In either case, you need only maintain a single directory housing Drupal. You also have the option of using multiple databases for multiple sites, or not; a single database can hold multiple sites, when using a table prefixing technique.

Each website is distinguished from others because it has its own settings.php file inside a directory. This directory must be precisely named to match your intended website address. The naming and directory hierachy of your web server is reflected in the website URL naming and hierachy, which is required by anyone trying to address your site.

A site configuration can be stored in any other 'sites' subdirectory, creating the hierachy. The simplest way to create a new website is to copy a directory, paste it in another, while naming the new copy to reflect to your intended URL, and taking care to adjust the settings.php inside.

For instance, example.com, sub.example.com, and sub.example.com/site3 can all be defined as independent Drupal sites. The directory structure for a such a configuration would look like this:

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 files in the following sequence, using the first settings.php it can find:

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

If your website address includes a non-standard port number, you must substitute the ':' character of your address, (indicating the port number follows), with a '.' character. For example, the website address ‘http://www.example.com:8080/mysite/test/’ is read by the web server from the file directory structure as: ‘sites/www.example.com.8080.mysite.test/’.

Each website configuration can have its own site-specific modules and themes that will be made available, in addition to the modules and themes that are initially installed via the codebase. To use site-specific modules or themes, simply create a modules or themes directory within the site configuration directory.

For example, if sub.example.com has a custom theme and a custom module, that should not be accessible to other sites, the setup would look like this:

sites/sub.example.com/:
settings.php
themes/custom_theme
modules/custom_module

NOTE: for more in-depth information about special configuration settings, consult the Drupal handbook at drupal.org.

***<__BEGIN HTACCESS SECTION__, editing in-progress Jan 31>***

On a single Drupal site, the '.htaccess' file is used to conform URLs as both Drupal and users expect URLs to be. On a multi-site server installation, a single '.htaccess' file is required for each site, and both the location and contents of this file are dependent upon both the server configuration, and the permissions assigned to Drupal.

Instructions are provided for each common installation scenario. Identify your own installation and/or your best option, and do as instructed. Choose and act on a single instruction for step 10, and then skip to step 11.

!Drupal base files installed in the root web directory, accessed as root.

10.1 The advantage of this setup is that paths work and no alterations to the .htaccess file are necessary. However some path information is not available, and name conflicts are a real possibility.

Also, if a symbolic link is made, referring to the Drupal base installation, scripts and directories outside of the base directory are not available to any of the Drupal sites.

Multiple Drupal sites can be created anywhere on the Linux box, and served from a central ly installed Drupal base. But this setup assumes one actually owns the box, so to speak. Most server applications like Drupal are professionally hosted, and it is rare for anyone to have such permissions. However a clued-in home user or small business might be running such a server setup on their own premises, for example.

!Drupal base files installed in a subdirectory of the web root, and accessed from a browser as a subdirectory.

10.2 This is a straightforward setup, and might be useful if you have a single site, but want to make it easy to switch between different versions of Drupal base directories.

Put drupal in htdocs/drupal (or make a symlink) and then have "http://host/drupal" set as the base in "site/host/settings.php". The drupal .htaccess file stays unchanged: since no Alias statement is involved you do not need to change the RewriteBase statement. The symlink version of this is easy for common codebase, but all Drupal links need to include string '/drupal'. Not terrible, but makes migrating to such a system difficult if one has an existing web-indexed or outside-linked system.

!Installed in subdirectory, but accessed as root.

10.3 Starts to get more interesting. Put drupal in a subdirectory (or
more likely make a symlink), then add a .htaccess file in the root
directory that redirects non-existing URL's to '/drupal'. Easy to
upgrade, allows migration from existing installation.

{{{RewriteEngine on
# Redirect root page to drupal home (if desired)
# NOTE: without trailing slash, external redirect to /drupal will
# be used and it will show up in browser. With slash, hidden.
RewriteRule ^$ drupal/ [L]
# Rewrite non-file/directory URL's to be under drupal
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ drupal/$1 [L]
}}}

The problem with this approach for a shared hosting setup is that it
requires symlinks that the user probably does not have the
permissions to create. But if you have control of the whole box,
this might not be a bad approach.

!Installed globally (no symlink), accessed as subdirectory.

or

!Installed globally (no symlink), accessed as root.

Finally we reach the case of having multiple sites with separate
document roots running from a common Drupal codebase. These two are
very similar. The rewrite rules in the common drupal .htaccess are
the same for both.

10.4 Presuming a common Drupal codebase installed in
/var/www/shared/drupal and 'Alias /shared/ /var/www/shared/':

in the common 'drupal/.htaccess':

{{{
RewriteEngine on
RewriteBase /shared/drupal

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]
}}}

Or if you have Drupal aliased directly ('Alias /drupal/
/var/www/drupal/'), set 'RewriteBase /drupal/'.

The rewrite rules in the root of the site will be slightly different:

(in site root .htaccess for Drupal access at root)

{{{
RewriteEngine on
RewriteRule ^$ /shared/drupal/ [L]

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ /shared/drupal/$1 [L]
}}}

(in site root .htaccess for Drupal access as subdir /drupal)
{{{
RewriteEngine on
RewriteRule ^drupal/(.*)$ /shared/drupal/$1 [L]
}}}

If you want access to look like a subdirectory, you'll want to set
$base_url in 'settings.php' to be equal to whatever your locally
aliased subdirectory is (http://host/drupal in this case). Possibly
usefully, these two rulesets can be combined if necessary to allow for
legacy links if you move from one style to another.

Stray notes:

The checks for -f and -d uses full path information when checking: so
if you have a subdir node but are looking for /node/1, -d is false.
But a search for /node/index.html will match and will be served (if
that file indeed exists). But this might cause a problem when using
other programs that require path_info.

Seems like symlinks are matched by check for "-f file". For example,
if 'file.html' is a symlink to 'real.html', "-f file.html" will be
true, contrary to what the manual says about 'regular files'.

Note that you will need to have "AllowOverride FileInfo" (or greater)
turned of for some directory above where your symlink or alias exists.
Otherwise, the symlink will be followed and the root page will be
accessible, but the RewriteRule's in the .htaccess file in the symlink
will be ignored so the rewrite rules won't work. If you are getting
'page not found' errors, you might put an intentional error in your
.htaccess file just to check that it is actualy being read.

RewriteBase is really hard to understand. When per-directory
(.htaccess) rewrite rules are used, the per-directory portion of the
URL is stripped off before the rule is applied, and then put back
after the rule. When RewriteBase is used, the per-directory portion
is still stripped, but then RewriteBase is put back afterwards.
When does one need this? Whenever one is is running out of an
Alias'ed directory, where the file path no longer matches the URL
path. It's not needed when in a subdirectory (or symlinked
subdirectory), only when dealing with aliases. In this case, one
needs to set RewriteBase to be equal to the current subdirectory but
treating the alias as root. For example, if you have 'Alias /shared/
/var/www/shared', and have Drupal installed under
'/var/www/shared/drupal', the .htaccess in that directory would need
to have 'RewriteBase /shared/drupal' to work correctly.

Moving the site-specific configuration files to live in the
virtual-hosts directory instead of in the common Drupal source base is
a separate matter. It should be easy to solve with some judicious
symlinks, though, or with a very simple patch to change where the
site-specific settings.php files are searched for.

******

!!CONFIGURE DRUPAL

11. Create 2 new subdirectories in your Drupal root directory. Name one ‘files’ and the other ‘tmp’ to adopt the Drupal standard, however you can choose different directories by adjusting the appropriate settings at Admin > Settings.

12. Ensure the directory used to store temporary files has correct permissions with the server.

At the command line enter:

chmod /tmp 777

13. Enter the address of your new site in a web browser window.

A login screen is displayed.

14. Click the ‘Register’ tab, enter both a username and E-mail address, and click ‘Create new account’. Drupal assigns you a default, random password, AND the user/edit node is displayed, providing you with an opportunity to change the password to your own preference.

The first account created is also known as UID1 (User ID #1), and is the super-user for this website. This super-user account should only be used for the site setup, major configuration changes, and upgrades. UID1 has special use and purpose. Do not come to use the first super-user account for day-to-day administration on your site; create adminstrator roles later for that purpose.

****

Drupal is now fully-powered and operational.

!!CRON TASKS

Many Drupal modules, such as the Search module, have periodic tasks that must be triggered by scheduling a cron job to occur at specified intervals. Search requires regularly scheduled indexing to occur, for example.

15. To activate these tasks, type the website URL of the cron page in a web browser address bar, and press Enter, as in this example:

http://www.example.com/cron.php

Entering this address in a browser’s address bar initiates a script called cron.php, which permissions all modules that are loaded and stand to benefit, allowing the modules to operate as they are intended, with scheduling patterns derived from the modules directly.

Most systems also support the crontab utility for scheduling tasks. The following crontab example instructs cron to initiate automatically, at the top of each hour:

0 * * * * wget -O - -q http://www.example.com/cron.php

Example scripts are in the ‘scripts’ directory. More information about the cron scripts are available in the admin help pages and in the Drupal handbook at drupal.org.

!!DRUPAL ADMINISTRATION

Upon a new installation, your Drupal website defaults to a very basic
configuration with only a few active modules, one theme, and no user
access rights.

Use your administration options to enable and configure services. For
example, set some general settings for your site with ‘Administer >
Settings’. Enable modules via ‘Administer > Modules’. Users can be set with ‘Administer > Users’.

For more information on configuration options, read through the
instructions accompanying each setting, and consult the various help pages available at ‘Administer > Help’.

!!CUSTOMIZING YOUR INSTALLATION

The default installation of Drupal includes 4 themes, and are available at ‘Administer > Themes’. Changing the appearance for an entire site is as simple as selecting a theme and clicking ‘submit’.

Many more open source themes can be previewed and downloaded for your own site, at http://themes.drupal.org.

Similarly Drupal is extended by the wealth of modules contributed by the community, and made available at http://drupal.org/projects/modules.

----
!FOR MORE DETAILED INFORMATION

For platform specific configuration issues and other installation and
administration assistance, please consult the Drupal handbook at
http://drupal.org/. You can also find support at the Drupal support
forum or through the Drupal mailing lists.