| Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision |
| playground:playground [2014/01/21 15:22] – chriskeene | playground:playground [2014/01/21 19:29] – [4 Set up a new Solr Core - if required] chriskeene |
|---|
| 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. | 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. |
| |
| ==== Decide on what kind of multi instance you want ==== | |
| | ===== 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: | 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 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 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 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? | * Will your system use directories or hostnames to differentiate different sites? |
| |
| ===== Creating a New Local Configuration Directory ===== | |
| |
| 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 [[customizing_vufind_2.0#Modules|custom code module]] name when prompted: | ===== 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. |
| |
| <code> | <code> |
| </code> | </code> |
| |
| After this, follow the same steps that you did on initial [[installation notes|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 <nowiki>http://my-vufind-server/my-instance-dir/Install/Home</nowiki> and fix all open issues. | 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 [[customizing_vufind_2.0#Modules|custom code module]] name when prompted. |
| |
| ==== Important Notes ==== | 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.: |
| | <code> |
| | sudo ln -s /usr/local/vufind/springfield/httpd-vufind.conf /etc/apache2/conf.d/vufindspringfield |
| | </code> |
| | The location of the Apache config directory will vary on different systems. |
| |
| * 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. | Note: |
| | * 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. |
| * 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. | * 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 ==== | ==== Apache Configuration for Directory-Based Multisite ==== |
| |
| 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. | 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)// |
| |
| Here is a possible workaround: | - Create a symbolic link to the 'public' directory e.g. <code> ln -s $VUFIND_HOME/public $VUFIND_HOME/public-springfield </code> |
| | - 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. <code> |
| * 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)// | Alias /springfield /usr/local/vufind/publicspringfield |
| * 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. | <Directory /usr/local/vufind/publicspringfield/> |
| | </code> |
| | |
| | |
| |
| 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. | Note: 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. |
| |
| ==== Apache Configuration for Host-Based Multisite ==== | ==== Apache Configuration for Host-Based Multisite ==== |
| // 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. // | // 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. // |
| |
| ===== Configuring Your New Instance ===== | ===== 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 notes|installation]]. |
| | |
| | - Restart Apache for the new config to take effect. |
| | - Go to <nowiki>http://my-vufind-server/my-instance-dir/Install/Home</nowiki> 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. |
| | |
| | * Shutdown vufind ($VUFIND_HOME/vufind.sh stop) |
| | * Copy the existing core (usually biblio) under VuFind's solr directory to a new directory of your choice. e.g. <code> |
| | cd $VUFIND_HOME/solr |
| | cp -pr biblio springfield |
| | </code> |
| | * 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 <code>cd springfield; rm -r index</code> |
| | * Edit solr/solr.xml to make the new core active. <code><core name="springfield" instanceDir="springfield"/></code> |
| | * 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 ===== |
| ==== Basic Configuration ==== | ==== Basic Configuration ==== |
| |
| 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. | 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. |
| |
| ===== Sharing (or not sharing) a MySQL Database ===== | ===== 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 [[#Basic Configuration|above]], you can even avoid duplicating credentials in multiple places. | 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 [[#Basic Configuration|above]], you can even avoid duplicating credentials in multiple places. |
| |
| ===== Using Multiple Solr Instances ===== | ==== Using Multiple Solr Instances : Create a New Solr Instance ==== |
| |
| 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: | 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: |
| |
| ==== Option 1: Create New Cores ==== | 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). |
| |
| You can use the existing Solr server but specify different cores within the server. To do this, follow these steps: | 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 [[..:installing_multiple_instances|VuFind 1.x multiple instances documentation]] for some tips; steps 4 and 6 there are still relevant. |
| |
| * Copy the existing core (usually biblio) under VuFind's solr directory to a new directory of your choice. | ===== Example shell transcript of setting up a new instance ===== |
| * Edit solr/solr.xml to make the new core active. | The following example creates a new instance called springfield, with a new Solr core, on server vufindserver as user libadmin. |
| * Edit conf/solrconfig.xml to adjust incorrect paths. | <code> |
| * Configure the default_core setting in the [Index] section of [[..:config.ini]] in your new instance to point to the newly-created core. | libadmin@vufindserver:/etc$ cd $VUFIND_HOME |
| * If using SolrMarc, configure import/import.properties in your [[local settings directory]] to point to the new core. | libadmin@vufindserver:/usr/local/vufind$ php install.php --multisite |
| * 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. | VuFind has been found in /usr/local/vufind. |
| |
| ==== Option 2: Create a New Solr Instance ==== | Where would you like to store your local settings? [/usr/local/vufind/local] springfield |
| |
| 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). | 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. |
| |
| 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 [[..:installing_multiple_instances|VuFind 1.x multiple instances documentation]] for some tips; steps 4 and 6 there are still relevant. | 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 |
| | </code> |
| ---- struct data ---- | ---- struct data ---- |
| ---- | ---- |
| |
