Table of Contents
Installing Multiple Instances
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.
0 Decide on what kind of multi instance you need
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. See the bottom of the page for more information
- Will the new instance have its own Solr Core? The Solr Core holds the searchable bibliographic records, if you want the new instance to search a separate set of records then it will need its own Solr core. See the bottom of the page for other options.
- Will your system use directories or hostnames to differentiate different sites?
1 Creating a New instance and local configuration directory
It is suggested (but not required) that you create a unique string for each multisite, you can use for: the directory/hostname in the url that users will request; configuration directory; etc. This helps keep things consistent and easy to manage. For example if you were setting up an instance specific for your Spingfield branch you could use 'springfield' as your string.
Run the standard install script (used during the original installation) but with the –multisite switch.
cd $VUFIND_HOME php install.php --multisite
This will prompt for the name of a new local settings directory for your instance, (e.g. using the exmaple above, 'springfield'). You will also need to specify a different base path and/or custom code module name when prompted.
At the end it will prompt you to create a symbolic link for your new sites httpd-vufind.conf config file in the Apache directory. E.g.:
sudo ln -s /usr/local/vufind/springfield/httpd-vufind.conf /etc/apache2/conf.d/vufindspringfield
The location of the Apache config directory will vary on different systems.
- 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. The “–multisite” switch is important, as this allows your Apache configuration to properly handle multiple sites. Configuration files from non-multisite VuFind instances can interfere with the functioning of subsequent multisite configurations – be sure they are updated or removed in order to avoid problems when switching to multi-site mode.
- 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.
2 Configure Apache
Apache Configuration for Directory-Based Multisite
This workaround is required for VuFind 2.5 and earlier. Later releases use <Location> sections instead of RewriteBase directives, which eliminates the need for unique symlinks for different instances. You can skip this section for those newer versions.
Due to 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. The following creates a symbolic link to the public directory for each instance of vufind. (In recent versions of Windows, “mklink /D” is equivalent to the Linux “ln -s” command)
- Create a symbolic link to the 'public' directory e.g.
ln -s $VUFIND_HOME/public $VUFIND_HOME/public-springfield
- Edit the httpd-vufind.conf for the new instance, and change the Alias and Directory lines to point to the symbolic link created specifically for that instance. e.g.
Alias /springfield /usr/local/vufind/publicspringfield <Directory /usr/local/vufind/publicspringfield/>
Apache Configuration for Host-Based Multisite
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.
3 Setting up the New Instance
The following steps should work for most setups but you may need to follow the steps that you did on initial installation.
- Restart Apache for the new config to take effect.
- Go to http://my-vufind-server/my-instance-dir/Install/Home and fix all open issues.
- It may report that you need to run 'chown www-data:www-data /usr/local/vufind/springfield/config/vufind' (system usernames and file locations will of course vary) If the 'vufind' folder does not exist you will need to create it.
- The Web interface will not allow you to specify an existing database. If you wish to use the same database as other instances (i.e. one of the decisions listed above) you will need to specify these in the cfg file. If you wish to create a new database you can use either the web interface or the cfg file.
- If you are not ready to configure the ILS Driver at this time (for live holdings availabiluty) select noILS.
4 Set up a new Solr Core - if required
Solr Cores hold the searchable records within VuFind. Follow these steps if you want this instance to search different records to other instances of vufind on your system.
The most common setup, outlined here is an additional core on the existing Solr instance, though there are other options, see further down this page.
- Shut down Solr (see stopping Solr manually)
- Copy the existing core (usually biblio) under VuFind's solr directory to a new directory of your choice. e.g.
cd $VUFIND_HOME/solr cp -pr biblio springfield
- If you don't want your new core to contain the records of the core you just copied from (e.g. biblio), go in to the new directory and delete (or move if you are cautious) the index folder
cd springfield; rm -r index
- Edit solr/solr.xml to make the new core active.
<core name="springfield" instanceDir="springfield"/>
- Edit conf/solrconfig.xml (in the new core directory) to adjust incorrect paths. If you have copied the biblo folder, use your text editor to search for 'biblio' and replace all occurrences (there are about two).
- edit $VUFIND_HOME/<instance_name>/config/vufind/config.ini, change the default_core setting under [index] to use the new core. E.g.: default_core = springfield
- If using SolrMarc (i.e. if you will be importing MARC records in to this instance), configure import/import.properties in your local settings directory to point to the new core.
Important: 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. All cronjobs to import records in to different cores will need to set this variable.
5 Configure your new instance
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.
Further information on MySQL Databases and Solr instances
Sharing (or not sharing) a MySQL Database
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.
Using Multiple Solr Instances : Create a New Solr Instance
The steps above setup a new Solr core in an existing Solr instance, which will probably be suitable for most systems. However another option is to create a New Solr Instance:
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.
Example shell transcript of setting up a new instance
The following example creates a new instance called springfield, with a new Solr core, on server vufindserver as user libadmin.
libadmin@vufindserver:/etc$ cd $VUFIND_HOME libadmin@vufindserver:/usr/local/vufind$ php install.php --multisite VuFind has been found in /usr/local/vufind. Where would you like to store your local settings? [/usr/local/vufind/local] springfield VuFind supports use of a custom module for storing local code changes. If you do not plan to customize the code, you can skip this step. If you decide to use a custom module, the name you choose will be used for the module's directory name and its PHP namespace. What module name would you like to use? [blank for none] What base path should be used in VuFind's URL? [/vufind] /springfield When running multiple VuFind sites against a single installation, youneed to decide how to distinguish between instances. Choose an option: 1.) Directory-based (i.e. http://server/vufind1 vs. http://server/vufind2) 2.) Host-based (i.e. http://vufind1.server vs. http://vufind2.server) or enter 0 to disable multisite mode. Which option do you want? 1 Apache configuration written to /usr/local/vufind/springfield/httpd-vufind.conf. You now need to load this configuration into Apache. You can do it in either of two ways: a) Add this line to your /etc/apache2/httpd.conf file: Include /usr/local/vufind/springfield/httpd-vufind.conf b) Link the configuration to Apache's conf.d directory like this: ln -s /usr/local/vufind/springfield/httpd-vufind.conf /etc/apache2/conf.d/vufind Option b is preferable if your platform supports it, but option a is more certain to be supported. Once the configuration is linked, restart Apache. You should now be able to access VuFind at http://localhost/springfield For proper use of command line tools, you should also ensure that your VUFIND_HOME and VUFIND_LOCAL_DIR environment variables are set to /usr/local/vufind and /usr/local/vufind/springfield respectively. libadmin@vufindserver:/usr/local/vufind$ sudo ln -s /usr/local/vufind/springfield/httpd-vufind.conf /etc/apache2/conf.d/vufind-springfield [sudo] password for libadmin: libadmin@vufindserver:/usr/local/vufind$ ln -s $VUFIND_HOME/public $VUFIND_HOME/public-springfield libadmin@vufindserver:/usr/local/vufind$ vi springfield/httpd-vufind.conf # edited lines: Alias /springfield /usr/local/vufind/publicspringfield # And: Alias /springfield /usr/local/vufind/publicspringfield libadmin@vufindserver:/usr/local/vufind$ sudo /etc/init.d/apache2 restart * Restarting web server apache2 [ OK ] libadmin@vufindserver:/usr/local/vufind$ cd springfield/config/ libadmin@vufindserver:/usr/local/vufind/springfield/config$ mkdir vufind libadmin@vufindserver:/usr/local/vufind/springfield/config$ sudo chown www-data:www-data /usr/local/vufind/springfield/config/vufind libadmin@vufindserver:/usr/local/vufind/springfield/config$ sudo chown www-data:www-data /usr/local/vufind/springfield/cache/ libadmin@vufindserver:/usr/local/vufind/springfield/config$ # go to http://vufindserver.example.com/springfield/Install/Home libadmin@vufindserver:/usr/local/vufind/springfield/config$ $VUFIND_HOME/vufind.sh stop Shutting down VuFind ... STOPPED Tue Jan 21 18:45:55 GMT 2014 libadmin@vufindserver:/usr/local/vufind/springfield/config$ cd $VUFIND_HOME/solr libadmin@vufindserver:/usr/local/vufind/solr$ cp -pr biblio springfield libadmin@vufindserver:/usr/local/vufind/solr$ cd springfield/ libadmin@vufindserver:/usr/local/vufind/solr/springfield$ rm -r index libadmin@vufindserver:/usr/local/vufind/solr/springfield$ cd .. libadmin@vufindserver:/usr/local/vufind/solr$ vi solr.xml libadmin@vufindserver:/usr/local/vufind/solr$ # added <core name="springfield" instanceDir="springfield"/> libadmin@vufindserver:/usr/local/vufind/solr$ vi springfield/conf/solrconfig.xml libadmin@vufindserver:/usr/local/vufind/solr$ # replaced biblio with springfield twice libadmin@vufindserver:/usr/local/vufind/solr$ vi $VUFIND_HOME/springfield/config/vufind/config.ini libadmin@vufindserver:/usr/local/vufind/solr$ # replaced biblio with springfield libadmin@vufindserver:/usr/local/vufind/solr$ vi $VUFIND_HOME/springfield/import/import.properties libadmin@vufindserver:/usr/local/vufind/springfield/import$ # replaced biblio with springfield twice libadmin@vufindserver:/usr/local/vufind/springfield/import$ $VUFIND_HOME/vufind.sh start libadmin@vufindserver:/usr/local/vufind/springfield/import$ # and now to import records libadmin@vufindserver:/usr/local/vufind/springfield/import$ export VUFIND_LOCAL_DIR=/usr/local/vufind/springfield libadmin@vufindserver:/usr/local/vufind/springfield/import$ cd $VUFIND_HOME libadmin@vufindserver:/usr/local/vufind$ ./import-marc.sh testfile.mrc