Differences

This shows you the differences between two versions of the page.

--- installation:vagrant [2017/08/02 19:39] – demiankatz
+++ installation:vagrant [2024/02/08 18:23] (current) – [Getting Started] demiankatz
@@ Line 1: / Line 1: @@
 ====== Vagrant ======
-[[http://www.vagrantup.com/|Vagrant]] is a tool for managing consistent development environments. While it is not intended for production use, VuFind developers may find it helpful for quickly setting up a VuFind system, and it may also be useful for evaluation purposes.
+[[http://www.vagrantup.com/|Vagrant]] is a tool for managing consistent development environments. While it is not intended for production use, VuFind® developers may find it helpful for quickly setting up a VuFind® system, and it may also be useful for evaluation purposes.
 ===== Getting Started =====
-Starting with VuFind 4.1, the software ships with a default Vagrantfile that will get an instance of VuFind running on an Ubuntu image.
+The software ships with a default [[https://github.com/vufind-org/vufind/blob/dev/Vagrantfile|Vagrantfile]] that will get an instance of VuFind® running on an Ubuntu image (since release 4.1).
-To get started, make sure that [[http://www.vagrantup.com/|Vagrant]] is installed on your system, then simply go to the VuFind directory and run:
+==== Setting Up the Virtual Machine ====
+To get started, make sure that [[http://www.vagrantup.com/|Vagrant]] is installed on your system, then simply go to your VuFind® directory (preferably a fresh, clean checkout from [[development:recommended_tools:git|Git]] with Composer dependencies already installed, if you're just getting started) and run:
   vagrant up
-The first time you run this, it will take quite some time to install and set up everything. Once the installation completes, VuFind will be visible on the host machine's port 4567, so you can access it with <nowiki>http://localhost:4567/vufind</nowiki>.
+This will take quite some time to install and set up everything. Once the installation completes, VuFind®'s web interface will be visible on the host machine's port 4567.
-To log into the virtual machine to run commands, you can execute
+You will have to do a bit of manual work to get everything running....
+=== Completing the Installation ===
+Access the web-based installation process at <nowiki>http://localhost:4567/vufind/Install</nowiki> to finalize configuration and initialize the database. Note that the MySQL root password is "root" on the test box (:!: this is obviously not secure; the VM is intended only for development purposes).
+=== Managing Solr and Indexing Records ===
+To log into the virtual machine to run commands, you can execute:
   vagrant ssh
-Note that your host machine's VuFind directory will be mounted within the Vagrant SSH session as /vagrant. Any changes you make there will affect your host machine as well (and vice versa).
+You will need to run:
+  cd $VUFIND_HOME; ./solr.sh start
+to get Solr running for the first time. You can then use the standard ./import-marc.sh script to index records into your test instance.
+If you want to view Solr in a web browser on your host machine, it should be port-mapped to port 4568, so you can view the admin at <nowiki>http://localhost:4568/solr</nowiki>.
+== Notes for Windows Users ==
+:!: For Windows users, the ''solr.sh'' and ''import-marc.sh'' may fail to start with a "bad interpreter" error.  This is caused by the files being on the host Windows system with DOS file encoding, despite running within the Vagrant Linux environment (via a synced folder).  To resolve this, [[https://stackoverflow.com/a/5514351|set each *.sh file's encoding to unix format]].
+:!: Windows users may also encounter errors about the inability to create symbolic links (especially when indexing MARC records). This problem is caused by permission issues related to symlink creation and can be worked around by running Vagrant from a command prompt with administrative rights. If you continue to have problems after correcting permissions, make sure you do not have an empty directory at $VUFIND_HOME/solr/vendor/.solrj -- a partially created SolrJ symlink collection can break the indexer; simply remove $VUFIND_HOME/solr/vendor/.solrj and try import again, and things should work.
+==== Notes on File Mapping / Locations ====
+Your host machine's VuFind® directory will be mounted within the Vagrant SSH session as /vagrant. Any changes you make there will affect your host machine as well (and vice versa).
+Because Apache does not have write access to the special mounted /vagrant directory, the system is using /vufindlocal as its $VUFIND_LOCAL_DIR; these files are only accessible from within the VM. You will have to use "vagrant ssh" to log in and examine/modify them.
+==== Managing the Virtual Machine ====
-When you are finished, you can use "vagrant suspend," "vagrant halt" or "vagrant destroy" depending on how permanently you wish to stop the machine. You can always reactivate it with "vagrant up" again later.
+Once everything is set up, you can issue a few commands to control the VM:
-===== Other Options =====
+  * vagrant suspend - save the current state of the VM, but stop it from running until you issue "vagrant up" again.
+  * vagrant halt - shut down the VM; it will boot back up the next time you issue "vagrant up".
+  * vagrant destroy - completely destroy the VM; you will have to reinstall it (see above) if you want it back.
-If you are on a version of VuFind older than 4.1, or if you want to explore other options, here are some other VuFind/Vagrant options:
-  * Mark A. Duffy has contributed a VuFind 2.x Vagrant configuration [[https://vagrantcloud.com/markaduffy/vufind_2x|on this page]].
-  * An alternative, puppet-configured option that runs directly off a clone of the VuFind 2.x git repository
-is available [[https://github.com/quartsize/vufind-vagrant|here]].
 ---- struct data ----
+properties.Page Owner :
 ----