An introduction to the simplest options for quickly installing VuFind®: the .deb package and Vagrant.

Video is available as an mp4 download or through YouTube.

Music is “Local Forecast” by Kevin Macleod. This song is permitted for commercial use under a Creative Commons Attribution 3.0 Unported License (CC BY 3.0) http://www.orangefreesounds.com/elevator-music/ https://creativecommons.org/licenses/by/3.0/

1. Installation wiki page

So this video is designed to show a couple of quick ways to get VuFind up and running for evaluation and development, but before I get into that I just wanted to highlight the fact that on the VuFind website and vufind.org if you go to documentation and scroll down to installation you will find detailed guides for installing VuFind on a variety of platforms and some more specialized topics, so if there's anything that you don't follow in this video, be sure to take a look at the documentation and hopefully that will clear things up, and if the documentation is unclear you can also always go to the support section of the website and reach out on slack or one of our mailing lists and we will be happy to help you.

So the first method of installation that I'm going to demonstrate is installing from a debian package which is probably the easiest way to get a running instance of VuFind in sort of a realistic environment. So what I have done as preparation for this demonstration is I have installed Ubuntu 19 on a virtual machine so I just have a blank Ubuntu installation and I've installed all of the latest patches so when I log in I have just opened a terminal window and if you were to look at the documentation on the website you would see that the first step is to wget the VuFind debian package from github. I have already done that so that you don't have to watch my progress bar. So once you have downloaded the debian package installing it is simply a matter of saying “sudo dpkg -i” and the file name which will start the installation process.

It takes a moment to unpack and you will see that when it is done it's going to display a whole bunch of scary-looking error messages which we actually expect to see, so do not be put off by that. The error messages are going to show up because this package has some dependencies that haven't been installed yet, and it will just take an additional step to resolve those dependencies. So now we can play the elevator music and in post we can edit out this long stretch of nothing happening. Go on virtual machine, you can do it! Ah, there we go, there is our screen full of error messages. So now in order to install all of these dependencies we just need to say “sudo apt-get install -f” and that will cause all of the missing things to get installed, and then we confirm that yes we do want to install all of this stuff, and now again we need to just watch some installation occurring. So we are in the very final stages of installation. Apache has been restarted, a few last-minute things are occurring, and VuFind has automatically set up its own default configuration. So now we are back at the command prompt and VuFind is now installed and running but there are still just a couple of things that we need to do.

One thing that the installation process has done is it has set up a couple of helpful environment variables for us in the profile file, but that will not have automatically loaded yet, so we could either leave the terminal and start a new one or we can say “source /etc/profile” to reload the profile, and now I have an environment variable called the $VUFIND_HOME which just contains the location of the VuFind directory so if I switch there I can now run “solr.sh start” to start the Solr index which VuFind uses for storing records, though at this point it will be completely empty. The other thing that we need to do at this point and this is specific to Ubuntu 18 and newer is we need to do some setup of the MySQL database so that VuFind's web-based installation process can work correctly. In these newer versions of Ubuntu by default MySQL is configured so that it only allows you to access the root user based on your login rather than using actual MySQL credentials, so we need to reconfigure that. So we are going to go “sudo mysql -u root” to login as the root user and then we are going to say “UPDATE mysql.user SET plugin='mysql_native_password' WHERE User='root';” We're going to “FLUSH PRIVILEGES;” to make all those changes take effect and we are going to quit. We can now run the standard “/usr/bin/mysql_secure_installation” script to setup MySQL the way we want it for now. I'm not going to install the validate password plug-in. I'm going to set a root password that I will remember. I'm going to clean up the anonymous users. We don't need to login as root from off the box, so I'm going to disable remote root login. I'm going to clean up test data and reload privilege tables so I now have a nice simple MySQL set up that will allow VuFind to set up the database for me. If I had not wanted to do this and wanted to keep those default settings there are ways around that which I will briefly mention, but this just makes this demonstration a little easier and the documentation that I pointed out at the beginning of this video contains all the details on how to do this for different combinations of Ubuntu and MySQL or MariaDB since each one has its own quirks. This is probably the hardest part of the installation process in this environment.

But anyway now that all of this stuff is done at the command line, I can open up my web browser and I should be able to finish the VuFind installation using the web-based installation process by just going to “http://localhost/vufind/Install” and this gives me a status display on the various aspects of VuFind so we can just click these fix buttons one by one to sort everything out. So by default if VuFind has no configuration file setup when we click “fix” here it automatically creates an initial configuration. We can then navigate back to auto configure and this is back to an okay status now we can go to fix the database. This is how we create our initial VuFind database. I'm going to make up a password for a VuFind specific user so that after this initial account is set up we no longer use root credentials to connect VuFind to MySQL but in order to do this initial setup I need to enter here the root password that I set up when I did the MySQL secure installation and you'll notice that there is a skip button here. If I were to click this instead of submitting the form I would get a list of SQL commands that I could run manually which is one way that you can get VuFind set up without granting root access to Apache but I'm just gonna do this the simple way for now and we can now see database is showing as okay.

I'm also going to click the fix button next to security which establishes some random keys in the configuration file that will be used for hashing for security purposes, and at this stage I'm not going to bother fixing the ILS because for this demo I don't have an integrated library system to connect to but if you do have an ILS this gives you the opportunity to choose which one you're using and it will establish a configuration file that you can edit with additional details, but at this point I now have a working instance of VuFind, it just doesn't have any records in it and we will talk about loading records into VuFind in a future call, so that's the end of the demo for setting up VuFind using a Debian package.

