Last updated March 7, 2013. Created on August 15, 2007.
Edited by 2020media, gerbreown, prodosh. Log in to edit this page.

If you are new to Drupal and Apache, these instructions will walk you through most of the things you need to do, to get Drupal up and running on Linux or Windows. I haven't covered the details of setting up a database in MySQL with phpMyAdmin, but I do show you how to configure Apache so that this works. For the Linux instructions the file paths are typical for SuSE Linux 10.1 - for most other Linuxes the htdocs path is likely to start at a different place, but the principles are the same.

We will assume you want to make a local installation on a Windows PC and an installation reachable via the Internet on a Linux server.

Hosts file

You will find the hosts file at the following locations:

- on Windows: c:\windows\system32\drivers\etc\hosts
- on Linux: /etc/hosts

In these instructions, we will assume you want to install a number of sites at:

On Windows (local):    strawberry.loc  and   blueberry.site
On Linux (Internet):    yourdomain.com    and   blueberry.com

The hosts file will look as follows for the Windows example:

127.0.0.1  localhost
127.0.0.1  strawberry.loc
127.0.0.1  blueberry.site blueberry

For a Linux internet server the hosts file should look as follows:

ipaddress  yourhostname.yourdomain.com  yourhostname
127.0.0.1   localhost

Please note that for the Linux server on the Internet you only need to have the Fully Qualified Domainname (FQD) in the form of yourhostname.yourdomain.com in the hosts file. On a Linux system working with DNS, you DO NOT need to make any entries other than the primary FQD in the hosts file. If you want to have a local site at blueberry.site on Linux, you should add the following line to the Linux hosts file:

127.0.0.1  blueberry.site blueberry

Of course blueberry.site would not be reachable through the Internet, because the Internet DNS system would know nothing about it, whereas it would work for a local user on that computer because the local system would know how to deal with it by looking up the information in the computer's hosts file.

DNS

Set up the DNS entries for every domainname your server is hosting. Each one of these domains needs to be resolved to your server's ip address. You will normally be able to configure this with your domain registrar or hosting provider.

For a local Windows or Linux installation, e.g. for development, no DNS configuration is necessary - the entries in the hosts file on your computer are sufficient. Please note that the default localhosts entry in the hosts file is not sufficient to get multi sites working on a Drupal installation.

Apache

Configure Apache for all the different domain names that your web server will be serving.

For Linux (our examples use paths for SuSE Linux > 10.0) the best place to do this is in the vhosts.conf file in the /etc/apache2/vhosts.d directory (you can call this file {anything}.conf). Actually every filename ending in .conf in the vhosts.d directory will be picked up, so beware of multiple overlapping entries - they will confuse the web server.

The entries can also be placed in the /etc/apache2/httpd.conf file initially to keep things simple. Later it is better to do it in the vhosts.conf file - this way, in case of an update of the Apache software, if the httpd.conf file is overwritten, your configuration will survive.

For Windows, you can get Apache, MySQL and PHP from: http://www.apachefriends.org/en/xampp-windows.html
If you installed XAMPP in the default directory on Windows, the vhosts file will be at:
c:\program files\xampp\apache\conf\extra\httpd-vhosts.conf
The entries can also be placed in the
c:\program files\xampp\apache\conf\httpd.conf file initially to keep things simple.

On Linux (the paths in the example are for SuSE Linux), your vhosts.conf file (or entries at the end of the httpd.conf file) should look as follows:

#
#  First entry of this file should be the NameVirtualHost entry, unless it is already there
#  If you want your web server to respond on a different port from the default
#      replace 80 with that port number
#      Available alternative port numbers are 8080 and 2222
#
NameVirtualHost *:80

#  For each domain you want to serve up with Drupal,
#    you need an entry that will match the incoming domain
#  You do not need a separate entry for each subdomain - Drupal takes care of that
#  The following entry takes care of :
#            yourdomain.com
#            www.yourdomain.com
#            bla.yourdomain.com
# gaga.yourdomain.com
#  etc.
#
#  In the following we assume that the Apache htdocs directory is at /srv/www/htdocs
#  and that Drupal has been installed in /srv/www/htdocs/drupal
#

<VirtualHost *:80>
        DocumentRoot /srv/www/htdocs/drupal
        ServerName yourdomain.com
        ServerAlias  *.yourdomain.com
        <Directory /srv/www/htdocs/drupal>
                Allow from all
                Options +Includes +Indexes +FollowSymLinks
                AllowOverride all
        </Directory>
