Local multi-site installation of Drupal 7 on Linux

Last updated February 7, 2013. Created by Fiable.biz on April 2, 2011.
Edited by cmalek, aaron, jhr. Log in to edit this page.

Drupal allows you to run multiple sites from a single Drupal code installation -- each with its own modules, content, theme, etc. For instance, you can run:

• Multiple sites on your local computer
• Multiple domains in a single hosting account
• Multiple sub-domains
• Multiple sub-directory sites

For a live multi-site installation, see Multisites Using Drupal 7.

This page describes one way to run multiple test sites on your local computer with Drupal 7 on Ubuntu 10.10, Ubuntu 11.04 and Mandriva 2010.2. But the method probably works with little modifications for other distributions. Purposedly, we only present one way to do that, in details, and we try to explain a bit what we're doing. We're not sure whether this procedure contains mistakes or not, and we think it probably contains useless things.

Note: if you are creating multiple sites, it is desirable to make a list of the desired sites before reading through these instructions completely. Some steps can be done in bulk to save time.

Why create extra sites? In addition to having several sites running already, you may have some ideas in the back of your head for other sites that you might put up in the future. So before you totally pooh-pooh the idea, give it a few minutes' thought. And you can always change your mind later; it just might be a bit messier then.

The Basics

In a normal situation, any web page is served by a server to a client, as a meal in a restaurant. "Server" refers both to a computer (usually a mainframe) or to a piece of software. Both are necessary to do the job. Similarly, "client" refers both to a computer (usually a PC) and to a piece of software, such a Mozilla Firefox or Google Chromium. Here, a same computer (yours) will be the server and its own client, but the server and client applications keep separate. In this page, we chose Apache as the server software. You may wonder why a server piece of software is even necessary on your computer. After all, you can just double-click on any HTML file to see it in your browser, even if Apache is not installed. This is because HTML, XHTML, CSS and JavaScript are interpreted client-side, i.e. by the browser itself. On internet, they are served by a server, but, on your local computer, they can be read directly. But Drupal also uses PHP, a programming language interpreted server-side: even on your own computer, if you don't have a server piece of software installed, the program will not be interpreted, and Drupal will not work. In Ubuntu, Apache serves the files in the /var/www/ hierarchy (in Mandriva Linux 2010, it is /var/www/html/), except if taught another location.

The main idea in this multi-site installation is that you need a MySQL database and a subdirectory of /var/www/drupal7/sites for each web site. It will be easier for you if their names are identical or similar (except for the default site, whose directory is /var/www/drupal7/sites/default and database is "drupal7"). In the instructions below, the site short name is "example", the database name is "company_example", and the site future URL: "example.com". The database will contain your web site text, while the subdirectory /var/www/drupal7/sites/example.com/ (Remember that example.com stands for your website future URL.) will usually contain your web site pictures, specific modules and themes, in subdirectories called "files", "modules" and "themes" respectively. The modules and themes common to multiple web sites are in /var/www/drupal7/sites/all/. The Drupal package installation creates automatically a subdirectory /var/www/drupal7/sites/default/.

The packages

To install the packages, you can use your distribution's package manager: "Ubuntu software center", "Mandriva control center" (then → "Software management", choosing "All" and "All" in the top left corner except if you want to restrain your search.).

• If your distribution includes Drupal 7, install this package; if prompted to choose between MySQL and MySQLi, choose the latter, and go directly to the paragraph "Mono-site installation of Drupal 7".
• If your distribution doesn't include Drupal 7
  1. Install Apache, MySQL and PHP: if your distribution includes a meta-package called "LAMP" (Linux, Apache, MySQL, PHP), or "LAMP PHP", use it (In Mandriva 2010 control center → Software management, you can restrain your search to "Meta packages" and "All" in the top left corner). If your distribution doesn't include such a meta package, install the three packages one by one.
  2. Install also MySQL administrator and PhpMyAdmin.
  3. (Step not needed in Ubuntu 10 and 11.) Install the PHP-PDO MySQL package: in Mandriva 2010, it's called php-pdo_mysql. And enable it: in Mandriva 2010, add the line
     extension=pdo_mysql.so
     to the file /etc/php.d/70_php.ini .