But another scenario that is often useful to be able to deal with is being a developer working with the code and wanting to very quickly get a test instance of VuFind up to do some experiments with without risking doing damage to your local box and in that situation a really useful tool is vagrant which is a way of automating the creation and management of virtual machines. VuFind ships with a default vagrant configuration that will get you a test server in just a couple of commands, so I'm going to demonstrate how that works as well.

I'm just going to connect to my test server using SSH and I will make my font bigger so that you can see it all right. So I'm going to do this absolutely from the ground up, so I'm going to go to my temp directory and I am just going to “git clone https://github.com/vufind-org/vufind” I'm going to clone a brand new fresh copy of VuFind just to show you that you don't need any extra things except the VuFind code itself. You just need to have git installed so you can clone the code and you need to have vagrant installed so that you can run vagrant. Installing vagrant is beyond the scope of this video but it's generally just a matter of installing a package from your package manager and possibly going into your computer's bios and enabling some virtualization settings, but if you do the good old “google the error message” trick you should be able to get vagrant running fairly painlessly. So anyway I've now just cloned VuFind into a new VuFind directory so I'm going to “cd” into that and all I need to do to get everything running is say “vagrant up” which is going to read the Vagrantfile that ships with VuFind and download a bunch of things.

So the way vagrant works is there are existing machine images that you can access and so you can specify a base image and then layer some commands on top of it, so for VuFind we're currently using the Ubuntu Bionic64 base image and then we have some scripting that will do the whole VuFind installation on top of that. So right now vagrant is just booting up its clone of the Bionic 64 image which will take a few moments. We're probably going to need to fast forward some of this part of the video as well and once the machine is all booted up it will run updates to get all of the latest packages and then it will run more or less the same installation process that the debian package had. So now we've reached the point where we're running the update scripts. Alright, so we've now moved on to the point where we are installing VuFind's dependencies. The updates are all installed. Now we are running “composer install” to get all of the PHP dependencies that did not download with the git repository automatically. Now we're downloading an installing Solr and we're done. So with just two command lines, one to clone the repository, one to start vagrant, and then quite a bit of patience we now have an instance of VuFind running inside a virtual machine on our server and what vagrant does that's really useful is it does both port and directory mapping so our current directory /tmp/vufind is actually mapped inside the virtual machine as the /vagrant directory and the virtual machine's web ports are mapped to different port numbers on the local machine so that we can see them. I'll demonstrate this first by using the “vagrant ssh” command which is how you get into the virtual machine. This will actually put me at a command prompt inside the VM.

So I'm now in the virtual machine and if I go to $VUFIND_HOME, which you will recall is the environment variable that takes you to the directory containing the VuFind installation, it puts me in /vagrant and if I do an “ls” I will see that this is actually the same thing that on the host machine is /tmp/vufind. While I'm here I'm gonna run “solr.sh start” to start up the Solr index because that does not start by default and VuFind is going to expect to see that, and now what I'm going to do while that begins is bring up a web browser because as I mentioned there was some port mapping taking place and in this instance we've mapped the HTTP port on the virtual machine to port 4567 on the host machine so if I just go to VuFind test which is the name of my test server colon 4 5 6 7 slash vufind slash Install, then I should get the same installation dialog box that I got when I installed from the Debian package and so this is me on my laptop accessing a virtual machine running on my test server that's being port proxied through the test server. So as before, I can fix the basic configuration, go back to the auto configure screen. I can setup the database and in the vagrant configuration the database root password is just automatically set for you to root which is obviously not secure but this is a disposable test environment so we don't particularly care about its security. Well usually you would set this up to test something for a few minutes and then destroy it again and it's all sandboxed inside a VM anyway. I'll do my security fix and now just as with the other installation method I have a fully functional running instance of VuFind, it just doesn't have any records yet so as I mentioned this is all documented in the VuFind wiki. There's a page under installation for vagrant that tells you about these port mappings and reminds you about what the root password is and also summarizes some other useful vagrant commands which I will go over really quickly.

So I'm going to exit out of my vagrant VM. I'm now back on the host machine prompt I can say “vagrant suspend” and what this will do is it will save the state of my virtual machine and stop it from running but it will create an image of the exact place it was when it was running so that the next time I type “vagrant up” it will resume from exactly the point where I was and it's not going to have to rebuild and reinstall everything, so this is useful if you're doing some work on the VM and then you need to stop and you don't want to be using up all of the memory and resources that virtualization takes on your server. You can turn it off but get back to where you were left. You can also say “vagrant halt” which is a little bit stronger than “vagrant suspend.” This is actually going to send a shutdown signal to the VM which will cause it to power down, and then the next time you say “vagrant up” it'll take a little bit longer because it's actually going to boot the whole box and if you have had processes running that don't automatically start you would have to “vagrant ssh” back in again and start them up. I'm not going to demonstrate that now for the sake of time. And when you're completely done if you want to free up all of the resources you can say “vagrant destroy” and it will ask for confirmation and when you confirm that it will delete all of the stuff related to the VM, free up all of your resources, and if you say “vagrant up” again you'll have to go through the whole installation process again. So as I say, vagrant is useful for getting a test instance up and running in a minimum of steps. It's useful for creating a disposable test where you can try things and not worry about hurting anything. It's also useful if you want to roll back and see how VuFind was at past points in time. We've had this vagrant configuration since VuFind 4.1, so if you check out older version tags and do “vagrant up” you'll get running instances of VuFind representing different points in time, which can be useful for example if you're trying to track down where a bug was created.

So that's all I had for today I hope at least some of this was interesting and I hope it will be more interesting when we do the video editing. Did anyone have anything they wanted to add to this: suggestions for next time, questions, etc.?