</VirtualHost>

#
#  The following entry takes care of :
#            blueberry.com
#            www.blueberry.com
#            bla.blueberry.com
#      gaga.blueberry.com
#  etc.
#
#  In the following we assume that the Apache htdocs directory is at /srv/www/htdocs
#  and that Drupal has been installed in /srv/www/htdocs/drupal
#

<VirtualHost *:80>
        DocumentRoot /srv/www/htdocs/drupal
        ServerName blueberry.com
        ServerAlias  *.blueberry.com
        <Directory /srv/www/htdocs/drupal>
                Allow from all
                Options +Includes +Indexes +FollowSymLinks
                AllowOverride all
        </Directory>
</VirtualHost>

#
#  On Linux, you will also need an entry to ensure that your phpMyAdmin works
#  - you will need phpMyAdmin to set up and manage your MySQL databases
#  I assume here that you have unpacked and copied the phpMyAdmin files to
#      /srv/www/htdocs/phpMyAdmin
#  Please note that in the following, the DocumentRoot and Directory command
#     both need to use phpMyAdmin
#     using phpmyadmin doesn't work even though phpmyadmin
#     is a symbolic link to phpMyAdmin
#
<VirtualHost *:80>
        ServerName phpmyadmin.yourdomain.com
        DocumentRoot /srv/www/htdocs/phpMyAdmin
        <Directory /srv/www/htdocs/phpMyAdmin>
                allow from all
                Options +Indexes +Includes +FollowSymLinks
                AllowOverride FileInfo Options
        </Directory>
</VirtualHost>

For the local Windows example, your httpd-vhosts.conf file (or entries at the end of the httpd.conf file) should look as follows:

#
#  First entry of this file should be the NameVirtualHost entry, unless it is already there
#  If you want your web server to respond on a different port from the default
#      replace 80 with that port number
#      Available alternative port numbers are 8080 and 2222
#
NameVirtualHost *:80

#  For each domain you want to serve up with Drupal,
#    you need an entry that will match the incoming domain
#  You do not need a separate entry for each subdomain - Drupal takes care of that
#
#  The following entry takes care of e.g:
#            strawberry.loc
#            www.strawberry.loc
#            bla.strawberry.loc
#      gaga.strawberry.loc
#  etc.
#
#  In the following we assume that the Apache htdocs directory is at
#          c:/program files/xampp/htdocs
#  and that Drupal has been installed in c:/program files/xampp/htdocs/drupal
#

<VirtualHost *:80>
        DocumentRoot "c:/program files/xampp/htdocs/drupal"
        ServerName strawberry.loc
        ServerAlias  *.yourdomain.com
        <Directory "c:/program files/xampp/htdocs/drupal">
                Allow from all
                Options +Includes +Indexes +FollowSymLinks
                AllowOverride all
        </Directory>
</VirtualHost>

#  The following entry takes care of e.g:
#            blueberry.site
#            www.blueberry.site
#            bla.blueberry.site
#      gaga.blueberry.site
#  etc.
#
#  In the following we assume that the Apache htdocs directory is at
#          c:/program files/xampp/htdocs
#  and that Drupal has been installed in c:/program files/xampp/htdocs/drupal
#

<VirtualHost *:80>
        DocumentRoot "c:/program files/xampp/htdocs/drupal"
        ServerName blueberry.site
        ServerAlias  *.blueberry.site
        <Directory "c:/program files/xampp/htdocs/drupal">
                Allow from all
                Options +Includes +Indexes +FollowSymLinks
                AllowOverride all
        </Directory>
</VirtualHost>

It seems that the first entry in vhosts.conf becomes the default Apache server, whereas the last entry in httpd.conf becomes the default.

On Windows, you get to phpMyAdmin by pointing your browser to http://localhost/phpmyadmin, if it is installed in the default location under the xampp directory.

Drupal

Make sure that the settings.php file in

    /srv/www/htdocs/drupal/sites/default on Linux or
    c:\program files\xampp\htdocs\drupal\sites\default on Windows

is the default file that came with the Drupal distribution. Now point your browser to http://yourdomain.com and you will see the Drupal install screen which will walk you through the installation for the site http://yourdomain.com.

It will ask you for
- the name of the MySQL database
- the database user and password, and
- ask you to set up the first user who will become the administrator of the site.