Mono-site installation of Drupal 7

Firstly install Drupal 7 thanks to your distribution or by hand. See Quick install for beginners (Neither Ubuntu 11.04 or Mandriva Linux 2010.2 include Drupal 7). Don't insert any dot in the name of the directory you install Drupal in. We suggest /var/www/drupal7/ and we will suppose below that such is its name. The corresponding database name cannot contain contain spaces, slashes, nor dots. I'll suppose below it is "drupal7".
Since you install locally, skip the "Set up a Domain and point it to the directory containing Drupal's files" part of the Quick install for beginners. Instead, you'll setup a virtual host:

Setting the default site hostname

In Ubuntu 10 and 11

At starting, Apache reads Ubuntu's file /etc/apache2/apache2.conf that file which includes several directives, notably:

ports.confs says "NameVirtualHost *:80".
which means that for all IP (the star means "all") the virtual host will be redirected as indicated. "80" is the number of the port listened to by Apache.

• Create a file called /etc/apache2/sites-available/drupal7 saying:
  
  <VirtualHost *:80>
   DocumentRoot /var/www/drupal7
   ServerName drupal7
</VirtualHost>
  
  This means that "drupal7" will point to /var/www/drupal7/ .
• Create a symbolic link from the directory sites-enabled to this file (So if you later want to disable your Drupal sites you will not need to remove them, but just to remove the link.):
  sudo ln -s /etc/apache2/sites-available/drupal7 /etc/apache2/sites-enabled/drupal7
• Create a file called /etc/apache2/conf.d/drupal7.conf saying:
  
  Alias drupal7 127.0.0.1

<Directory /var/www/drupal7>
Options +FollowSymLinks
AllowOverride All
order allow,deny
allow from all
</Directory>
• In Ubuntu 11.04, in order to enable Apache's Rewrite module, necessary for Drupal's "Clean URLs" feature, launch Debian script sudo a2enmod rewrite, which will create the symbolic link /etc/apache2/mods-enabled/rewrite.load .

In Mageia 2 and Mandriva Linux 2010

