Start of possible revised multi instance page.

This page refers to VuFind 2.x; for similar notes related to earlier versions, see this page.

There are a few reasons you might want to have several instances of VuFind. Two real-life examples:

• You need to present the same index in slightly different ways at different URLs (i.e. filter differently or offer different themes for members of a consortium)
• You use VuFind as the basis for several distinct, separate systems running on the same server (i.e. a bibliography project distinct from your library catalog)

Regardless of your use case, you probably do not need to actually install multiple copies of VuFind. VuFind 2's flexible configuration options allow you to create multiple configurations for a single instance.

Vufind has been designed to allow much of the configuration (including theme choice) to be set per instance, while allowing those options unchanged to be inherited from the main configuration. There are a few things you will need to decide upfront when setting up a new instance:

• Will the new instance use the same database as other instances, or have its own? The database stores users, favorites and tags, so the question really comes down to if you want the new instance to have the same users and tags as existing instances, or to have its own.
• Will the new instance have it's own Solr Core. The Solr Core holds the searchable bibliographic records, if you want the new instance to search a seperate set of records then it will need it's own core.
• Will your system use directories or hostnames to differentiate different sites?

Creating a new configuration is simple. Just run the same install.php script that you used when you first installed VuFind, but specify a different local settings directory, base path and/or custom code module name when prompted:

cd $VUFIND_HOME
php install.php --multisite

After this, follow the same steps that you did on initial installation – link up your Apache configuration, then go to the install script for your new instance in a web browser using a URL similar to http://my-vufind-server/my-instance-dir/Install/Home and fix all open issues.

• Using the “–multisite” switch on install.php is important, as this allows your Apache configuration to properly handle multiple sites. If you have already installed a copy of VuFind in single site mode, you need to reconfigure it by re-running install.php with the –multisite switch in order to generate a multisite-capable Apache configuration.
• Windows users should be aware that running install.php creates a new “vufind.bat” file every time. This vufind.bat file is used to set up the environment variables for other VuFind-related scripts like import-marc.bat. If you are using custom import rules, this can affect where SolrMarc looks for your settings. Be sure to adjust vufind.bat as needed to ensure correct importing.

Because of the way VuFind's current default configuration uses the RewriteBase directive, having multiple VuFind configurations that all point to the same directory in their <Directory> sections prevents multisite VuFind instances from loading correctly.

Here is a possible workaround:

• For each instance of VuFind, create a new symbolic link to the public directory; i.e. “ln -s $VUFIND_HOME/public $VUFIND_HOME/public-instance1”. (In recent versions of Windows, “mklink /D” is equivalent to the Linux “ln -s” command)
• Edit the httpd-vufind.conf file in each local configuration directory, and change the Alias and Directory lines to point to the symbolic link created specifically for that instance.

This is not ideal – there should be a way to make the configuration work without duplication of the public directory. However, until a better solution is found, this workaround will allow directory-based VuFind multisites to operate.

If you are pointing multiple hostnames at a single server and using these to distinguish between VuFind instances, you can't simply link up the httpd-vufind.conf configurations generated by install.php. Instead, you also need to set up virtual hosts. Here is an example virtual host configuration for Apache, assuming hostnames of test1 and test2 and local settings directories of ms1 and ms2:

<VirtualHost *:80>
    ServerName test1
</VirtualHost>

Include /usr/local/vufind2/ms1/httpd-vufind.conf

<VirtualHost *:80>
    ServerName test2
</VirtualHost>

Include /usr/local/vufind2/ms2/httpd-vufind.conf

Note that when you restart Apache after adding these settings (either by editing httpd.conf or by putting a new file in Apache's conf.d directory), you will see a warning about overlapping Alias settings. This is harmless.

In some Linux distributions, it may be necessary to put the Include statements inside the <VirtualHost> blocks – this was reported as an issue with RHEL5.

If your new instance is configured almost exactly like your previous instance but with a few minor modifications, consider using the [Parent_Config] section of config.ini to inherit settings from a shared base configuration. This will make maintenance easier over time. The [Parent_Config] section is supported by all of VuFind's .ini files, so you can use this technique on any files that need to be customized.

If you need to write code that is specific to a particular instance, or if you need to customize code in different ways for different instances, you just need to create a separate module for each instance. This is handled for you by install.php. See the custom code module page for more details on populating your newly created module.

VuFind's theme is determined by config.ini settings. Since each instance of VuFind has its own config.ini in its local settings directory, you can easily configure separate themes for separate instances. Since themes can inherit from one another, it is possible to create a base theme for shared customizations and isolate minor, distinctive changes to very small, instance-specific themes. See customizing the user interface for more details.

If you simply create a new instance with install.php and the web-based install script, VuFind will attempt to create a separate MySQL database for each instance. This may be desirable if each instance has its own distinct user base and tags/favorites should not flow between instances. However, it is more common that you will want to share a database. In this situation, just manually copy the database settings from your original instance's config.ini file into the new instance instead of using the “fix” link in the automatic installer. If you use a shared base configuration as suggested above, you can even avoid duplicating credentials in multiple places.

If you need completely separate indexes for different instances of VuFind, you may need to set up a duplicate copy of Solr. There are two possible approaches:

You can use the existing Solr server but specify different cores within the server. To do this, follow these steps:

• Copy the existing core (usually biblio) under VuFind's solr directory to a new directory of your choice.
• Edit solr/solr.xml to make the new core active.
• Edit conf/solrconfig.xml to adjust incorrect paths.
• Configure the default_core setting in the [Index] section of config.ini in your new instance to point to the newly-created core.
• If using SolrMarc, configure import/import.properties in your local settings directory to point to the new core.
• When indexing, make sure that the VUFIND_LOCAL_DIR environment variable points to the correct configuration so that records are sent to the appropriate place.

Creating a new core usually makes more sense than creating a copy of Solr, but if your index is too large to fit on a single server, you could also copy VuFind's Solr index and startup script to another server, and reconfigure your instance to point there (using the url setting in the [Index] section of config.ini and, if necessary, the solr.path = REMOTE and solr.hosturl settings of SolrMarc's import.properties file).

It probably does not make sense to try to run two separate instances of Solr on a single server, but if you have a good reason to do this, refer to the old VuFind 1.x multiple instances documentation for some tips; steps 4 and 6 there are still relevant.