It is IMPORTANT that the you use this original settings.php file, OR ELSE the Drupal install procedure DOES NOT WORK when you go to http://yourdomain.com. The reason for this is that if you use an existing installations settings.php file, Drupal thinks the site is already configured and DOES NOT start the one time start up installation.

Do the same for any other domains you intend to use and have configured in Apache.

Independent Site at a subdomain

To have http://bla.yourdomain.com (Linux example) or http://bla.strawberry.loc (Windows local) be a different Drupal site, create a directory called:

/srv/www/htdocs/drupal/sites/bla.yourdomain.com on Linux or
        c:\program files\xampp\htdocs\drupal\sites\bla.stawberry.loc on Windows

and copy the default settings.php file that came with the Drupal distribution into the above directory.

It is IMPORTANT that the you use this original settings.php file, OR ELSE the easy Drupal install procedure DOES NOT WORK. Make sure you have created a separate database for this site in MySQL before starting the install. Just point the browser to:

http://bla.yourdomain.com  on Linux hosting server or
        http://bla.strawberry.loc on your Windows server

to start the installation. Again, It will ask you:
- for the name of the MySQL database
- for the database user and password, and
- to set up the first user who will become the administrator of the site.

Repeat the above for any other sub-domains you want to configure such as http://hello.blueberry.site on Windows.

Independent site at a sub URL

To set up a separate Drupal site at http://www.yourdomain.com/gugu create a directory called

/srv/www/htdocs/drupal/sites/www.yourdomain.com.gugu
       c:\program files\xampp\htdocs\drupal\sites\www.stawberry.loc.gugu on Windows

and copy the default settings.php file that came with the Drupal distribution into the above directory.

It is IMPORTANT that the you use this original settings.php file, OR ELSE the Drupal install procedure DOES NOT WORK. Make sure you have created a separate database for this site in MySQL before starting the install. Just point the browser to:

http://www.yourdomain.com/gugu on Linux or
        http://www.strawberry.com/gugu on Windows

to start the installation. You will be asked:
- for the name of the MySQL database
- for the database user and password, and
- to set up the first user who will become the administrator of the site.

Mechanism for setting up sub-domain and sub-directory/sub-URL sites

For details on how Drupal uses the sites directory structure, read the INSTALL.txt file in the top level drupal directory. Here is the relevant excerpt:

MULTISITE CONFIGURATION

A single Drupal installation can host several Drupal-powered sites, each with
its own individual configuration.

Additional site configurations are created in subdirectories within 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/).

Sites do not have to have a different domain. You can also use subdomains and
subdirectories for Drupal sites. For example, example.com, sub.example.com,
and sub.example.com/site3 can all be defined as independent Drupal sites. The
setup for a configuration 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 files in the following order, using the
first configuration it finds:

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 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.

Each site configuration can have its own site-specific modules and themes in
addition to those installed in the standard 'modules'and 'themes' directories.
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 information about multiple virtual hosts or the configuration
settings, consult the Drupal handbook at drupal.org.

Permissions

FINALLY, make sure all the directories from /srv/www/htdocs/drupal downwards are accessible by the web server. On SuSE Linux, execute:

chown -R wwwrun:www /srv/www/htdocs/drupal 

to ensure that the directories have the right permissions. The userid (uid) is wwrun and the group id (gid) is www.

These can also be configured somewhere in Apache. For other Linux distributions, find out as what user and group Apache runs as and where the htdocs Apache web server root directory is.

Nothing further can stand in the way of your Drupal development - enjoy.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

vunger’s picture

Thank you very much! It worked and it was easier than my single-site install (using these instructions: http://drupal.org/node/307893) had been. All Drupal installs should be done this way.

smiletrl’s picture

Thank you for your step by step details on this process.
Now I find ServerAlias doesn't work for me. No matter what domain/subdomain I used for ServerAlias,everytime I point browser to ServerAlias name e.g. en.mydomain.com, IE or Firefox returns that this is a wrong URL.
I followed your steps,but I get stuck on this point,may you help?
Any advice will be appreciated!

gerbreown’s picture

After trying to follow numerous other articles to set up a Drupal 7.9 multisite on my local system, I'm happy to say this one WORKS...

I had a few problems until I remembered to restart Apache. Then everything worked and I was able to set up six(6) sites on my local system that match my live sites.

Thanks for the information!!!