• Navigate to /etc/httpd/conf/vhosts.d/ folder.
• Open 00_default_vhosts.conf file. Apache's main configuration file is /etc/httpd/conf/httpd.conf . At starting, Apache reads that file which includes several directives, notably:
  
  Include conf/webapps.d/*.conf
Include conf/vhosts.d/*.conf
  
  So that our file 00_default_vhosts.conf will be read as if it were part of the main configuration file.
• At the bottom of the existing list, comment out (adding the charcter "#" at the beginning of the lines) the examples.
• After these comment lines, enter:
  
  NameVirtualHost *:80
<VirtualHost *:80>
   DocumentRoot /var/www/html
   ServerName localhost
</VirtualHost>
<VirtualHost *:80>
   ServerPath /drupal7
   DocumentRoot /var/www/drupal7
   ServerName drupal7
</VirtualHost>
  
  The 1^st line means that for all IP (the star means "all") the virtual host will be redirected as indicated. "80" is the number of the port listened to by Apache. Then we say that "localhost" will point to /var/www/html/, which is not in the Drupal hierarchy, so that you be still able to have non-Drupal websites there. If all your websites are Drupal websites, don't write these lines. But you still need the 1st one. And the last virtual host is for the default Drupal 7 site.

Setting the default site database

MySQL administrator calls "schema" what Drupal and PhpMyAdmin call "database".

• Create an empty database schema with MySQL administrator. In Ubuntu 10 and 11, you'll find MySQL administrator in Applications→Programming. (In Mandriva 2010: "Applications launcher menu" → Development → Databases). Name this schema "drupal7". To create it, click on “Catalogs” and right-click in the left bottom part of the window called schemata, then choose “Create schema”. You can also use PhpMyAdmin to create your database schema, called there "database": in your browser: http://localhost/phpmydamnin .
• Be aware that some share hosting services require that all your database usernames begin by a fix part (for instance derived from your main site name) followed by an underscore. If you don't want to change your username when putting your Drupal site alive, check your hosting service rules now. Create a user called "company_drupal", where "company" stands for the prefix required by your hosting service provider. To add a new user, in MySQL aministrator, click on "User administration"→"New user", and name it "company_drupal", then in the left bottom part of the window called "User accounts", right-click on the user name, choose "Add host" and add the host "localhost". Give this user a password (don't forget it).
• Grant company_drupal@localhost the SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE_TMP_TABLE and LOCK_TABLES privileges to this new schema. To do so, in MySQL administrator:User administration, in the bottom left part of the window called "User accounts", click on company_drupal, then on "@localhost", then in the right part of the window, on tab "Schema privileges", in the "Schema part", click on "drupal7", in the "Available privileges" part, choose the above mentioned privileges and move them to the "Assigned privileges" thanks to the left arrow in between. Then click on "Apply changes".

Don't use the default site

We suggest you don't use the default website, so that you'll always have a virgin site to copy or to compare to your sites. So don't add content to it, don't enable modules or themes, don't configure it. The bulk loops below have to be performed as many times as you want to create sites (other than the default one). Check if the default Drupal web site and the non-Drupal websites, if any, work.

Setting the databases

MySQL administrator calls "schema" what Drupal and PhpMyAdmin call "database".

Bulk loop 1

• Create an empty database schema with MySQL administrator. In Ubuntu 10 and 11, you'll find MySQL administrator in Applications→Programming. (In Mandriva 2010: "Applications launcher menu" → Development → Databases). Give this schema a name related to your website name. It cannot contain spaces, slashes, nor dots. Be aware that some share hosting services require that all your schemas names and database usernames begin by a fix part (for instance derived from your main site name) followed by an underscore. If you don't want to change your schema's name or username when putting your Drupal site alive, check your hosting service rules now. As said, we will call the schema "company_example". To create it, click on “Catalogs” and right-click in the left bottom part of the window called schemata, then choose “Create schema”.
• We will use for the schema "company_example" the user name already used for the schema "drupal7" of the Drupal website. If you've forgot it, look in /var/www/drupal7/sites/default/settings.php for a line like
        'username' => 'company_drupal',
  Let's suppose the main username of Drupal in MySQL is "company_drupal". If the website you're created in for a human client, it's more secure providing its database a different MySQL user, so that he won't be able to modify the other websites databases. In this case, we suggest 2 users have write access to the database: the general user "company_drupal", so that you can do modifications on the websites without changing user between the websites, and the MySQL user specific to that website, let's say "company_example". (So "company_example" is both the name of the schema and of its user.) To add a new user, in MySQL aministrator, click on "User administration"→"New user", and name it "company_example", then in the left bottom part of the window called "User accounts", right-click on the user name, choose "Add host" and add the host "localhost". Give this user a password (don't forget it).
• So let's suppose the user representing Drupal for the schema "company_example" is company_example. Grant company_example@localhost the SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE_TMP_TABLE and LOCK_TABLES privileges to this new schema. To do so, in MySQL administrator:User administration, in the bottom left part of the window called "User accounts", click on company_example, then on "@localhost", then in the right part of the window, on tab "Schema privileges", in the "Schema part", click on "company_example", in the "Available privileges" part, choose the above mentioned privileges and move them to the "Assigned privileges" thanks to the left arrow in between. Then click on "Apply changes". The same way, grant the same privileges to your general MySQL user "company_drupal".

End of bulk loop 1

Setting the subdirectories

Bulk loop 2

• Copy directory /var/www/drupal7/sites/default as /var/www/drupal7/sites/example.com  .
• Give read and write permissions to everybody for that directory and for /var/www/drupal7/sites/example.com/files/ .
• If the file /var/www/drupal7/sites/example.com/settings.php doesn't exist yet, copy /var/www/drupal7/sites/example.com/default.settings.php to /var/www/drupal7/sites/example.com/settings.php .
• Search the line beginning by "$databases" and modify that paragraph like this:
  
  $databases['default']['default'] = array(
   'driver' => 'mysql',
   'database' => 'company_example',
   'username' => 'company_example',
   'password' => 'my_password',
   'host' => 'localhost',
   'prefix' => '',
   'collation' => 'utf8_general_ci',
);
  
  replacing the 1st occurrence of "company_example" by the database schema's name, "my_password" by your password, and, if you have created another database user representing Drupal in the schema, replace also "company_example" by its name. If you have installed mysqli, replace "mysql" by "mysqli".

End of bulk loop 2
Copy /var/www/drupal7/sites/example.sites.php to /var/www/drupal7/sites/sites.php .

Bulk loop 3

• At the end of /var/www/drupal7/sites/sites.php , add the following line:
  $sites['example'] = 'example.com';
  replacing "example" by the website short name, and "example.com" by the directory name.

End of bulk loop 3

Setting the hostnames

Bulk loop 4

• In /etc/apache2/sites-enabled/drupal7 (In Mageia 2 and Mandriva Linux 2010, it is /etc/httpd/conf/vhosts.d/00_default_vhosts.conf ), add
  
  <VirtualHost *:80>
   DocumentRoot /var/www/drupal7
   ServerName example
</VirtualHost>
• In /etc/apache2/conf.d/drupal7.conf (in Mageia 2, it is the file /etc/httpd/conf/webapps.d/drupal.conf ), add the line (not needed in Mandriva Linux 2010)
  Alias example 127.0.0.1
• in the file /etc/hosts , add "example " to this line of aliases:
  127.0.0.1 example localhost
  In Mageia 2 and Mandriva Linux 2010, you can instead go to "Configure your computer" → "Network and internet" → Others → "Host definitions" (drakhosts), choose the line "127.0.0.1", click on "Modify", add the databases' names in the line "Host Aliases", separated by spaces, then click on the 2 successive "OK" buttons.

End of bulk loop 4

Relaunch Apache by
sudo service apache2 restart
In Mageia 2 go instead to "Configure your computer" → System → "Manage system services by enabling or disabling them" (drakxservices), in the line "httpd-prefork", click the "Start" button (In Mandriva Linux 2010, click on "httpd" and on the "Start Service" button). This will stop and relaunch Apache. Wait for it to say "running.". Click on the "OK" button.

Bulk loop 5

Go with your web browser on the page http://example/install.php and follow carefully the instructions. Specially, don't forget to remove the world write permission of /var/www/drupal7/sites/example.com when asked to do so.

End of bulk loop 5
It should work now. You can close MySQL administrator.

Troubleshooting

If you got an error or a empty screen during the process, then modified something and want to try again, then you may need to clear your browser cache to check whether your new attempt is fruitful. For this,

• in Mozilla Firefox, go to Edit → Preferences → Privacy → "Clear your recent history"; in "Time range history", choose a duration at least as long as the time elapsed since your first modification; if unsure, choose "Everything". In "Details", check only "Cache", then click on "Clear now".
• In Chromium web browser, go to the wrench icon on the top right → Preferences → Under the bonnet → Privacy: Clear browsing data. In "Obliterate the following items from:" choose the duration (If unsure, choose "the beginning of time".), check only "Empty the cache" then click on "Clear browsing data".

Making your websites

• Dowload the contributed modules and themes you need. They have to be compatible with your main version of Drupal. The main version is indicated by the first number. For instance, If you have installed Drupal 7.0, the main version is refered to as "7.x", and the modules compatible with it are numbered 7.x-a.b, where a and b are integers (Example: "7.x-3.7"). Versions called "7.x-a.b-dev" are versions in development. Don't worry: you can install and uninstall contributed modules and themes as soon as Drupal is installed, and later at any time. (Before uninstalling anything, check it's not used.) So if you don't know what you will need, you can just begin with Drupal's core modules and themes, and are not required to install any. You can get trouble with development versions, even after you've desintalled them.
• Decompress the modules and themes you have downloaded and read carefully the README.txt and INSTALL.TXT (if any) files in them. Then put into /var/www/drupal7/sites/all/modules/ the decompressed directories of modules which will be used by several sites. Put into /var/www/drupal7/sites/all/themes/ the decompressed directories of contributed themes which will be used by several sites, if you need so. Put into /var/www/drupal7/sites/all/files/ the files (notably pictures) which will be used by several sites if any.
• Open your browser if it's not open yet.

Bulk loop 6

• Install in /var/www/drupal7/sites/example.com/modules/ the contributed modules which will only be used by the website called databasename, if any.
• Install in /var/www/drupal7/sites/example.com/themes/ the contributed themes which will only be used by the website whose directory example.com, if any. If, for the sole website example.com, you modify a theme present in /var/www/drupal7/sites/all/themes/ and put the modified version into /var/www/drupal7/sites/example.com/themes/, change its name so that you can easily distinguish the two. Don't change the folder name, but change the name Drupal will display: if you theme is called myTheme, then open the file myTheme/myTheme.info, at the beginning of this file, find the line beginning by "name =" and change what follows the "=" sign. You may also want the change the "description" of the theme, thanks to the line beginning by "description =". Remember that if you modify a copyrighted theme, you need the author's authorisation. If it's a theme distributed with a free license, this authorisation is granted automatically under some conditions, notably that you provide in turn your modified version under a similar license, on request.
• In your brower, visit http://example and follow those instructions. You notably have to give your site a title, and to enable the modules and themes you will use. Again, you may enable or disable any module or theme later. But changing theme may cause problems in an existing site, specially if you change for a contributed theme.

End of bulk loop 6

Backing up and restoring

Don't forget to include your web sites folders and database schemata in your regular backup scheme. They are located in /var/www/drupal7/sites/ and /var/lib/mysql/ , respectively.

Mandriva Linux 2010's general backup scheme

• Go to Configure your computer → System → Draksnapshot → Advanced → Add .
• Add /var/www/drupal7/sites/ if you want to save this directory and it's not already included in the directories to save. You may prefer to save your all Drupal installation: in this case enter /var/www/drupal7/ instead, but this needs more space. Click on "OK".
• Add the same way /var/lib/mysql/ .
• Click on "Close".

Database backup

The disadvantages of /var/lib/mysql/ is that it contains human unreadable files, and, if you later want to migrate your website to a 3^rd party's shared hosting service server, they probably won't allow you to write directly in their /var/lib/mysql/ directory. In order to save your databases in a human readable and "migratable" form:

• Open MySQL Administrator.
• Enter your database username (probably "root") and password.
• In the Catalog, choose the schemata you want to backup and click on "Backup". This will create a .sql file you can read, modify if you know SQL and Drupal, and copy to your hosting service provider's server. This file is a list of directives to MySQL.

Database restoration

• Open MySQL Administrator.
• Enter your database username (probably "root") and password.
• In MySQL administrator, you can see the list of schemata by clicking, in the right up section of MySQL administrator window, on "Catalogs".
• In the same section of the window, click on "Restore backup".
• In the "Backup files to restore" rectangle, choose the restoration file you need (the ".sql" suffix doesn't appear). If it's not there, you look for it thanks to the button "Change the path".
• In the right section of the window, click on the "Selection" tab.
• Asked if you want to restore the schemata into old ones or new ones, make your choice. If the schemata to restore are not already in the "Catalogs", choose to restore them as new shemas ("in a new schema").
• Uncheck the database objects (usually schemas) you don't want to restore.
• In the right bottom corner, click on "Restore backup".
• A dialog will popup: click on "OK".

Responsability and acknowledgements

This page, redacted by Fiable.biz, includes partial copy and update of the author's contribution to How to documentation for creating Drupal 7 multisite configuration from Drupal's multisite group and Local multi-site installation of Drupal from Mandriva wiki. NancyDru and jcl_vanier are also to thank for the latter.

Other ressources

Configuring a basic multisite development environment in Linux
Migrating a site